API Web Com o ASP - Net Core

Contents
Visão geral
Sobre o ASP.NET Core
Comparar o ASP.NET Core e o ASP.NET
Comparar o .NET Core e o .NET Framework
Introdução
Tutoriais
Aplicativos Web
Páginas do Razor
Com o Visual Studio
Com o Visual Studio Code
Com o Visual Studio para Mac
MVC
Com o Visual Studio
APIs da Web
Com o Visual Studio
Para aplicativos móveis nativos
Aplicativos Web em tempo real
SignalR com JavaScript
SignalR com TypeScript
Acesso aos dados
EF Core com Razor Pages
EF Core com MVC, BD existente
EF Core com MVC, BD novo
EF Core com MVC, tutorial longo
Princípios básicos
Visão geral
Inicialização do aplicativo
Injeção de dependência (serviços)
Roteamento
Vários ambientes
Configuração
Opções
Registro em log
Tratar erros
Middleware
Visão geral
Middleware de fábrica
Middleware baseado em fábrica com contêiner de terceiros
Host
Visão geral
Host da Web
Host Genérico
Servidores
Visão geral
Kestrel
Módulo do ASP.NET Core
HTTP.sys
Iniciar solicitações HTTP
Aplicativos Web
Páginas do Razor
Visão geral
Tutoriais
Razor Pages com Visual Studio
Visão geral
Introdução
Adicionar um modelo
Scaffolding
SQL Server
Atualizar as páginas
Adicionar pesquisa
Adicionar um novo campo
Adicionar validação
Razor Pages com Visual Studio Code
Visão geral
Introdução a Páginas do Razor
Adicionar um modelo
Páginas do Razor geradas por scaffolding
Trabalhar com SQLite
Adicionar pesquisa
Razor Pages com Visual Studio para Mac
Visão geral
Adicionar um modelo
Páginas do Razor geradas por scaffolding
Adicionar pesquisa
Filtros
Bibliotecas de classes
Convenções de aplicativo e roteamento
Carregar arquivos
SDK do Razor
MVC
Visão geral
Tutoriais
MVC com Visual Studio
Visão geral
Introdução
Adicionar um controlador
Adicionar uma exibição
Adicionar um modelo
Trabalhar com o SQL Server
Exibições e ações do controlador
Adicionar pesquisa
Examinar os métodos Details e Delete
MVC com Visual Studio Code
Visão geral
Introdução
Adicionar um modelo
Exibições e métodos do controlador
Adicionar pesquisa
MVC com Visual Studio para Mac
Visão geral
Introdução
Adicionar um modelo
Exibições e métodos do controlador
Adicionar pesquisa
Exibições
Exibições parciais
Controladores
Roteamento
Uploads de arquivo
Injeção de dependência – controladores
Injeção de dependência – exibições
Teste de unidade
Estado de sessão e de aplicativo
Auxiliares de Marca
Visão geral
Criar auxiliares de marcação
Usar auxiliares de marcação em formulários
Componentes do Auxiliar de Marca
Auxiliares de marcação internos
Âncora
Cache
Cache distribuído
Ambiente
Formulário
Image
Entrada
Rótulo
Parcial
Selecionar
Área de texto
Mensagem de validação
Resumo de validação
Layout
Arquivos estáticos
Model binding
Validação de modelo
Sintaxe Razor
Avançado
Exibir componentes
Exibir compilação
Modelo de aplicativo
Filtros
Áreas
Partes do aplicativo
Model binding personalizado
Compatibilidade de versões
APIs da Web
Visão geral
Tutoriais
API Web com o Visual Studio
API Web com o Visual Studio Code
API Web com o Visual Studio para Mac
API Web para aplicativos móveis nativos
Swagger/OpenAPI
Visão geral
Introdução ao Swashbuckle
Introdução ao NSwag
Tipos de retorno de ação
Formatar dados de resposta
Formatadores personalizados
Aplicativos em tempo real
Visão geral
Plataformas compatíveis
Tutoriais
SignalR com JavaScript
SignalR com TypeScript
Conceitos de servidor
Hubs
HubContext
Usuários e Grupos
Publicar no Azure
Clientes
Cliente .NET
Referência da API REST
Cliente Java
Referência de API Java
Cliente JavaScript
Referência de API JavaScript
WebPack e TypeScript
Configuração
Autenticação e autorização
Considerações sobre segurança
Protocolo de Hub do MessagePack
Streaming
Comparar o SignalR e o SignalR Core
WebSockets sem SignalR
Testar, depurar e solucionar problemas
Teste de unidade
Testes de unidades de páginas Razor
Controladores de teste
Depuração remota
Depuração de instantâneo
Depurando de instantâneo no Visual Studio
Testes de integração
Solução de problemas
Acesso aos dados
Tutoriais
EF Core com Razor Pages
Visão geral
Introdução
Criar, ler, atualizar e excluir
Classificar, filtrar, paginar e agrupar
Migrações
Criar um modelo de dados complexo
Ler dados relacionados
Atualizar dados relacionados
Tratar conflitos de simultaneidade
EF Core com MVC, BD novo
EF Core com MVC, BD existente
EF Core com MVC, tutorial longo
Visão geral
Introdução
Criar, ler, atualizar e excluir
Classificar, filtrar, paginar e agrupar
Migrações
Criar um modelo de dados complexo
Ler dados relacionados
Atualizar dados relacionados
Tratar conflitos de simultaneidade
Herança
Tópicos avançados
EF 6 com ASP.NET Core
Armazenamento do Azure com o Visual Studio
Serviços conectados
Armazenamento de Blobs
Armazenamento de filas
Armazenamento de tabelas
Desenvolvimento do lado do cliente
Visão geral
Gulp
Grunt
LibMan
Visão geral
CLI
Visual Studio
Bower
LESS, Sass e Font Awesome
Agrupar e minificar
Link do navegador
Aplicativos de página única
Visão geral
Angular
React
React com Redux
JavaScriptServices
Hospedagem e implantação
Visão geral
Hospedar no Serviço de Aplicativo do Azure
Visão geral
Publicar com o Visual Studio
Publicar com as ferramentas da CLI
Publicar com Visual Studio e Git
Implantação contínua com o Azure Pipelines
Solucionar problemas de inicialização
DevOps
Visão geral
Ferramentas e downloads
Implantar no Serviço de Aplicativo
Integração contínua e implantação
Monitorar e solucionar problemas
Próximas etapas
Hospedar no Windows com o IIS
Visão geral
Solução de problemas no IIS
Referência do Módulo do ASP.NET Core
Suporte ao IIS no Visual Studio
Módulos do IIS
Hospedar em um serviço Windows
Hospedar em Linux com o Nginx
Hospedar em Linux com o Apache
Hospedar no Docker
Visão geral
Compilar imagens do Docker
Ferramentas do Visual Studio
Publicar em uma imagem do Docker
Configuração de balanceador de carga e de proxy
Hospedar em uma web farm
Perfis de publicação do Visual Studio
Estrutura de diretórios
Referência de erros para o Serviço de Aplicativo do Azure e o IIS
Segurança e identidade
Visão geral
Autenticação
Introdução ao Identity
Identidade Scaffold
Adicionar dados de usuário personalizados à Identidade
Personalizar Identidade
Opções de autenticação de OSS da comunidade
Configurar o Identity
Configurar a Autenticação do Windows
Provedores de armazenamento personalizados para o Identity
Provedores externos
Visão geral
Autenticação do Facebook
Autenticação do Twitter
Autenticação do Google
Autenticação da Microsoft
Outros provedores de autenticação
Declarações adicionais
Autenticação de Web Services Federation
Confirmação de conta e recuperação de senha
Habilitar a geração de código QR no Identity
Autenticação de dois fatores com SMS
Usar a autenticação de cookie sem o Identity
Azure Active Directory
Visão geral
Integrar o Azure AD em um aplicativo Web
Integrar o Azure AD B2C em um aplicativo Web
Integrar o Azure AD B2C em uma API Web
Chamar uma API Web do WPF
Chamar uma API Web em um aplicativo Web usando o Azure AD
Proteger aplicativos ASP.NET Core com o IdentityServer4
Proteger aplicativos ASP.NET Core com a Autenticação do Serviço de Aplicativo do
Azure (autenticação fácil)
Contas de usuários individuais
Autorização
Visão geral
Criar um aplicativo Web com autorização
Convenções de autorização de Páginas Razor
Autorização simples
Autorização baseada em função
Autorização baseada em declarações
Autorização baseada em política
Provedores da política de autorização
Injeção de dependência em manipuladores de requisitos
Autorização baseada em recursos
Autorização baseada em exibição
Limitar a identidade por esquema
Proteção de dados
Visão geral
APIs de Proteção de Dados
APIs de consumidor
Visão geral
Cadeias de caracteres de finalidade
Multilocação e hierarquia de finalidade
Senhas hash
Limitar o tempo de vida de cargas protegidas
Desproteger cargas cujas chaves foram revogadas
Configuração
Visão geral
Configurar a proteção de dados
Configurações padrão
Política ampla de computador
Cenários sem reconhecimento de DI
APIs de extensibilidade
Visão geral
Extensibilidade da criptografia básica
Extensibilidade de gerenciamento de chaves
APIs diversas
Implementação
Visão geral
Detalhes de criptografia autenticada
Derivação de subchaves e criptografia autenticada
Cabeçalhos de contexto
Gerenciamento de chaves
Provedores de armazenamento de chaves
Criptografia de chave em repouso
Imutabilidade de chave e configurações
Formato do armazenamento de chaves
Provedores de proteção de dados efêmeros
Compatibilidade
Visão geral
Substitua <machineKey> no ASP.NET
Proteger segredos no desenvolvimento
Impor o HTTPS
Compatível com o RGPD (Regulamento Geral sobre a Proteção de Dados) da UE
Provedor de configuração do Azure Key Vault
Falsificação antissolicitação
Prevenir ataques de redirecionamento abertos
Evitar scripts entre sites
Habilitar o CORS (Solicitações Entre Origens)
Compartilhar cookies entre aplicativos
Lista segura de IP
Outros tópicos
Globalização e localização
Localização do objeto portátil com o Orchard Core
Reescrita de URL
Provedores de arquivo
Recursos de solicitação
Acessar o HttpContext
Alterar tokens
OWIN (Open Web Interface para .NET)
Tarefas em segundo plano com serviços hospedados
Aprimorar um aplicativo de um assembly externo
Metapacote Microsoft.AspNetCore.App
Metapacote Microsoft.AspNetCore.All
Fazendo log com o LoggerMessage
Usar um inspetor de arquivo
Respostas de cache
Visão geral
Cache na memória
Cache distribuído
Cache de resposta
Middleware de cache de resposta
Compactação de resposta
Migração
2.0 a 2.1
1.x a 2.0
Visão geral
Autenticação e identidade
ASP.NET para ASP.NET Core
Visão geral
MVC
API Web
Configuração
Autenticação e identidade
ClaimsPrincipal.Current
Associação de identidade
Módulos HTTP para middleware
O que há de novo
Novidades no 2.1
Novidades no 2.0
Novidades no 1.1
Referência de API
Contribuir
Introdução ao ASP.NET Core
01/11/2018 • 6 minutes to read • Edit Online
Por Daniel Roth, Rick Anderson e Shaun Luttin

O ASP.NET Core é uma estrutura de software livre, de multiplaforma e alto desempenho para a criação de
aplicativos modernos conectados à Internet e baseados em nuvem. Com o ASP.NET Core, você pode:
Compilar aplicativos e serviços Web, aplicativos IoT e back-ends móveis.
Usar suas ferramentas de desenvolvimento favoritas no Windows, macOS e Linux.
Implantar na nuvem ou local.
Executar no .NET Core ou no .NET Framework.
Por que usar o ASP.NET Core?

Milhões de desenvolvedores usaram (e continuam usando) o ASP.NET 4.x para criar aplicativos Web. O ASP.NET
Core é uma reformulação do ASP.NET 4.x, com alterações de arquitetura que resultam em uma estrutura mais
enxuta e modular.
O ASP.NET Core oferece os seguintes benefícios:
Uma história unificada para a criação da interface do usuário da Web e das APIs Web.
Projetado para possibilidade de teste.
O Razor Pages torna a codificação de cenários focados em página mais fácil e produtiva.
Capacidade de desenvolver e executar no Windows, macOS e Linux.
De software livre e voltado para a comunidade.
Integração de estruturas modernas do lado do cliente e fluxos de trabalho de desenvolvimento.
Um sistema de configuração pronto para a nuvem, baseado no ambiente.
Injeção de dependência interna.
Um pipeline de solicitação HTTP leve, modular e de alto desempenho.
A capacidade de hospedar no IIS, Nginx, Apache, Docker ou hospedar em seu próprio processo.
Controle de versão do aplicativo do lado a lado ao direcionar .NET Core.
Ferramentas que simplificam o moderno desenvolvimento para a Web.
Compilar APIs Web e uma interface do usuário da Web usando o

ASP.NET Core MVC
O ASP.NET Core MVC fornece recursos que ajudam você a compilar APIs Web e aplicativos Web:
O padrão MVC (Model-View -Controller) ajuda a tornar as APIs Web e os aplicativos Web testáveis.
As Páginas Razor (novidade no ASP.NET Core 2.0) é um modelo de programação baseado em página que
torna a criação da interface do usuário da Web mais fácil e produtiva.
A marcação Razor fornece uma sintaxe produtiva para Páginas Razor e as Exibições do MVC.
Os Auxiliares de Marcação permitem que o código do servidor participe da criação e renderização de
elementos HTML em arquivos do Razor.
O suporte interno para vários formatos de dados e negociação de conteúdo permite que as APIs Web
alcancem uma ampla gama de clientes, incluindo navegadores e dispositivos móveis.
O model binding mapeia automaticamente os dados de solicitações HTTP para os parâmetros de método de
ação.
A Validação de Modelos executa automaticamente a validação no lado do cliente e do servidor.

ASP.NET Core integra-se perfeitamente com estruturas conhecidas do lado do cliente e bibliotecas, incluindo
Angular, React e Bootstrap. Para saber mais, consulte Desenvolvimento do lado do cliente.
ASP.NET Core direcionado para o .NET Framework

O ASP.NET Core pode ser direcionado para o .NET Core ou ao .NET Framework. Os aplicativos do ASP.NET
Core direcionados ao .NET Framework não são multiplataforma,— são executados somente no Windows. Não
existem planos para interromper o suporte ao direcionamento para .NET Framework no ASP.NET Core. Em geral,
o ASP.NET Core é composto de bibliotecas do .NET Standard. Aplicativos criados com o .NET Standard 2.0 são
executados em qualquer lugar com suporte para ele.
O ASP.NET Core 2.x dá suporte para as versões do .NET Framework compatíveis com o .NET Standard 2.0:
O .NET Framework 4.7.1 e versões posteriores são fortemente recomendados.
.NET Framework 4.6.1 e versões posteriores.
Há várias vantagens em direcionar para o .NET Core, e essas vantagens aumentam com cada versão. Algumas
vantagens do .NET Core em relação ao .NET Framework incluem:
Multiplataforma. É executado no Windows, no Linux e no macOS.
Desempenho aprimorado
Controle de versão lado a lado
Novas APIs
Código Aberto
Estamos trabalhando duro para diminuir a diferença de API entre o .NET Framework e o .NET Core. O Pacote de
Compatibilidade do Windows disponibilizou milhares de APIs exclusivas do Windows no .NET Core. Essas APIs
não estavam disponíveis no .NET Core 1.x.
Como baixar uma amostra

Muitos dos artigos e tutoriais incluem links para exemplos de código.
1. Baixe o arquivo zip do repositório ASP.NET.
2. Descompacte o arquivo Docs-master.zip.
3. Use a URL no link de exemplo para ajudá-lo a navegar até o diretório de exemplo.
Próximas etapas
Para obter mais informações, consulte os seguintes recursos:
Publicar um aplicativo ASP.NET Core no Azure com o Visual Studio
Conceitos básicos do ASP.NET Core
O Community Standup semanal do ASP.NET aborda o progresso e os planos da equipe. Ele apresenta o novo
software de terceiros e blogs.
Escolher entre o ASP.NET 4.x e o ASP.NET Core
O ASP.NET Core é uma reformulação do ASP.NET 4. x. Este artigo lista as diferenças entre eles.
ASP.NET Core
O ASP.NET Core é uma estrutura de software livre, multiplataforma, para a criação de aplicativos Web modernos e
baseados em nuvem, no Windows, no macOS ou no Linux.
O ASP.NET Core oferece os seguintes benefícios:
Uma história unificada para a criação da interface do usuário da Web e das APIs Web.
Projetado para possibilidade de teste.
O Razor Pages torna a codificação de cenários focados em página mais fácil e produtiva.
Capacidade de desenvolver e executar no Windows, macOS e Linux.
De software livre e voltado para a comunidade.
Integração de estruturas modernas do lado do cliente e fluxos de trabalho de desenvolvimento.
Um sistema de configuração pronto para a nuvem, baseado no ambiente.
Injeção de dependência interna.
Um pipeline de solicitação HTTP leve, modular e de alto desempenho.
A capacidade de hospedar no IIS, Nginx, Apache, Docker ou hospedar em seu próprio processo.
Controle de versão do aplicativo do lado a lado ao direcionar .NET Core.
Ferramentas que simplificam o moderno desenvolvimento para a Web.
ASP.NET 4.x
O ASP.NET 4.x é uma estrutura consolidada que fornece os serviços necessários para criar aplicativos Web
baseados em servidor, de nível empresarial, no Windows.
Seleção de estrutura
A tabela a seguir compara o ASP.NET Core com o ASP.NET 4. x.
ASP.NET CORE ASP.NET 4.X
Build para Windows, macOS ou Linux Build para Windows
Páginas Razor é a abordagem recomendada para criar uma Use o Web Forms, o SignalR, o MVC, a API Web, Webhooks
interface do usuário da Web começando com o ASP.NET Core ou páginas da Web
2.x. Confira também MVC, API Web e SignalR.
Várias versões por computador Uma versão por computador
Desenvolva com o Visual Studio, Visual Studio para Mac ou Desenvolva com o Visual Studio usando o C#, VB ou F#
Visual Studio Code usando o C# ou o F#
Desempenho superior ao do ASP.NET 4.x Bom desempenho

ASP.NET CORE ASP.NET 4.X
Escolha o .NET Framework ou o tempo de execução do .NET Use o tempo de execução do .NET Framework
Core
Confira ASP.NET Core targeting .NET Framework (ASP.NET Core direcionado para o .NET Framework) para obter
informações sobre o suporte do ASP.NET Core 2.x no .NET Framework.
Cenários do ASP.NET Core

Páginas Razor é a abordagem recomendada para criar uma interface do usuário da Web começando com o
ASP.NET Core 2.x.
Sites
APIs
Em tempo real
Implantar um aplicativo ASP.NET Core no Azure
Cenários do ASP.NET 4.x

Sites
APIs
Em tempo real
Criar um aplicativo Web ASP.NET 4.x no Azure
Recursos adicionais
Introdução ao ASP.NET
Implantar aplicativos ASP.NET Core no Serviço de Aplicativo do Azure
Tutorial: introdução ao ASP.NET Core
Este tutorial mostra como usar a interface de linha de comando do .NET Core para criar um aplicativo Web
ASP.NET Core. Você aprenderá como:
Criar um projeto de aplicativo Web.
Habilitar o HTTPS local.
Execute o aplicativo.
Editar uma página do Razor.
No final, você terá um aplicativo Web de trabalho em execução no seu computador local.
Pré-requisitos
Instale o SDK do .NET Core 2.1 ou posteriores.
Criar um projeto de aplicativo Web

Abra um shell de comando e insira o seguinte comando:
dotnet new webapp -o aspnetcoreapp

Habilitar o HTTPS local
Confie no certificado de desenvolvimento HTTPS:
Windows
macOS
Linux
dotnet dev-certs https --trust
O comando anterior exibe a caixa de diálogo a seguir:
Selecione Sim se você concordar com confiar no certificado de desenvolvimento.
Executar o aplicativo
Execute os seguintes comandos:
cd aspnetcoreapp
dotnet run
Procure https://localhost:5001. Clique em Aceitar para aceitar a política de privacidade e cookies. Este
aplicativo não armazena informações pessoais.
Editar uma página do Razor

Abra Pages/About.cshtml e modifique a página com a seguinte marcação realçada:
@page
@model AboutModel
@{
ViewData["Title"] = "About";
}
<h2>@ViewData["Title"]</h2>
<h3>@Model.Message</h3>
<p>Hello, world! The time on the server is @DateTime.Now</p>

Navegue até https://localhost:5001/About e verifique as alterações exibidas.
Próximas etapas
Neste tutorial, você aprendeu como:
Habilitar o HTTPS local.
Execute o projeto.
Faça uma alteração.
Para saber mais sobre o ASP.NET Core, confira a introdução:
Criar um aplicativo Web de Páginas do Razor com o
ASP.NET Core
Essa série explica as noções básicas de criação de um aplicativo Web de Páginas do Razor com o ASP.NET Core
usando o Visual Studio. Outras versões dessa série incluem uma versão do macOS e uma versão do Visual Studio
Code.
1. Introdução a Páginas do Razor
2. Adicionar um modelo a um aplicativo de Páginas do Razor
3. Páginas do Razor geradas por scaffolding
4. Trabalhar com o SQL Server LocalDB
5. Atualizando as páginas
6. Adicionar pesquisa
7. Adicionar um novo campo
8. Adicionar validação
Após o tutorial, para adicionar um recurso de upload de arquivo ao aplicativo de amostra, confira Carregar
arquivos para uma Página Razor no ASP.NET Core.
ASP.NET Core e o Visual Studio Code
Esse é um trabalho em andamento.

usando o Visual Studio Code.
1. Introdução às Páginas do Razor com o VSCode
4. Trabalhar com SQLite
5. Atualizar as páginas
Até a próxima seção ser concluída, execute a versão do Visual Studio para Windows.
ASP.NET Core no macOS com o Visual Studio para
Mac

Esta série explica as noções básicas de criação de um aplicativo Web de Páginas do Razor com o ASP.NET Core no
macOS.
1. Introdução às Páginas do Razor no macOS
Criar um aplicativo Web com o ASP.NET Core MVC
no Windows com o Visual Studio
Este tutorial ensina a usar o desenvolvimento Web do ASP.NET Core MVC com controladores e exibições. O Razor
Pages é um recurso da estrutura do ASP.NET Core MVC que faz com que a criação e o teste de IU da Web fiquem
mais fáceis e produtivos. Você pode usar o Razor Pages com controladores e exibições no mesmo projeto.
É recomendável que você teste o tutorial do Razor Pages antes da versão de MVC/Controlador/Exibições. O
tutorial Páginas do Razor:
É a abordagem preferencial para o desenvolvimento de novos aplicativos.
É mais fácil de acompanhar.
Aborda mais recursos.
Se você escolher este tutorial em vez da versão Páginas do Razor, deixe uma observação explicando o motivo neste
problema do GitHub.
Há três versões deste tutorial:
Windows: esta série
macOS: Como criar um aplicativo ASP.NET Core MVC com o Visual Studio para Mac
macOS, Linux e Windows: Como criar um aplicativo ASP.NET Core MVC com o Visual Studio Code
A série de tutoriais inclui o seguinte:
1. Introdução
2. Adicionar um controlador
3. Adicionar uma exibição
4. Adicionar um modelo
6. Exibições e métodos do controlador
10. Examinar os métodos Details e Delete
Criar um aplicativo ASP.NET Core MVC com o Visual
Studio Code
Esta série de tutoriais ensina os conceitos básicos da criação de um aplicativo Web ASP.NET Core MVC usando o
Visual Studio Code.
problema do GitHub.
1. Introdução
no macOS com o Visual Studio para Mac
Visual Studio para Mac.
problema do GitHub.
1. Introdução
5. SQLite
Criar uma API Web com o ASP.NET Core e o Visual
Studio
Por Rick Anderson e Mike Wasson

Este tutorial compilará uma API Web para gerenciar uma lista de itens de “tarefas pendentes”. Uma interface do
usuário (UI) não será criada.
Windows: API Web com o Visual Studio para Windows (este tutorial)
macOS: API Web com o Visual Studio para Mac
macOS, Linux, Windows: API Web com o Visual Studio Code
Visão geral
Este tutorial cria a seguinte API:
API DESCRIÇÃO CORPO DA SOLICITAÇÃO CORPO DA RESPOSTA
GET /api/todo Obter todos os itens de Nenhum Matriz de itens de tarefas

tarefas pendentes pendentes
GET /api/todo/{id} Obter um item por ID Nenhum Item de tarefas pendentes
POST /api/todo Adicionar um novo item Item de tarefas pendentes Item de tarefas pendentes
PUT /api/todo/{id} Atualizar um item existente Item de tarefas pendentes Nenhum
DELETE /api/todo/{id} Excluir um item Nenhum Nenhum
O diagrama a seguir mostra o design básico do aplicativo.
O cliente é tudo o que consome a API Web (aplicativo móvel, navegador, etc.). Este tutorial não cria um
cliente. Postman ou curl são usados como clientes para testar o aplicativo.
Um modelo é um objeto que representa os dados no aplicativo. Nesse caso, o único modelo é um item de
tarefas pendentes. Os modelos são representados como classes C#, também conhecidas como POCOs (
Plain Old CLR Objects, ou objetos CRL básicos).
Um controlador é um objeto que manipula solicitações HTTP e cria a resposta HTTP. Este aplicativo tem um
único controlador.
Para manter o tutorial simples, o aplicativo não usa um banco de dados persistente. O aplicativo de exemplo
armazena os itens de tarefas pendentes em um banco de dados em memória.
Pré-requisitos
Visual Studio 2017 versão 15.7.3 ou posterior com as cargas de trabalho a seguir:
ASP.NET e desenvolvimento para a Web
Desenvolvimento entre plataformas do .NET Core
SDK do .NET Core 2.1 ou posteriores
Criar o projeto
Siga estas etapas no Visual Studio:
No menu Arquivo, selecione Novo > Projeto.
Selecione o modelo Aplicativo Web ASP.NET Core. Nomeie o projeto como TodoApi e clique em OK.
Na caixa de diálogo Novo aplicativo Web ASP.NET Core – TodoApi e escolha a versão do ASP.NET Core.
Selecione o modelo API e clique em OK. Não selecione Habilitar Suporte ao Docker.
Iniciar o aplicativo
No Visual Studio, pressione CTRL + F5 para iniciar o aplicativo. O Visual Studio inicia um navegador e navega para
http://localhost:<port>/api/values , em que <port> é um número de porta escolhido aleatoriamente. O Chrome,
Microsoft Edge e Firefox exibem a seguinte saída:
["value1","value2"]
Se usar o Internet Explorer, você deverá salvar um arquivo values.json.

Adicionar uma classe de modelo
Um modelo é um objeto que representa os dados no aplicativo. Nesse caso, o único modelo é um item de tarefas
pendentes.
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto. Selecione Adicionar > Nova Pasta.
Nomeie a pasta Models.
NOTE
As classes de modelo podem ficar em qualquer lugar no projeto. A pasta Modelos é usada por convenção para as classes de
modelo.
No Gerenciador de Soluções, clique com o botão direito do mouse na pasta Modelos e selecione Adicionar >
Classe. Nomeie a classe como TodoItem e clique em Adicionar.
Atualize a classe TodoItem com o código a seguir:
namespace TodoApi.Models
{
public class TodoItem
{
public long Id { get; set; }
public string Name { get; set; }
public bool IsComplete { get; set; }
}
}
O banco de dados gera o Id quando um TodoItem é criado.

Criar o contexto de banco de dados
O contexto de banco de dados é a classe principal que coordena a funcionalidade do Entity Framework para um
determinado modelo de dados. Essa classe é criada derivando-a da classe Microsoft.EntityFrameworkCore.DbContext
.
Classe. Nomeie a classe como TodoContext e clique em Adicionar.
Substitua a classe pelo código a seguir:
using Microsoft.EntityFrameworkCore;
{
public class TodoContext : DbContext
{
public TodoContext(DbContextOptions<TodoContext> options)
: base(options)
{
}
public DbSet<TodoItem> TodoItems { get; set; }

}
}
Registrar o contexto de banco de dados

Nesta etapa, o contexto do banco de dados é registrado com o contêiner injeção de dependência. Os serviços
(como o contexto do banco de dados) que são registrados com o contêiner de injeção de dependência (DI) estão
disponíveis para os controladores.
Registre o contexto de banco de dados com o contêiner de serviço usando o suporte interno para injeção de
dependência. Substitua o conteúdo do arquivo Startup.cs pelo seguinte código:
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;
using TodoApi.Models;
namespace TodoApi
{
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}
public void Configure(IApplicationBuilder app)

{
app.UseMvc();
}
}
}
namespace TodoApi
{
{
{
services.AddMvc();
}

{
app.UseMvc();
}
}
}
O código anterior:
Remove o código não usado.
Especifica que um banco de dados em memória é injetado no contêiner de serviço.
No Gerenciador de Soluções, clique com o botão direito do mouse na pasta Controladores. Selecione Adicionar >
Novo Item. Na caixa de diálogo Adicionar Novo Item, selecione o modelo Classe do Controlador de API.
Nomeie a classe como TodoController e clique em Adicionar.
using System.Collections.Generic;
using System.Linq;
namespace TodoApi.Controllers
{
[Route("api/[controller]")]
public class TodoController : ControllerBase
{
private readonly TodoContext _context;
public TodoController(TodoContext context)

{
_context = context;
if (_context.TodoItems.Count() == 0)
{
_context.TodoItems.Add(new TodoItem { Name = "Item1" });
_context.SaveChanges();
}
}
}
}
O código anterior define uma classe de controlador de API sem métodos. Nas próximas seções, os métodos serão
adicionados para implementar a API.
using System.Linq;
{
[ApiController]
{

{
_context = context;
{
// Create a new TodoItem if collection is empty,
// which means you can't delete all TodoItems.
}
}
}
}
O código anterior:
Define uma classe de controlador de API sem métodos.
Cria um novo item de Tarefas pendentes quando TodoItems está vazio. Você não poderá excluir todos os itens
de Tarefas pendentes porque o construtor cria um novo se TodoItems estiver vazio.
Nas próximas seções, os métodos serão adicionados para implementar a API. A classe é anotada com um atributo
[ApiController] para habilitar alguns recursos convenientes. Para obter informações sobre os recursos habilitados
pelo atributo, confira Anotar classe com o ApiControllerAttribute.
O construtor do controlador usa a Injeção de Dependência para injetar o contexto de banco de dados ( TodoContext
) no controlador. O contexto de banco de dados é usado em cada um dos métodos CRUD no controlador. O
construtor adiciona um item no banco de dados em memória, caso ele não exista.
Obter itens pendentes

Para obter os itens pendentes, adicione os seguintes métodos à classe TodoController :
[HttpGet]
public List<TodoItem> GetAll()
{
return _context.TodoItems.ToList();
}
[HttpGet("{id}", Name = "GetTodo")]

public IActionResult GetById(long id)
{
var item = _context.TodoItems.Find(id);
if (item == null)
{
return NotFound();
}
return Ok(item);
}
[HttpGet]
public ActionResult<List<TodoItem>> GetAll()
{
}

public ActionResult<TodoItem> GetById(long id)
{
if (item == null)
{
return NotFound();
}
return item;
}
Esses métodos de implementam os dois métodos GET:

GET /api/todo
GET /api/todo/{id}
Aqui está um exemplo de resposta HTTP para o método GetAll :
[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
Mais adiante no tutorial, mostrarei como a resposta HTTP pode ser visualizada com o Postman ou o curl.
Roteamento e caminhos de URL
O atributo [HttpGet] indica um método que responde a uma solicitação HTTP GET. O caminho da URL de cada
método é construído da seguinte maneira:
Use a cadeia de caracteres de modelo no atributo Route do controlador:
{
{
{
[ApiController]
{
Substitua [controller] com o nome do controlador, que é o nome de classe do controlador menos o sufixo
"Controlador". Para esta amostra, o nome de classe do controlador é TodoController e o nome da raiz é “todo”.
O roteamento do ASP.NET Core não diferencia maiúsculas de minúsculas.
Se o atributo [HttpGet] tiver um modelo de rota (como [HttpGet("/products")] ), acrescente isso ao caminho.
Esta amostra não usa um modelo. Para obter mais informações, confira Roteamento de atributo com atributos
Http[Verb].
No método GetById a seguir, "{id}" é uma variável de espaço reservado para o identificador exclusivo do item
pendente. Quando GetById é invocado, ele atribui o valor de "{id}" na URL ao parâmetro id do método.

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}
Name = "GetTodo" cria uma rota nomeada. Rotas nomeadas:

permitem que o aplicativo crie um link HTTP usando o nome da rota.
Serão explicadas posteriormente no tutorial.
Valores de retorno
O método GetAll retorna uma coleção de objetos TodoItem . O MVC serializa automaticamente o objeto em
JSON e grava o JSON no corpo da mensagem de resposta. O código de resposta para esse método é 200,
supondo que não haja nenhuma exceção sem tratamento. As exceções sem tratamento são convertidas em erros
5xx.
Por outro lado, o método GetById retorna o tipo IActionResult type mais geral, que representa uma ampla
variedade de tipos de retorno. GetById tem dois tipos retornados diferentes:
Se nenhum item corresponder à ID solicitada, o método retornará um erro 404. O retorno NotFound retorna
uma resposta HTTP 404.
Caso contrário, o método retornará 200 com um corpo de resposta JSON. O retorno OK resulta em uma
resposta HTTP 200.
Por outro lado, o método GetById retorna o tipo ActionResult<T> mais geral, que representa uma ampla
Caso contrário, o método retornará 200 com um corpo de resposta JSON. Retornar item resulta em uma
resposta HTTP 200.
No Visual Studio, pressione CTRL + F5 para iniciar o aplicativo. O Visual Studio inicia um navegador e navega para
http://localhost:<port>/api/values , em que <port> é um número de porta escolhido aleatoriamente. Navegue
até o controlador Todo no http://localhost:<port>/api/todo .
Implementar as outras operações CRUD

Nas próximas seções, os métodos Create , Update e Delete serão adicionados ao controlador.
Create
Adicione o seguinte método Create :
[HttpPost]
public IActionResult Create([FromBody] TodoItem item)
{
if (item == null)
{
return BadRequest();
}
_context.TodoItems.Add(item);
return CreatedAtRoute("GetTodo", new { id = item.Id }, item);

}
O código anterior é um método HTTP POST, conforme indicado pelo atributo [HttpPost]. O atributo [FromBody]
informa ao MVC que ele deve obter o valor do item pendente no corpo da solicitação HTTP.
[HttpPost]
public IActionResult Create(TodoItem item)
{

}
O código anterior é um método HTTP POST, conforme indicado pelo atributo [HttpPost]. O MVC obtém o valor do
item pendente no corpo da solicitação HTTP.
O método CreatedAtRoute :
Retorna uma resposta 201. HTTP 201 é a resposta padrão para um método HTTP POST que cria um novo
recurso no servidor.
Adiciona um cabeçalho Local à resposta. O cabeçalho Location especifica o URI do item de tarefas pendentes
recém-criado. Consulte 10.2.2 201 criado.
Usa a rota chamada "GetTodo" para criar a URL. A rota chamada "GetTodo" é definida em GetById :

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}
Usar o Postman para enviar uma solicitação Create

Inicie o aplicativo.
Abra o Postman.
Atualize o número da porta na URL do localhost.
Defina o método HTTP para POST.
Clique na guia Corpo.
Selecione o botão de opção bruto.
Defina o tipo como JSON (aplicativo/json).
Insira um corpo de solicitação com um item pendente que se assemelhe ao JSON a seguir:
{
"name":"walk dog",
"isComplete":true
}
Clique no botão Enviar.
TIP
Se nenhuma resposta for exibida depois de clicar em Enviar, desabilite a opção Verificação de certificação SSL. Isso é
encontrado em Arquivo > Configurações. Clique no botão Enviar novamente depois de desabilitar a configuração.
Clique na guia Cabeçalhos no painel Resposta e copie o valor do cabeçalho Local:

O URI do cabeçalho Local pode ser usado para acessar o novo item.
Atualização
Adicione o seguinte método Update :
[HttpPut("{id}")]
public IActionResult Update(long id, [FromBody] TodoItem item)
{
if (item == null || item.Id != id)
{
}
var todo = _context.TodoItems.Find(id);

if (todo == null)
{
return NotFound();
}
todo.IsComplete = item.IsComplete;
todo.Name = item.Name;
_context.TodoItems.Update(todo);
return NoContent();
}
[HttpPut("{id}")]
public IActionResult Update(long id, TodoItem item)
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
Update é semelhante a Create , exceto pelo uso de HTTP PUT. A resposta é 204 (Sem conteúdo). De acordo com a
especificação de HTTP, uma solicitação PUT requer que o cliente envie a entidade atualizada inteira, não apenas os
deltas. Para dar suporte a atualizações parciais, use HTTP PATCH.
Use o Postman para atualizar o nome do item pendende para "walk cat":
Excluir
Adicione o seguinte método Delete :
[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
if (todo == null)
{
return NotFound();
}
_context.TodoItems.Remove(todo);
return NoContent();
}
A resposta Delete é 204 (Sem conteúdo).

Use Postman para excluir o item pendente:
Chamar a API Web com o jQuery

Nesta seção, é adicionada uma página HTML que usa o jQuery para chamar a API Web. O jQuery inicia a
solicitação e atualiza a página com os detalhes da resposta da API.
Configure o projeto para atender arquivos estáticos e habilitar o mapeamento de arquivo padrão. Isso é feito
chamando os métodos de extensão UseStaticFiles e UseDefaultFiles em Startup.Configure. Para obter mais
informações, veja Arquivos estáticos.
{
app.UseDefaultFiles();
app.UseStaticFiles();
app.UseMvc();
}
Adicione um arquivo HTML, chamado index.html, ao diretório wwwroot do projeto. Substitua seu conteúdo pela
seguinte marcação:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>To-do CRUD</title>
<style>
input[type='submit'], button, [aria-label] {
cursor: pointer;
}
#spoiler {
display: none;
}
table {
font-family: Arial, sans-serif;
border: 1px solid;
border-collapse: collapse;
}
th {
background-color: #0066CC;
color: white;
}
td {
border: 1px solid;
padding: 5px;
}
</style>
</head>
<body>
<h1>To-do CRUD</h1>
<h3>Add</h3>
<form action="javascript:void(0);" method="POST" onsubmit="addItem()">
<input type="text" id="add-name" placeholder="New to-do">
<input type="submit" value="Add">
</form>
<div id="spoiler">
<h3>Edit</h3>
<form class="my-form">
<input type="hidden" id="edit-id">
<input type="checkbox" id="edit-isComplete">
<input type="text" id="edit-name">
<input type="submit" value="Edit">
<a onclick="closeInput()" aria-label="Close">✖</a>
</form>
</div>
<p id="counter"></p>
<table>
<tr>
<th>Is Complete</th>
<th>Name</th>
<th>Name</th>
<th></th>
<th></th>
</tr>
<tbody id="todos"></tbody>
</table>
<script src="https://code.jquery.com/jquery-3.3.1.min.js"
integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8="
crossorigin="anonymous"></script>
<script src="site.js"></script>
</body>
</html>
Adicione um arquivo JavaScript, chamado site.js, ao diretório wwwroot do projeto. Substitua seu conteúdo pelo
código a seguir:
const uri = 'api/todo';

let todos = null;
function getCount(data) {
const el = $('#counter');
let name = 'to-do';
if (data) {
if (data > 1) {
name = 'to-dos';
}
el.text(data + ' ' + name);
} else {
el.html('No ' + name);
}
}
$(document).ready(function () {
getData();
});
function getData() {
$.ajax({
type: 'GET',
url: uri,
success: function (data) {
$('#todos').empty();
getCount(data.length);
$.each(data, function (key, item) {
const checked = item.isComplete ? 'checked' : '';
$('<tr><td><input disabled="true" type="checkbox" ' + checked + '></td>' +

'<td>' + item.name + '</td>' +
'<td><button onclick="editItem(' + item.id + ')">Edit</button></td>' +
'<td><button onclick="deleteItem(' + item.id + ')">Delete</button></td>' +
'</tr>').appendTo($('#todos'));
});
todos = data;
}
});
}
function addItem() {
const item = {
'name': $('#add-name').val(),
'isComplete': false
};
$.ajax({
type: 'POST',
accepts: 'application/json',
url: uri,
url: uri,
contentType: 'application/json',
data: JSON.stringify(item),
error: function (jqXHR, textStatus, errorThrown) {
alert('here');
},
success: function (result) {
getData();
$('#add-name').val('');
}
});
}
function deleteItem(id) {
$.ajax({
url: uri + '/' + id,
type: 'DELETE',
getData();
}
});
}
function editItem(id) {
$.each(todos, function (key, item) {
if (item.id === id) {
$('#edit-name').val(item.name);
$('#edit-id').val(item.id);
$('#edit-isComplete')[0].checked = item.isComplete;
}
});
$('#spoiler').css({ 'display': 'block' });
}
$('.my-form').on('submit', function () {
const item = {
'name': $('#edit-name').val(),
'isComplete': $('#edit-isComplete').is(':checked'),
'id': $('#edit-id').val()
};
$.ajax({
url: uri + '/' + $('#edit-id').val(),
type: 'PUT',
getData();
}
});
closeInput();
return false;
});
function closeInput() {
$('#spoiler').css({ 'display': 'none' });
}
Pode ser necessário realizar uma alteração nas configurações de inicialização do projeto do ASP.NET Core para
testar a página HTML localmente. Abra launchSettings.json no diretório Propriedades do projeto. Remova a
propriedade launchUrl para forçar o aplicativo a ser aberto em index.html, o arquivo padrão do projeto.
Há várias maneiras de obter o jQuery. No trecho de código anterior, a biblioteca é carregada de uma CDN. Este é
um exemplo completo de CRUD ao chamar a API com o jQuery. Existem recursos adicionais neste exemplo para
enriquecer a experiência. Abaixo estão as explicações relacionadas às chamadas à API.
Obter uma lista de itens pendentes
Para obter uma lista de itens pendentes, envie uma solicitação HTTP GET para /api/todo.
A função ajax do jQuery envia uma solicitação AJAX para a API, que retorna o JSON que representa um objeto ou
uma matriz. Essa função pode lidar com todas as formas de interação de HTTP, enviando uma solicitação HTTP à
url especificada. GET é usado como o type . A função de retorno de chamada success será invocada se a
solicitação for bem-sucedida. No retorno de chamada, o DOM é atualizado com as informações do item pendente.
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
Adicionar um item pendente

Para adicionar um item pendente, envie uma solicitação HTTP POST para /api/todo/. O corpo da solicitação deve
conter um objeto pendente. A função ajax está usando o POST para chamar a API. Para as solicitações POST e PUT
, o corpo da solicitação representa os dados enviados para a API. A API está esperando um corpo de solicitação
JSON. As opções accepts e contentType são definidas como application/json para classificar o tipo de mídia
que está sendo recebido e enviado, respectivamente. Os dados são convertidos em um objeto JSON usando
JSON.stringify . Quando a API retorna um código de status de êxito, a função getData é invocada para atualizar a
tabela HTML.
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}
Atualizar um item pendente

Atualizar um item pendente é muito semelhante a adicionar um item pendente, pois ambas as ações contam com
um corpo da solicitação. Nesse caso, a única diferença real entre as duas é que a url é alterada para adicionar o
identificador exclusivo do item e o type é PUT .
$.ajax({
type: 'PUT',
getData();
}
});
Excluir um item pendente

A exclusão de um item pendente é feita definindo o type na chamada do AJAX como DELETE e especificando o
identificador exclusivo do item na URL.
$.ajax({
type: 'DELETE',
getData();
}
});
Próximas etapas
Para obter informações de como usar um banco de dados persistente, confira:
Criar um aplicativo Web de Páginas do Razor com o ASP.NET Core
Páginas Razor do ASP.NET Core com EF Core – série de tutoriais
Hospedar e implantar o ASP.NET Core
Páginas de ajuda da API Web ASP.NET Core usando o Swagger
Roteamento para ações do controlador
Criar APIs Web com o ASP.NET Core
Tipos de retorno de ação do controlador
Exibir ou baixar o código de exemplo. Consulte como baixar.
Studio Code

Neste tutorial, crie uma API Web para gerenciar uma lista de itens de "tarefas pendentes". Uma interface do
usuário não é construída.
macOS, Linux, Windows: API Web com o Visual Studio Code (Este tutorial)
Windows: API Web com o Visual Studio para Windows
Visão geral

único controlador.
Pré-requisitos
Instale o seguinte:
SDK 2.0 ou posterior do .NET Core
Visual Studio Code
C# para Visual Studio Code
Visual Studio Code
Consulte Ajuda do Visual Studio Code para obter dicas sobre como usar o VS Code.
Criar o projeto
Em um console, execute os seguintes comandos:
dotnet new webapi -o TodoApi

code TodoApi
A pasta TodoApi é aberta no VS Code (Visual Studio Code). Selecione o arquivo Startup.cs.
Selecione Sim para a mensagem de Aviso “Os ativos necessários para compilar e depurar estão ausentes em
'TodoApi'. Deseja adicioná-los?”
Selecione Restaurar para a mensagem Informações “Há dependências não resolvidas”.
Pressione Depurar (F5) para compilar e executar o programa. Em um navegador, navegue até
http://localhost:5000/api/values. É exibida a saída a seguir:
["value1","value2"]
Adicionar suporte ao Entity Framework Core

A criação de um projeto no ASP.NET Core 2.1 ou posterior adiciona o metapacote Microsoft.AspNetCore.App ao
arquivo de projeto:
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
A criação de um projeto no ASP.NET Core 2.0 ou posterior adiciona o metapacote Microsoft.AspNetCore.All ao

arquivo de projeto:
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
</ItemGroup>
Não é necessário instalar o provedor de banco de dados Entity Framework Core InMemory separadamente. Este
provedor de banco de dados permite que o Entity Framework Core seja usado com um banco de dados em
memória.

Um modelo é um objeto que representa os dados em seu aplicativo. Nesse caso, o único modelo é um item de
tarefas pendentes.
Adicione uma pasta chamada Models. Você pode colocar as classes de modelo em qualquer lugar no projeto, mas a
pasta Models é usada por convenção.
Adicione uma classe TodoItem com o seguinte código:
{
{
}
}

O contexto de banco de dados é a classe principal que coordena a funcionalidade do Entity Framework para
determinado modelo de dados. Você cria essa classe derivando-a da classe
Microsoft.EntityFrameworkCore.DbContext .
Adicione uma classe TodoContext à pasta Models:
{
{
: base(options)
{
}

}
}

namespace TodoApi
{
{
{
services.AddMvc()
}

{
app.UseMvc();
}
}
}
namespace TodoApi
{
{
{
services.AddMvc();
}

{
app.UseMvc();
}
}
}
O código anterior:
Na pasta Controllers, crie uma classe chamada TodoController . Substitua seu conteúdo pelo código a seguir:
using System.Linq;
{
{

{
_context = context;
{
}
}
}
}
using System.Linq;
{
[ApiController]
{

{
_context = context;
{
}
}
}
}
O código anterior:

[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}
[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return item;
}

GET /api/todo
GET /api/todo/{id}
[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
{
{
{
[ApiController]
{
Http[Verb].

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Valores de retorno
5xx.
resposta HTTP 200.
resposta HTTP 200.
No VS Code, pressione F5 para iniciar o aplicativo. Navegue até http://localhost:5000/api/todo (o controlador
Todo que nós criamos).


{
app.UseMvc();
}
<!DOCTYPE html>
<html>
<head>
<style>
cursor: pointer;
}
#spoiler {
display: none;
}
table {
border: 1px solid;
}
th {
color: white;
}
td {
border: 1px solid;
padding: 5px;
}
</style>
</head>
<body>
<h1>To-do CRUD</h1>
<h3>Add</h3>
</form>
<div id="spoiler">
<h3>Edit</h3>
</form>
</div>
<table>
<tr>
<th>Name</th>
<th></th>
<th></th>
</tr>
</table>
</body>
</html>
código a seguir:

let todos = null;
let name = 'to-do';
if (data) {
if (data > 1) {
name = 'to-dos';
}
} else {
}
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}
$.ajax({
type: 'DELETE',
getData();
}
});
}
}
});
}
const item = {
};
$.ajax({
type: 'PUT',
getData();
}
});
closeInput();
return false;
});
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}

tabela HTML.
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}

$.ajax({
type: 'PUT',
getData();
}
});

$.ajax({
type: 'DELETE',
getData();
}
});

Create
[HttpPost]
{
if (item == null)
{
}

}
[HttpPost]
{

}
O código anterior é um método HTTP POST, conforme indicado pelo atributo [HttpPost]. O MVC obtém o valor do
item pendente no corpo da solicitação HTTP.

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Abra o Postman.
{
"name":"walk dog",
"isComplete":true
}
TIP

Atualização
[HttpPut("{id}")]
{
{
}

if (todo == null)
{
return NotFound();
}
return NoContent();
}
[HttpPut("{id}")]
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
Update é semelhante a Create , exceto pelo uso de HTTP PUT. A resposta é 204 (Sem conteúdo). De acordo com a
especificação de HTTP, uma solicitação PUT requer que o cliente envie a entidade atualizada inteira, não apenas os
Excluir
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}

Ajuda do Visual Studio Code

Introdução
Depuração
Terminal integrado
Atalhos de teclado
Atalhos de teclado do macOS
Atalhos de teclado do Linux
Atalhos de teclado do Windows
Próximas etapas
Studio para Mac

Neste tutorial, crie uma API Web para gerenciar uma lista de itens de "tarefas pendentes". A interface do usuário
não é construída.
macOS: API Web com o Visual Studio para Mac (este tutorial)
Visão geral

único controlador.
Confira Introdução ao ASP.NET Core MVC no Mac ou Linux para obter um exemplo que usa um banco de dados
persistente.
Pré-requisitos
Visual Studio para Mac
Criar o projeto
No Visual Studio, selecione Arquivo > Nova Solução.
Selecione Aplicativo .NET Core > API Web ASP.NET Core > Avançar.
Digite TodoApi para o Nome do Projeto e, em seguida, clique em Criar.
No Visual Studio, selecione Executar > Iniciar com Depuração para iniciar o aplicativo. O Visual Studio inicia
um navegador e navega para http://localhost:5000 . Você obtém um erro de HTTP 404 (Não Encontrado). Altere
a URL para http://localhost:<port>/api/values . Os dados do ValuesController são exibidos:
["value1","value2"]

Instalar o provedor de banco de dados Entity Framework Core InMemory. Este provedor de banco de dados
permite que o Entity Framework Core seja usado com um banco de dados em memória.
No menu Projeto, selecione Adicionar pacotes do NuGet.
Como alternativa, clique com o botão direito do mouse em Dependências e, em seguida, selecione
Adicionar Pacotes.
Digite EntityFrameworkCore.InMemory na caixa de pesquisa.
Selecione Microsoft.EntityFrameworkCore.InMemory e, em seguida, selecione Adicionar Pacote.
tarefas pendentes.
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto. Selecione Adicionar > Nova Pasta.
Nomeie a pasta como Modelos.
NOTE
Você pode colocar as classes de modelo em qualquer lugar no projeto, mas a pasta Models é usada por convenção.
Clique com o botão direito do mouse na pasta Modelos e selecione Adicionar > Novo Arquivo > Geral > Classe
Vazia. Nomeie a classe como TodoItem e, em seguida, clique em Novo.
Substitua o código gerado por:
{
{
}
}

Adicione uma classe denominada TodoContext à pasta Modelos.
{
{
: base(options)
{
}

}
}

namespace TodoApi
{
{
{
services.AddMvc()
}

{
app.UseMvc();
}
}
}
namespace TodoApi
{
{
{
services.AddMvc();
}

{
app.UseMvc();
}
}
}
O código anterior:
No Gerenciador de Soluções, na pasta Controladores, adicione a classe TodoController .
Substitua o código gerado pelo seguinte:
using System.Linq;
{
{

{
_context = context;
{
}
}
}
}
using System.Linq;
{
[ApiController]
{

{
_context = context;
{
}
}
}
}
O código anterior:

[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}
[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return item;
}

GET /api/todo
GET /api/todo/{id}
[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
{
{
{
[ApiController]
{
Http[Verb].

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Valores de retorno
5xx.
resposta HTTP 200.
resposta HTTP 200.
um navegador e navega para http://localhost:<port> , em que <port> é um número de porta escolhido
aleatoriamente. Você obtém um erro de HTTP 404 (Não Encontrado). Altere a URL para
http://localhost:<port>/api/values . Os dados do ValuesController são exibidos:
["value1","value2"]
Navegue até o controlador Todo no http://localhost:<port>/api/todo . O seguinte JSON é retornado:
[{"key":1,"name":"Item1","isComplete":false}]

Adicionaremos os métodos Create , Update e Delete ao controlador. Esses métodos são variações de um mesmo
tema e, portanto, mostrarei apenas o código e realçarei as principais diferenças. Compile o projeto depois de
adicionar ou alterar o código.
Create
[HttpPost]
{
if (item == null)
{
}

}
O método anterior responde a um HTTP POST, conforme indicado pelo atributo [HttpPost]. O atributo
[FromBody] informa ao MVC que ele deve obter o valor do item pendente no corpo da solicitação HTTP.
[HttpPost]
{

}
O método anterior responde a um HTTP POST, conforme indicado pelo atributo [HttpPost]. O MVC obtém o valor
do item pendente no corpo da solicitação HTTP.
O método CreatedAtRoute retorna uma resposta 201. Essa é a resposta padrão para um método HTTP POST que
cria um novo recurso no servidor. CreatedAtRoute também adiciona um cabeçalho Local à resposta. O cabeçalho
Location especifica o URI do item de tarefas pendentes recém-criado. Consulte 10.2.2 201 criado.
Inicie o aplicativo (Executar > Iniciar com Depuração).
Abra o Postman.
{
"name":"walk dog",
"isComplete":true
}
TIP

É possível usar o URI do cabeçalho Local para acessar o recurso que você criou. O método Create retorna
CreatedAtRoute. O primeiro parâmetro passado para CreatedAtRoute representa a rota nomeada a ser usada para
gerar a URL. Lembre-se de que o método GetById criou a rota nomeada "GetTodo" :
Atualização
[HttpPut("{id}")]
{
{
}

if (todo == null)
{
return NotFound();
}
return NoContent();
}
[HttpPut("{id}")]
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
Update é semelhante a Create , mas usa HTTP PUT. A resposta é 204 (Sem conteúdo). De acordo com a
especificação HTTP, uma solicitação PUT exige que o cliente envie a entidade atualizada inteira, não apenas os
{
"key": 1,
"name": "walk dog",
"isComplete": true
}
Excluir
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
A resposta é 204 (Sem conteúdo).


{
app.UseMvc();
}
<!DOCTYPE html>
<html>
<head>
<style>
cursor: pointer;
}
}
#spoiler {
display: none;
}
table {
border: 1px solid;
}
th {
color: white;
}
td {
border: 1px solid;
padding: 5px;
}
</style>
</head>
<body>
<h1>To-do CRUD</h1>
<h3>Add</h3>
</form>
<div id="spoiler">
<h3>Edit</h3>
</form>
</div>
<table>
<tr>
<th>Name</th>
<th></th>
<th></th>
</tr>
</table>
</body>
</html>
código a seguir:

let todos = null;
let name = 'to-do';
if (data) {
if (data > 1) {
name = 'to-dos';
}
} else {
}
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}
$.ajax({
type: 'DELETE',
getData();
}
});
}
}
});
}
const item = {
};
$.ajax({
type: 'PUT',
getData();
}
});
closeInput();
return false;
});
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}

tabela HTML.
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}

$.ajax({
type: 'PUT',
getData();
}
});

$.ajax({
type: 'DELETE',
getData();
}
});
Próximas etapas
Criar serviços de back-end para aplicativos móveis
nativos com o ASP.NET Core
Por Steve Smith

Os aplicativos móveis podem se comunicar com facilidade com os serviços de back-end do ASP.NET Core.
Exibir ou baixar o código de exemplo dos serviços de back-end
Exemplo do aplicativo móvel nativo

Este tutorial demonstra como criar serviços de back-end usando o ASP.NET Core MVC para dar suporte a
aplicativos móveis nativos. Ele usa o aplicativo Xamarin Forms ToDoRest como seu cliente nativo, que inclui
clientes nativos separados para dispositivos Android, iOS, Universal do Windows e Windows Phone. Siga o tutorial
com links para criar o aplicativo nativo (e instale as ferramentas do Xamarin gratuitas necessárias), além de baixar a
solução de exemplo do Xamarin. A amostra do Xamarin inclui um projeto de serviços do ASP.NET Web API 2, que
substitui o aplicativo ASP.NET Core deste artigo (sem nenhuma alteração exigida pelo cliente).
Recursos
O aplicativo ToDoRest é compatível com listagem, adição, exclusão e atualização de itens de tarefas pendentes.
Cada item tem uma ID, um Nome, Observações e uma propriedade que indica se ele já foi Concluído.
A exibição principal dos itens, conforme mostrado acima, lista o nome de cada item e indica se ele foi concluído
com uma marca de seleção.
Tocar no ícone + abre uma caixa de diálogo de adição de itens:
Tocar em um item na tela da lista principal abre uma caixa de diálogo de edição, na qual o Nome do item,
Observações e configurações de Concluído podem ser modificados, ou o item pode ser excluído:
Esta amostra é configurada por padrão para usar os serviços de back-end hospedados em developer.xamarin.com,
que permitem operações somente leitura. Para testá-la por conta própria no aplicativo ASP.NET Core criado na
próxima seção em execução no computador, você precisará atualizar a constante RestUrl do aplicativo. Navegue
para o projeto ToDoREST e abra o arquivo Constants.cs. Substitua o RestUrl por uma URL que inclui o endereço IP
do computador (não localhost ou 127.0.0.1, pois esse endereço é usado no emulador do dispositivo, não no
computador). Inclua o número da porta também (5000). Para testar se os serviços funcionam com um dispositivo,
verifique se você não tem um firewall ativo bloqueando o acesso a essa porta.
// URL of REST service (Xamarin ReadOnly Service)

//public static string RestUrl = "http://developer.xamarin.com:8081/api/todoitems{0}";
// use your machine's IP address

public static string RestUrl = "http://192.168.1.207:5000/api/todoitems/{0}";
Criando o projeto ASP.NET Core

Crie um novo aplicativo Web do ASP.NET Core no Visual Studio. Escolha o modelo de Web API sem autenticação.
Nomeie o projeto como ToDoApi.
O aplicativo deve responder a todas as solicitações feitas através da porta 5000. Atualize o Program.cs para incluir
.UseUrls("http://*:5000") para ficar assim:
var host = new WebHostBuilder()

.UseKestrel()
.UseUrls("http://*:5000")
.UseContentRoot(Directory.GetCurrentDirectory())
.UseIISIntegration()
.UseStartup<Startup>()
.Build();
NOTE
Execute o aplicativo diretamente, em vez de por trás do IIS Express, que ignora solicitações não local por padrão. Execute
dotnet run em um prompt de comando ou escolha o perfil de nome do aplicativo no menu suspenso Destino de Depuração
na barra de ferramentas do Visual Studio.
Adicione uma classe de modelo para representar itens pendentes. Marque os campos obrigatórios usando o
atributo [Required] :
using System.ComponentModel.DataAnnotations;
namespace ToDoApi.Models
{
public class ToDoItem
{
[Required]
public string ID { get; set; }
[Required]
[Required]
public string Notes { get; set; }
public bool Done { get; set; }

}
}
Os métodos da API exigem alguma maneira de trabalhar com dados. Use a mesma interface IToDoRepository nos
usos de exemplo originais do Xamarin:
using ToDoApi.Models;
namespace ToDoApi.Interfaces
{
public interface IToDoRepository
{
bool DoesItemExist(string id);
IEnumerable<ToDoItem> All { get; }
ToDoItem Find(string id);
void Insert(ToDoItem item);
void Update(ToDoItem item);
void Delete(string id);
}
}
Para esta amostra, a implementação apenas usa uma coleção particular de itens:
using System.Linq;
using ToDoApi.Interfaces;
namespace ToDoApi.Services
{
public class ToDoRepository : IToDoRepository
{
private List<ToDoItem> _toDoList;
public ToDoRepository()
{
InitializeData();
}
public IEnumerable<ToDoItem> All

{
get { return _toDoList; }
}
public bool DoesItemExist(string id)

{
return _toDoList.Any(item => item.ID == id);
}
public ToDoItem Find(string id)

{
return _toDoList.FirstOrDefault(item => item.ID == id);
}
public void Insert(ToDoItem item)

{
_toDoList.Add(item);
}
public void Update(ToDoItem item)

{
var todoItem = this.Find(item.ID);
var index = _toDoList.IndexOf(todoItem);
_toDoList.RemoveAt(index);
_toDoList.Insert(index, item);
}
public void Delete(string id)

{
_toDoList.Remove(this.Find(id));
}
private void InitializeData()

{
_toDoList = new List<ToDoItem>();
var todoItem1 = new ToDoItem

{
ID = "6bb8a868-dba1-4f1a-93b7-24ebce87e243",
Name = "Learn app development",
Notes = "Attend Xamarin University",
Done = true
};

{
ID = "b94afb54-a1cb-4313-8af3-b7511551b33b",
Name = "Develop apps",
Notes = "Use Xamarin Studio/Visual Studio",
Done = false
};

{
ID = "ecfa6f80-3671-4911-aabe-63cc442c1ecf",
Name = "Publish apps",
Notes = "All app stores",
Done = false,
};
_toDoList.Add(todoItem1);
}
}
}
Configure a implementação em Startup.cs:

{
// Add framework services.
services.AddMvc();
services.AddSingleton<IToDoRepository,ToDoRepository>();
}
Neste ponto, você está pronto para criar o ToDoItemsController.
TIP
Saiba mais sobre como criar APIs Web em Criar sua primeira API Web com o ASP.NET Core MVC e o Visual Studio.
Criando o controlador
Adicione um novo controlador ao projeto, ToDoItemsController. Ele deve herdar de
Microsoft.AspNetCore.Mvc.Controller. Adicione um atributo Route para indicar que o controlador manipulará as
solicitações feitas para caminhos que começam com api/todoitems . O token [controller] na rota é substituído
pelo nome do controlador (com a omissão do sufixo Controller ) e é especialmente útil para rotas globais. Saiba
mais sobre o roteamento.
O controlador requer um IToDoRepository para a função; solicite uma instância desse tipo usando o construtor do
controlador. No tempo de execução, esta instância será fornecida com suporte do framework parainjeção de
dependência.
using System;
using Microsoft.AspNetCore.Http;
namespace ToDoApi.Controllers
{
public class ToDoItemsController : Controller
{
private readonly IToDoRepository _toDoRepository;
public ToDoItemsController(IToDoRepository toDoRepository)

{
_toDoRepository = toDoRepository;
}
Essa API é compatível com quatro verbos HTTP diferentes para executar operações CRUD (Criar, Ler, Atualizar,
Excluir) na fonte de dados. A mais simples delas é a operação Read, que corresponde a uma solicitação HTTP GET.
Lendo itens
A solicitação de uma lista de itens é feita com uma solicitação GET ao método List . O atributo [HttpGet] no
método List indica que esta ação só deve lidar com as solicitações GET. A rota para esta ação é a rota
especificada no controlador. Você não precisa necessariamente usar o nome da ação como parte da rota. Você
precisa garantir que cada ação tem uma rota exclusiva e não ambígua. Os atributos de roteamento podem ser
aplicados nos níveis de método e controlador para criar rotas específicas.
[HttpGet]
public IActionResult List()
{
return Ok(_toDoRepository.All);
}
O método List retorna um código de resposta OK 200 e todos os itens de tarefas, serializados como JSON.
Você pode testar o novo método de API usando uma variedade de ferramentas, como Postman. Veja abaixo:
Criando itens
Por convenção, a criação de novos itens de dados é mapeada para o verbo HTTP POST. O método Create tem um
atributo [HttpPost] aplicado a ele e aceita uma instância ToDoItem . Como o argumento item será enviado no
corpo de POST, este parâmetro será decorado com o atributo [FromBody] .
Dentro do método, o item é verificado quanto à validade e existência anterior no armazenamento de dados e, se
nenhum problema ocorrer, ele será adicionado usando o repositório. A verificação de ModelState.IsValid executa a
validação do modelo e deve ser feita em todos os métodos de API que aceitam a entrada do usuário.
[HttpPost]
public IActionResult Create([FromBody] ToDoItem item)
{
try
{
if (item == null || !ModelState.IsValid)
{
return BadRequest(ErrorCode.TodoItemNameAndNotesRequired.ToString());
}
bool itemExists = _toDoRepository.DoesItemExist(item.ID);
if (itemExists)
{
return StatusCode(StatusCodes.Status409Conflict, ErrorCode.TodoItemIDInUse.ToString());
}
_toDoRepository.Insert(item);
}
catch (Exception)
{
return BadRequest(ErrorCode.CouldNotCreateItem.ToString());
}
return Ok(item);
}
A amostra usa uma enumeração que contém códigos de erro que são passados para o cliente móvel:
public enum ErrorCode

{
TodoItemNameAndNotesRequired,
TodoItemIDInUse,
RecordNotFound,
CouldNotCreateItem,
CouldNotUpdateItem,
CouldNotDeleteItem
}
Teste a adição de novos itens usando Postman escolhendo o verbo POST fornecendo o novo objeto no formato
JSON no corpo da solicitação. Você também deve adicionar um cabeçalho de solicitação que especifica um
Content-Type de application/json .
O método retorna o item recém-criado na resposta.
Atualizando itens
A modificação de registros é feita com as solicitações HTTP PUT. Além desta mudança, o método Edit é quase
idêntico ao Create . Observe que, se o registro não for encontrado, a ação Edit retornará uma resposta NotFound
(404).
[HttpPut]
public IActionResult Edit([FromBody] ToDoItem item)
{
try
{
{
}
var existingItem = _toDoRepository.Find(item.ID);
if (existingItem == null)
{
return NotFound(ErrorCode.RecordNotFound.ToString());
}
_toDoRepository.Update(item);
}
catch (Exception)
{
return BadRequest(ErrorCode.CouldNotUpdateItem.ToString());
}
return NoContent();
}
Para testar com Postman, altere o verbo para PUT. Especifique os dados do objeto atualizado no corpo da
solicitação.
Este método retornará uma resposta NoContent (204) quando obtiver êxito, para manter a consistência com a API
já existente.
Excluindo itens
A exclusão de registros é feita por meio da criação de solicitações de exclusão para o serviço e por meio do envio
do ID do item a ser excluído. Assim como as atualizações, as solicitações de itens que não existem receberão
respostas NotFound . Caso contrário, uma solicitação bem-sucedida receberá uma resposta NoContent (204).
public IActionResult Delete(string id)
{
try
{
var item = _toDoRepository.Find(id);
if (item == null)
{
}
_toDoRepository.Delete(id);
}
catch (Exception)
{
return BadRequest(ErrorCode.CouldNotDeleteItem.ToString());
}
return NoContent();
}
Observe que, ao testar a funcionalidade de exclusão, nada é necessário no Corpo da solicitação.
Convenções de Web API comuns

À medida que você desenvolve serviços de back-end para seu aplicativo, desejará criar um conjunto consistente de
convenções ou políticas para lidar com preocupações paralelas. Por exemplo, no serviço mostrado acima, as
solicitações de registros específicos que não foram encontrados receberam uma resposta NotFound , em vez de
uma resposta BadRequest . Da mesma forma, os comandos feitos para esse serviço que passaram tipos associados
a um modelo sempre verificaram ModelState.IsValid e retornaram um BadRequest para tipos de modelo
inválidos.
Depois de identificar uma diretiva comum para suas APIs, você geralmente pode encapsulá-la em um filtro. Saiba
mais sobre como encapsular políticas comuns da API em aplicativos ASP.NET Core MVC.
Recursos adicionais
Tutorial: introdução ao SignalR para ASP.NET Core
Este tutorial ensina as noções básicas da criação de um aplicativo em tempo real usando o SignalR. Você aprenderá
como:
Crie um projeto Web.
Adicionar uma biblioteca de clientes do SignalR.
Criar um hub do SignalR.
Configurar o projeto para usar o SignalR.
Adicione o código que envia mensagens de qualquer cliente para todos os clientes conectados.
No final, você terá um aplicativo de chat funcionando:
Exibir ou baixar um código de exemplo (como baixar).
Pré-requisitos
Visual Studio
Visual Studio Code
Visual Studio 2017 versão 15.8 ou posterior com a carga de trabalho ASP.NET e desenvolvimento para a
Web
SDK do .NET Core 2.1 Core ou posterior
Criar um projeto Web

Visual Studio
Visual Studio Code
No menu, selecione Arquivo > Novo Projeto.
Na caixa de diálogo Novo Projeto, selecione Instalado > Visual C# > Web > Aplicativo Web ASP.NET
Core. Dê ao projeto o nome de SignalRChat.
Selecione Aplicativo Web para criar um projeto que usa Razor Pages.
Selecione uma estrutura de destino do .NET Core, selecione ASP.NET Core 2.1 e clique em OK.
Adicionar a biblioteca de clientes do SignalR

A biblioteca do servidor SignalR está incluída no metapacote Microsoft.AspNetCore.App . A biblioteca de clientes do
JavaScript não é incluída automaticamente no projeto. Neste tutorial, você usará o LibMan (Library Manager) para
obter a biblioteca de clientes de unpkg. unpkg é uma CDN (rede de distribuição de conteúdo) que pode distribuir
qualquer conteúdo do npm, o gerenciador de pacotes do Node.js.
Visual Studio
Visual Studio Code
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Adicionar >
Biblioteca do Lado do Cliente.
Na caixa de diálogo Adicionar Biblioteca do Lado do Cliente, para Provedor, selecione unpkg.
Para Biblioteca, insira @aspnet/signalr@1 e selecione a versão mais recente que não seja uma versão
prévia.
Selecione Escolher arquivos específicos, expanda a pasta distribuidor/navegador e selecione signalr.js e

signalr.min.js.
Defina Localização de Destino como wwwroot/lib/signalr/ e selecione Instalar.
O LibMan cria uma pasta wwwroot/lib/signalr e copia os arquivos selecionados para ela.
Criar um hub do SignalR

Um hub é uma classe que funciona como um pipeline de alto nível que lida com a comunicação entre cliente e
servidor.
Na pasta do projeto SignalRChat, crie uma pasta Hubs.
Na pasta Hubs, crie um arquivo ChatHub.cs com o código a seguir:
using Microsoft.AspNetCore.SignalR;
using System.Threading.Tasks;
namespace SignalRChat.Hubs
{
public class ChatHub : Hub
{
public async Task SendMessage(string user, string message)
{
await Clients.All.SendAsync("ReceiveMessage", user, message);
}
}
}
A classe ChatHub é herda da classe Hub do SignalR. A classe Hub gerencia conexões, grupos e sistemas de
mensagens.
O método SendMessage pode ser chamado por qualquer cliente conectado. Ele envia a mensagem recebida
para todos os clientes. O código do SignalR é assíncrono para fornecer o máximo de escalabilidade.
Configurar o SignalR
O servidor do SignalR precisa ser configurado para passar solicitações do SignalR ao SignalR.
Adicione o seguinte código realçado ao arquivo Startup.cs.
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using SignalRChat.Hubs;
namespace SignalRChat
{
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
// This method gets called by the runtime. Use this method to add services to the container.
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies is needed for a
given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
services.AddSignalR();
}
// This method gets called by the runtime. Use this method to configure the HTTP request
pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseCookiePolicy();
app.UseSignalR(routes =>
{
routes.MapHub<ChatHub>("/chatHub");
});
app.UseMvc();
}
}
}
Essas alterações adicionam o SignalR ao sistema de injeção de dependência e ao pipeline do middleware do

ASP.NET Core.
Adicionar o código de cliente do SignalR
Substitua o conteúdo Pages\Index.cshtml pelo código a seguir:
@page
<div class="container">
<div class="row"> </div>
<div class="row">
<div class="col-6"> </div>
<div class="col-6">
User..........<input type="text" id="userInput" />
<br />
Message...<input type="text" id="messageInput" />
<input type="button" id="sendButton" value="Send Message" />
</div>
</div>
<div class="row">
<div class="col-12">
<hr />
</div>
</div>
<div class="row">
<div class="col-6">
<ul id="messagesList"></ul>
</div>
</div>
</div>
<script src="~/lib/signalr/dist/browser/signalr.js"></script>
<script src="~/js/chat.js"></script>
O código anterior:
Cria as caixas de texto para o nome e a mensagem de texto e um botão Enviar.
Cria uma lista com id="messagesList" para exibir as mensagens recebidas do hub do SignalR.
Inclui referências de script ao SignalR e ao código do aplicativo chat.js que você criará na próxima etapa.
Na pasta wwwroot/js, crie um arquivo chat.js com o código a seguir:
"use strict";
var connection = new signalR.HubConnectionBuilder().withUrl("/chatHub").build();
connection.on("ReceiveMessage", function (user, message) {

var msg = message.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
var encodedMsg = user + " says " + msg;
var li = document.createElement("li");
li.textContent = encodedMsg;
document.getElementById("messagesList").appendChild(li);
});
connection.start().catch(function (err) {
return console.error(err.toString());
});
document.getElementById("sendButton").addEventListener("click", function (event) {

var user = document.getElementById("userInput").value;
var message = document.getElementById("messageInput").value;
connection.invoke("SendMessage", user, message).catch(function (err) {
});
event.preventDefault();
});
O código anterior:
Cria e inicia uma conexão.
Adiciona no botão Enviar um manipulador que envia mensagens ao hub.
Adiciona no objeto de conexão um manipulador que recebe mensagens do hub e as adiciona à lista.
Visual Studio
Visual Studio Code
Pressione CTRL + F5 para executar o aplicativo sem depuração.
Copie a URL da barra de endereços, abra outra instância ou guia do navegador e cole a URL na barra de
endereços.
Escolha qualquer navegador, insira um nome e uma mensagem e selecione o botão Enviar.
O nome e a mensagem são exibidos em ambas as páginas instantaneamente.
TIP
Se o aplicativo não funcionar, abra as ferramentas para desenvolvedores do navegador (F12) e acesse o console. Você pode
encontrar erros relacionados ao código HTML e JavaScript. Por exemplo, suponha que você coloque signalr.js em uma pasta
diferente daquela direcionada. Nesse caso, a referência a esse arquivo não funcionará e ocorrerá um erro 404 no console.
Próximas etapas
Adicionar o código que usa o hub para enviar mensagens de qualquer cliente para todos os clientes conectados.
Para saber mais sobre o SignalR, confira a introdução:
Introdução ao ASP.NET Core SignalR
Usar o SignalR do ASP.NET Core com TypeScript e
Webpack
Por Sébastien Sougnez e Scott Addie

O Webpack habilita os desenvolvedores a agrupar e criar recursos de um aplicativo Web do lado do cliente. Este
tutorial demonstra como usar o Webpack em um aplicativo Web SignalR do ASP.NET Core cujo cliente é escrito
em TypeScript.
Neste tutorial, você aprenderá como:
Gerar um aplicativo inicial SignalR do ASP.NET Core por scaffold
Configurar o cliente TypeScript do SignalR
Configurar um pipeline de build usando o Webpack
Configurar o servidor SignalR
Habilitar a comunicação entre o cliente e o servidor
Exibir ou baixar código de exemplo (como baixar)
Pré-requisitos
Instale o software a seguir:
Visual Studio
CLI do .NET Core
Node.js com npm
Visual Studio 2017 versão 15.7.3 ou posterior com a carga de trabalho do ASP.NET e desenvolvimento para
a Web
Criar o aplicativo Web do ASP.NET Core

Visual Studio
CLI do .NET Core
Configure o Visual Studio para pesquisar o npm na variável de ambiente PATH. Por padrão, o Visual Studio usa a
versão do npm encontrada no diretório de instalação. Siga estas instruções no Visual Studio:
1. Navegue até Ferramentas > Opções > Projetos e soluções > Gerenciamento de Pacotes Web >
Ferramentas Web Externas.
2. Selecione a entrada $ (PATH ) na lista. Clique na seta para cima para mover a entrada para a segunda posição
da lista. Como uma reserva, a primeira entrada se refere aos pacotes locais do projeto.
A configuração do Visual Studio foi concluída. É hora de criar o projeto.
1. Use a opção do menu Arquivo > Novo > Projeto e escolha o modelo Aplicativo Web do ASP.NET Core.
2. Nomeie o projeto como SignalRWebPack e clique no botão OK.
3. Selecione .NET Core no menu suspenso da estrutura de destino e clique em ASP.NET Core 2.1. Selecione o
modelo Empty e clique no botão OK.
Configurar Webpack e TypeScript

As etapas a seguir configuram a conversão do TypeScript para JavaScript e o agrupamento de recursos no lado do
cliente.
1. Execute o seguinte comando na raiz do projeto para criar um arquivo package.json:
npm init -y
2. Adicione a propriedade destacada ao arquivo package.json:
{
"name": "SignalRWebPack",
"version": "1.0.0",
"private": true,
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}
Definir a propriedade private como true evita avisos de instalação de pacote na próxima etapa.
3. Instalar os pacotes de npm exigidos. Execute o seguinte comando na raiz do projeto:
npm install -D -E clean-webpack-plugin@0.1.19 css-loader@0.28.11 html-webpack-plugin@3.2.0 mini-css-
extract-plugin@0.4.0 ts-loader@4.4.1 typescript@2.9.2 webpack@4.12.0 webpack-cli@3.0.6
Alguns detalhes de comando a se observar:

Um número de versão segue o sinal @ para cada nome de pacote. O npm instala essas versões
específicas do pacote.
A opção -E desabilita o comportamento padrão do npm de escrever os operadores de intervalo de
versão semântica para package.json. Por exemplo, "webpack": "4.12.0" é usado em vez de
"webpack": "^4.12.0" . Essa opção evita atualizações não intencionais para versões de pacote mais
recentes.
Veja os documentos oficiais de instalação de npm para saber mais detalhes.
4. Substitua a propriedade scripts do arquivo package.json com o seguinte snippet:
"scripts": {
"build": "webpack --mode=development --watch",
"release": "webpack --mode=production",
"publish": "npm run release && dotnet publish -c Release"
},
Uma explicação sobre os scripts:

build : agrupa os recursos do lado do cliente no modo de desenvolvimento e busca alterações no
arquivo. O observador de arquivos faz com que o lote se regenere toda vez que um arquivo de projeto é
alterado. A opção mode desabilita otimizações de produção, como tree shaking e minificação. Use
somente build no desenvolvimento.
release : agrupa recursos do lado do cliente no modo de produção.
publish : executa o script release para agrupar recursos do lado do cliente no modo de produção.
Chama o comando publicar da CLI do .NET Core para publicar o aplicativo.
5. Crie um arquivo chamado webpack.config.js na raiz do projeto, com o seguinte conteúdo:
const path = require("path");
const HtmlWebpackPlugin = require("html-webpack-plugin");
const CleanWebpackPlugin = require("clean-webpack-plugin");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
entry: "./src/index.ts",
output: {
path: path.resolve(__dirname, "wwwroot"),
filename: "[name].[chunkhash].js",
publicPath: "/"
},
resolve: {
extensions: [".js", ".ts"]
},
module: {
rules: [
{
test: /\.ts$/,
use: "ts-loader"
},
{
test: /\.css$/,
use: [MiniCssExtractPlugin.loader, "css-loader"]
}
]
},
plugins: [
new CleanWebpackPlugin(["wwwroot/*"]),
new HtmlWebpackPlugin({
template: "./src/index.html"
}),
new MiniCssExtractPlugin({
filename: "css/[name].[chunkhash].css"
})
]
};
O arquivo precedente configura a compilação Webpack. Detalhes de configuração a serem notados:

A propriedade output substitui o valor padrão do dist. Em vez disso, o lote é emitido no diretório
wwwroot.
A matriz resolve.extensions inclui .js para importar o JavaScript do cliente SignalR.
6. Crie um novo diretório src na raiz do projeto. O propósito é armazenar os ativos do lado do cliente do
projeto.
7. Crie src/index.html com o seguinte conteúdo.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>ASP.NET Core SignalR</title>
</head>
<body>
<div id="divMessages" class="messages">
</div>
<div class="input-zone">
<label id="lblMessage" for="tbMessage">Message:</label>
<input id="tbMessage" class="input-zone-input" type="text" />
<button id="btnSend">Send</button>
</div>
</body>
</html>
A HTML precedente define a marcação clichê da página inicial.

8. Crie um novo diretório src/css. Seu propósito é armazenar os arquivos do projeto .css.
9. Crie src/css/main.css com o seguinte conteúdo:
*, *::before, *::after {
box-sizing: border-box;
}
html, body {
margin: 0;
padding: 0;
}
.input-zone {
align-items: center;
display: flex;
flex-direction: row;
margin: 10px;
}
.input-zone-input {
flex: 1;
margin-right: 10px;
}
.message-author {
font-weight: bold;
}
.messages {
border: 1px solid #000;
margin: 10px;
max-height: 300px;
min-height: 300px;
overflow-y: auto;
padding: 5px;
}
O arquivo precedente main.css define o estilo do aplicativo.

10. Crie src/tsconfig.json com o seguinte conteúdo:
{
"compilerOptions": {
"target": "es5"
}
}
O código precedente configura o compilador TypeScript para produzir um JavaScript compatível com
ECMAScript 5.
11. Crie src/index.ts com o seguinte conteúdo:
import "./css/main.css";
const divMessages: HTMLDivElement = document.querySelector("#divMessages");

const tbMessage: HTMLInputElement = document.querySelector("#tbMessage");
const btnSend: HTMLButtonElement = document.querySelector("#btnSend");
const username = new Date().getTime();
tbMessage.addEventListener("keyup", (e: KeyboardEvent) => {

if (e.keyCode === 13) {
send();
}
});
btnSend.addEventListener("click", send);
function send() {
}
O TypeScript precedente recupera referências a elementos DOM e anexa dois manipuladores de eventos:
keyup : esse evento é acionado quando o usuário digita algo na caixa de texto identificada como
tbMessage . A função send é chamada quando o usuário pressionar a tecla Enter.
click : esse evento é acionado quando o usuário clica no botão Enviar. A função send é chamada.
Configurar o aplicativo do ASP.NET Core

1. O código fornecido no método Startup.Configure exibe Olá, Mundo. Substitua a chamada para o método
app.Run com chamadas para UseDefaultFiles e UseStaticFiles.
O código precedente permite que o servidor localize e forneça o arquivo index.html, se o usuário inserir a
URL completa ou a URL raiz do aplicativo Web.
2. Chame AddSignalR no método Startup.ConfigureServices . Adiciona serviços SignalR ao seu projeto.
3. Mapeie uma rota /hub para o hub ChatHub . Adicione as linhas a seguir ao final do método
Startup.Configure :
app.UseSignalR(options =>
{
options.MapHub<ChatHub>("/hub");
});
4. Crie um novo diretório, chamado Hubs, na raiz do projeto. A finalidade é armazenar o hub SignalR, que é
criado na próxima etapa.
5. Crie o hub Hubs/ChatHub.cs com o código a seguir:
namespace SignalRWebPack.Hubs
{
{
}
}
6. Adicione o código a seguir ao topo do arquivo Startup.cs para resolver a referência ChatHub :
using SignalRWebPack.Hubs;

Atualmente, o aplicativo exibe um formulário simples para enviar mensagens. Nada acontece quando você tenta
fazer alguma coisa. O servidor está escutando uma rota específica, mas não faz nada com as mensagens enviadas.
1. Execute o comando a seguir na raiz do projeto:
npm install @aspnet/signalr
O comando precedente instala o cliente TypeScript do SignalR, que permite ao cliente enviar mensagens
para o servidor.
2. Adicione o código destacado ao arquivo src/index.ts:
import * as signalR from "@aspnet/signalr";

const connection = new signalR.HubConnectionBuilder()

.withUrl("/hub")
.build();
connection.start().catch(err => document.write(err));
connection.on("messageReceived", (username: string, message: string) => {

let m = document.createElement("div");
m.innerHTML =
`<div class="message__author">${username}</div><div>${message}</div>`;
divMessages.appendChild(m);
divMessages.scrollTop = divMessages.scrollHeight;
});

send();
}
});
function send() {
}
O código precedente é compatível com o recebimento de mensagens do servidor. A classe

HubConnectionBuilder cria um novo construtor para configurar a conexão do servidor. A função withUrl
configura a URL do hub.
O SignalR habilita a troca de mensagens entre um cliente e um servidor. Cada mensagem tem um nome
específico. Por exemplo, você pode ter mensagens com o nome messageReceived que executam a lógica
responsável por exibir a nova mensagem na zona de mensagens. É possível escutar uma mensagem
específica por meio da função on . Você pode escutar qualquer número de nomes de mensagem. Também é
possível passar parâmetros para a mensagem, como o nome do autor e o conteúdo da mensagem recebida.
Quando o cliente recebe a mensagem, um novo elemento div é criado com o nome do autor e o conteúdo
da mensagem em seu atributo innerHTML . Ele é adicionado ao elemento principal div que exibe as
mensagens.
3. Agora que o cliente pode receber mensagens, configure-o para enviá-las. Adicione o código destacado ao
arquivo src/index.ts:


.withUrl("/hub")
.build();

let messageContainer = document.createElement("div");
messageContainer.innerHTML =
`<div class="message-author">${username}</div><div>${message}</div>`;
divMessages.appendChild(messageContainer);
});

send();
}
});
function send() {
connection.send("newMessage", username, tbMessage.value)
.then(() => tbMessage.value = "");
}
Enviar uma mensagem por meio da conexão WebSockets exige uma chamada para o método send . O
primeiro parâmetro do método é o nome da mensagem. Os dados da mensagem residem nos outros
parâmetros. Neste exemplo, uma mensagem identificada como newMessage é enviada ao servidor. A
mensagem é composta do nome de usuário e da entrada em uma caixa de texto. Se o envio for bem-
sucedido, o valor da caixa de texto será limpo.
4. Adicione o método em destaque à classe ChatHub :
{
{
public async Task NewMessage(string username, string message)
{
await Clients.All.SendAsync("messageReceived", username, message);
}
}
}
O código precedente transmite as mensagens recebidas para todos os usuários conectados quando o
servidor as recebe. Não é necessário ter um método genérico on para receber todas as mensagens. Um
método nomeado com o nome da mensagem é suficiente.
Neste exemplo, o cliente TypeScript envia uma mensagem identificada como newMessage . O método
NewMessage de C# espera os dados enviados pelo cliente. Uma chamada é feita para o método SendAsync
em Clients.All. As mensagens recebidas são enviadas a todos os clientes conectados ao hub.
Testar o aplicativo
Confirme que o aplicativo funciona com as seguintes etapas.
Visual Studio
CLI do .NET Core
1. Execute o Webpack no modo de versão. Na janela Console do Gerenciador de Pacotes, execute o
seguinte comando na raiz do projeto:
npm run release
Este comando suspende o fornecimento dos ativos do lado do cliente ao executar o aplicativo. Os ativos são
colocados na pasta wwwroot.
O Webpack concluiu as seguintes tarefas:
Limpou os conteúdos do diretório wwwroot.
Converteu o TypeScript para JavaScript, um processo conhecido como transpilação.
Reduziu o tamanho do arquivo JavaScript gerado, um processo conhecido como minificação.
Copiou os arquivos JavaScript, CSS e HTML processados do src para o diretório wwwroot.
Injetou os seguintes elementos no arquivo wwwroot/index.html:
Uma marca <link> , que referencia o arquivo wwwroot/main.<hash>.css. Essa marca é colocada
imediatamente antes do fim da marca </head> .
Uma marca <script> , que referencia o arquivo minificado wwwroot/main.<hash>.js. Essa marca
é colocada imediatamente antes do fim da marca </body> .
2. Selecione Debug > Iniciar sem depuração para iniciar o aplicativo em um navegador sem anexar o
depurador. O arquivo wwwroot/index.html é fornecido em http://localhost:<port_number> .
3. Abra outra instância do navegador (qualquer navegador). Cole a URL na barra de endereços.
4. Escolha qualquer navegador, digite algo na caixa de texto Mensagem e clique no botão Enviar. O nome de
usuário exclusivo e a mensagem são exibidas em ambas as páginas instantaneamente.
Recursos adicionais
ASP.NET Core SignalR JavaScript cliente
Usando os hubs de SignalR do ASP.NET Core
Páginas Razor do ASP.NET Core com EF Core – série
de tutoriais
Esta série de tutoriais ensina a criar aplicativos Web de Razor Pages do ASP.NET Core que usam o EF (Entity
Framework) Core para o acesso a dados.
1. Introdução
2. Operações Create, Read, Update e Delete
3. Classificação, filtragem, paginação e agrupamento
4. Migrações
5. Criar um modelo de dados complexo
6. Lendo dados relacionados
7. Atualizando dados relacionados
8. Tratar conflitos de simultaneidade
ASP.NET Core MVC com EF Core – série de tutoriais
Este tutorial ensina a usar o ASP.NET Core MVC e o Entity Framework Core com controladores e exibições. As
Páginas Razor é uma nova alternativa no ASP.NET Core 2.0, um modelo de programação baseado em página que
torna a criação da interface do usuário da Web mais fácil e produtiva. É recomendável tentar o tutorial das Páginas
Razor na versão do MVC. O tutorial Páginas do Razor:
Fornece mais práticas recomendadas do EF Core.
Usa consultas mais eficientes.
É mais atual com a API mais recente.
problema do GitHub.
1. Introdução
4. Migrações
9. Herança
10. Tópicos avançados
Conceitos básicos do ASP.NET Core
Um aplicativo ASP.NET Core é um aplicativo de console que cria um servidor Web em seu método Program.Main .
O método Main é o ponto de entrada gerenciado do aplicativo:
public class Program

{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}
O host do .NET Core:

Carrega o tempo de execução do .NET Core.
Usa o primeiro argumento de linha de comando como o caminho para o binário gerenciado que contém o
ponto de entrada ( Main ) e inicia a execução do código.
O método Main invoca WebHost.CreateDefaultBuilder, que segue o padrão de construtor para criar um host da
Web. O construtor tem métodos que definem o servidor Web (por exemplo, UseKestrel) e a classe de inicialização
(UseStartup). No exemplo anterior, o servidor Web Kestrel é alocado automaticamente. O host Web do ASP.NET
Core tenta executar no IIS, se disponível. Outros servidores Web como HTTP.sys podem ser usados ao chamar o
método de extensão apropriado. UseStartup é explicado em mais detalhes na próxima seção.
IWebHostBuilder, o tipo de retorno da invocação de WebHost.CreateDefaultBuilder , fornece muitos métodos
opcionais. Alguns desses métodos incluem UseHttpSys para hospedar o aplicativo em HTTP.sys e
UseContentRoot para especificar o diretório de conteúdo raiz. Os métodos Build e Run compilam o objeto
IWebHost que hospeda o aplicativo e começa a escutar solicitações HTTP.

{
{
.UseKestrel()
.Build();
host.Run();
}
}
O host do .NET Core:

Carrega o tempo de execução do .NET Core.
Usa o primeiro argumento de linha de comando como o caminho para o binário gerenciado que contém o
ponto de entrada ( Main ) e inicia a execução do código.
O método Main usa WebHostBuilder, que segue o padrão de construtor para criar um host de aplicativo Web. O
construtor tem métodos que definem o servidor Web (por exemplo, UseKestrel) e a classe de inicialização
(UseStartup). No exemplo anterior, o servidor Web Kestrel é usado. Outros servidores Web como WebListener
podem ser usados ao chamar o método de extensão apropriado. UseStartup é explicado em mais detalhes na
próxima seção.
O WebHostBuilder fornece muitos métodos opcionais, incluindo UseIISIntegration, para hospedagem no IIS e no
IIS Express, e UseContentRoot, para especificar o diretório do conteúdo raiz. Os métodos Build e Run compilam o
objeto IWebHost que hospeda o aplicativo e começa a escutar solicitações HTTP.
Inicialização
O método UseStartup em WebHostBuilder especifica a classe Startup para seu aplicativo:

{
{
}

}

{
{
.UseKestrel()
.Build();
host.Run();
}
}
É na classe Startup que você define o pipeline de tratamento de solicitação e é nela que todos os serviços que o
aplicativo precisa estão configurados. A classe Startup deve ser pública e conter os seguintes métodos:

{
// This method gets called by the runtime. Use this method
// to add services to the container.
{
}

// to configure the HTTP request pipeline.
{
}
}
{
// to add services to the container.
{
}

// to configure the HTTP request pipeline.
{
}
}
ConfigureServices define os Serviços usados pelo seu aplicativo (por exemplo, ASP.NET Core MVC, Entity
Framework Core, Identity etc.). Configure define o middleware chamado no pipeline de solicitação.
Para obter mais informações, consulte Inicialização de aplicativo no ASP.NET Core.
Raiz do conteúdo
A raiz do conteúdo é o caminho base para qualquer conteúdo usado pelo aplicativo, tal como Razor Pages,
exibições do MVC e ativos estáticos. Por padrão, a raiz do conteúdo é a mesma localização que o caminho base do
aplicativo para o executável que hospeda o aplicativo.
Diretório base (webroot)

O webroot de um aplicativo é o diretório do projeto que contém recursos públicos e estáticos como CSS,
JavaScript e arquivos de imagem. Por padrão, wwwroot é o webroot.
Para arquivos (.cshtml) do Razor, o til-barra ~/ aponta para o webroot. Caminhos que começam com ~/ são
denominados caminhos virtuais.
Injeção de dependência (serviços)

Um serviço é um componente que é destinado ao consumo comum em um aplicativo. Os serviços são
disponibilizados por meio de DI (injeção de dependência). O ASP.NET Core inclui um contêiner nativo de IoC
(Inversão de Controle) que dá suporte à injeção de construtor por padrão. É possível substituir o contêiner padrão,
se desejado. Além do benefício de seu acoplamento flexível, a DI disponibiliza serviços, tais como registro em log,
por todo o seu aplicativo.
Para obter mais informações, consulte Injeção de dependência no ASP.NET Core.
Middleware
No ASP.NET Core, você compõe o pipeline de solicitação usando o middleware. O middleware do ASP.NET Core
executa operações assíncronas em um HttpContext e então invoca o próximo middleware no pipeline ou encerra a
solicitação.
Por convenção, um componente de middleware chamado "XYZ" é adicionado ao pipeline invocando-se um
método de extensão UseXYZ no método Configure .
O ASP.NET Core inclui um conjunto de middleware interno, e você pode escrever seu próprio middleware
personalizado. A OWIN (Open Web Interface para .NET), que permite que aplicativos Web sejam desacoplados de
servidores Web, é compatível com aplicativos ASP.NET Core.
Para obter mais informações, consulte Middleware do ASP.NET Core e OWIN (Open Web Interface para .NET)
com o ASP.NET Core.

O IHttpClientFactory está disponível para acessar instâncias de HttpClient para fazer solicitações HTTP.
Para obter mais informações, consulte Iniciar solicitações HTTP.
Ambientes
Os ambientes, como Desenvolvimento e Produção, são uma noção de primeira classe no ASP.NET Core e podem
ser definidos usando uma variável de ambiente, um arquivo de configurações e um argumento de linha de
comando.
Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core.
Hospedagem
Os aplicativos ASP.NET Core configuram e iniciam um host, que é responsável pelo gerenciamento de
inicialização e de tempo de vida do aplicativo.
Para obter mais informações, consulte Host no ASP.NET Core.
Servidores
O modelo de hospedagem do ASP.NET Core não escuta diretamente as solicitações. O modelo de host se baseia
em uma implementação do servidor HTTP para encaminhar a solicitação ao aplicativo. A solicitação encaminhada
é empacotada como um conjunto de objetos de recurso que podem ser acessados por meio de interfaces. O
ASP.NET Core inclui um servidor Web gerenciado e de plataforma cruzada chamado Kestrel. O Kestrel
normalmente é executado por trás de um servidor Web de produção, assim como IIS ou Nginx em uma
configuração de proxy reverso. O Kestrel também pode ser executado como um servidor de borda voltado para o
público exposto diretamente à Internet no ASP.NET Core 2.0 ou posterior.
Para obter mais informações, consulte Implementações de servidor Web em ASP.NET Core.
Configuração
O ASP.NET Core usa um modelo de configuração com base nos pares de nome-valor. O modelo de configuração
não baseado em System.Configuration ou em web.config. A configuração obtém as definições de um conjunto
ordenado de provedores de configuração. Os provedores internos de configuração dão suporte a uma variedade
de formatos de arquivo (XML, JSON, INI), variáveis de ambiente e argumentos de linha de comando. Você
também pode escrever seus próprios provedores de configuração personalizados.
Para obter mais informações, consulte Configuração no ASP.NET Core.
Registrando em log
O ASP.NET Core dá suporte a uma API de registro em log que funciona com uma variedade de provedores de
logs. Os provedores internos dão suporte ao envio de logs para um ou mais destinos. As estruturas de registro em
log de terceiros podem ser usadas.
Para obter mais informações, consulte Registro em log no ASP.NET Core.
Tratamento de erros
O ASP.NET Core tem cenários internos para tratamento de erros em aplicativos, incluindo uma página de exceção
de desenvolvedor, páginas de erro personalizadas, páginas de código de status estático e tratamento de exceções
de inicialização.
Para obter mais informações, consulte Tratar erros no ASP.NET Core.
Roteamento
O ASP.NET Core oferece cenários para roteamento de solicitações de aplicativo para manipuladores de rotas.
Para obter mais informações, consulte Roteamento no ASP.NET Core.
Tarefas em segundo plano

As tarefas em segundo plano são implementadas como serviços hospedados. Um serviço hospedado é uma classe
com lógica de tarefa em segundo plano que implementa a interface IHostedService.
Para obter mais informações, consulte Tarefas em segundo plano com serviços hospedados no ASP.NET Core.
Acessar o HttpContext
HttpContext está disponível automaticamente durante o processamento de solicitações com Razor Pages e com o
MVC. Em circunstâncias em que HttpContext não está prontamente disponível, você pode acessar o HttpContext
por meio da interface IHttpContextAccessor e sua implementação padrão, HttpContextAccessor.
Para obter mais informações, consulte Acessar o HttpContext no ASP.NET Core.
Inicialização de aplicativo no ASP.NET Core
Por Steve Smith, Tom Dykstra e Luke Latham

A classe Startup configura serviços e o pipeline de solicitação do aplicativo.
A classe Startup
Os aplicativos do ASP.NET Core usam uma classe Startup , que é chamada de Startup por convenção. A
classe Startup :
Também é possível incluir um método ConfigureServices para configurar os serviços do aplicativo.
Deve incluir um método Configure para criar o pipeline de processamento de solicitações do aplicativo.
ConfigureServices e Configure são chamados pelo tempo de execução quando o aplicativo é iniciado:

{
// Use this method to add services to the container.
{
...
}
// Use this method to configure the HTTP request pipeline.

{
...
}
}
Especifique a classe Startup com o método WebHostBuilderExtensions UseStartup<TStartup>:

{
{
}

}
O host da Web fornece alguns serviços que estão disponíveis para o construtor de classe Startup . O
aplicativo adiciona serviços adicionais por meio de ConfigureServices . Os serviços de aplicativos e o host
ficam, então, disponíveis em Configure e em todo o aplicativo.
Um uso comum da injeção de dependência na classe Startup é injetar:
IHostingEnvironment para configurar serviços pelo ambiente.
IConfiguration para ler a configuração.
ILoggerFactory para criar um agente em Startup.ConfigureServices .

{
private readonly IHostingEnvironment _env;
private readonly IConfiguration _config;
private readonly ILoggerFactory _loggerFactory;
public Startup(IHostingEnvironment env, IConfiguration config,

ILoggerFactory loggerFactory)
{
_env = env;
_config = config;
_loggerFactory = loggerFactory;
}

{
var logger = _loggerFactory.CreateLogger<Startup>();
if (_env.IsDevelopment())
{
// Development service configuration
logger.LogInformation("Development environment");
}
else
{
// Non-development service configuration
logger.LogInformation($"Environment: {_env.EnvironmentName}");
}
// Configuration is available during startup.

// Examples:
// _config["key"]
// _config["subsection:suboption1"]
}
}
Uma alternativa a injetar IHostingEnvironment é usar uma abordagem baseada em convenções. Quando o
aplicativo define classes Startup separadas para ambientes diferentes (por exemplo, StartupDevelopment ), a
classe Startup apropriada é selecionada no tempo de execução. A classe cujo sufixo do nome corresponde ao
ambiente atual é priorizada. Se o aplicativo for executado no ambiente de desenvolvimento e incluir uma
classe Startup e uma classe StartupDevelopment , a classe StartupDevelopment será usada. Para obter mais
informações, veja Usar vários ambientes.
Para saber mais sobre WebHostBuilder , consulte tópico sobre Hospedagem. Para obter informações sobre
como tratar erros durante a inicialização, consulte Tratamento de exceção na inicialização.
O método ConfigureServices
O método ConfigureServices é:
Opcional
Chamado pelo host da Web antes do Configure método para configurar os serviços do aplicativo.
Onde as opções de configuração são definidas por convenção.
O padrão típico consiste em chamar todos os métodos Add{Service} e, em seguida, chamar todos os métodos
services.Configure{Service} . Por exemplo, veja o tópico Configurar serviços de identidade.
Adicionar serviços ao contêiner de serviços os torna disponíveis dentro do aplicativo e no método Configure .
Os serviços são resolvidos via injeção de dependência ou IApplicationBuilder.ApplicationServices.
O host da Web pode configurar alguns serviços antes que métodos Startup sejam chamados. Detalhes estão
disponíveis no tópico Host no ASP.NET Core.
Para recursos que exigem uma configuração significativa, há métodos de extensão Add[Service] em
IServiceCollection. Um aplicativo ASP.NET Core típico registra serviços para o Entity Framework, Identity e
MVC:

{
services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));
services.AddIdentity<ApplicationUser, IdentityRole>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();
services.AddMvc();
// Add application services.

services.AddTransient<IEmailSender, AuthMessageSender>();
services.AddTransient<ISmsSender, AuthMessageSender>();
}
O método Configure
O método Configure é usado para especificar como o aplicativo responde as solicitações HTTP. O pipeline de
solicitação é configurado adicionando componentes de middleware a uma instância de IApplicationBuilder.
IApplicationBuilder está disponível para o método Configure , mas não é registrado no contêiner de serviço.
A hospedagem cria um IApplicationBuilder e o passa diretamente para Configure .
Os modelos do ASP.NET Core configuram o pipeline com suporte para uma página de exceção de
desenvolvedor, o BrowserLink, páginas de erro, arquivos estáticos e o ASP.NET Core MVC:

{
{
app.UseBrowserLink();
}
else
{
}
app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller}/{action=Index}/{id?}");
});
}
Cada método de extensão Use adiciona um componente de middleware ao pipeline de solicitação. Por
exemplo, o método de extensão UseMvc adiciona o Middleware de roteamento ao pipeline de solicitação e
configura o MVC como o manipulador padrão.
Cada componente de middleware no pipeline de solicitação é responsável por invocar o próximo componente
no pipeline ou causar um curto-circuito da cadeia, se apropriado. Se o curto-circuito não ocorrer ao longo da
cadeia de middleware, cada middleware terá uma segunda chance de processar a solicitação antes que ela seja
enviada ao cliente.
Serviços adicionais, como IHostingEnvironment e ILoggerFactory , também podem ser especificados na
assinatura do método. Quando especificados, serviços adicionais são injetados quando estão disponíveis.
Para obter mais informações de como usar o IApplicationBuilder e a ordem de processamento de
middleware, confira Middleware.
Métodos de conveniência
Os métodos de conveniência ConfigureServices e Configure podem ser usados em vez de especificar uma
classe Startup . Diversas chamadas para ConfigureServices são acrescentadas umas às outras. Diversas
chamadas para Configure usam a última chamada de método.
{
public static IHostingEnvironment HostingEnvironment { get; set; }
public static IConfiguration Configuration { get; set; }

{
}

.ConfigureAppConfiguration((hostingContext, config) =>
{
HostingEnvironment = hostingContext.HostingEnvironment;
Configuration = config.Build();
})
.ConfigureServices(services =>
{
services.AddMvc();
})
.Configure(app =>
{
var loggerFactory = app.ApplicationServices
.GetRequiredService<ILoggerFactory>();
var logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Logged in Configure");
if (HostingEnvironment.IsDevelopment())
{
}
else
{
}
// Configuration is available during startup. Examples:

// Configuration["key"]
// Configuration["subsection:suboption1"]
app.UseMvcWithDefaultRoute();
});
}
Estender a inicialização com filtros de inicialização

Use IStartupFilter para configurar o middleware no início ou no final do pipeline do middleware Configure de
um aplicativo. IStartupFilter é útil para garantir que um middleware seja executado antes ou depois do
middleware adicionado pelas bibliotecas no início ou no final do pipeline de processamento de solicitação do
aplicativo.
IStartupFilter implementa um único método, Configure, que recebe e retorna um
Action<IApplicationBuilder> . Um IApplicationBuilder define uma classe para configurar o pipeline de
solicitação do aplicativo. Para obter mais informações, confira Criar um pipeline de middleware com o
IApplicationBuilder.
Cada IStartupFilter implementa uma ou mais middlewares no pipeline de solicitação. Os filtros são
invocados na ordem em que foram adicionados ao contêiner de serviço. Filtros podem adicionar middleware
antes ou depois de passar o controle para o filtro seguinte, de modo que eles são acrescentados ao início ou no
final do pipeline de aplicativo.
O aplicativo de exemplo demonstra como registrar um middleware com IStartupFilter . O aplicativo de
exemplo inclui um middleware que define um valor de opção de um parâmetro de cadeia de caracteres de
consulta:
public class RequestSetOptionsMiddleware

{
private readonly RequestDelegate _next;
private IOptions<AppOptions> _injectedOptions;
public RequestSetOptionsMiddleware(
RequestDelegate next, IOptions<AppOptions> injectedOptions)
{
_next = next;
_injectedOptions = injectedOptions;
}
public async Task Invoke(HttpContext httpContext)

{
Console.WriteLine("RequestSetOptionsMiddleware.Invoke");
var option = httpContext.Request.Query["option"];
if (!string.IsNullOrWhiteSpace(option))
{
_injectedOptions.Value.Option = WebUtility.HtmlEncode(option);
}
await _next(httpContext);
}
}
O RequestSetOptionsMiddleware é configurado na classe RequestSetOptionsStartupFilter :
public class RequestSetOptionsStartupFilter : IStartupFilter

{
public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
{
return builder =>
{
builder.UseMiddleware<RequestSetOptionsMiddleware>();
next(builder);
};
}
}
O IStartupFilter está registrado no contêiner de serviço do IWebHostBuilder.ConfigureServices para

demonstrar como o filtro de inicialização aumenta a Startup externa da classe Startup :
.ConfigureServices(services =>
{
services.AddTransient<IStartupFilter,
RequestSetOptionsStartupFilter>();
})
.Build();
Quando um parâmetro de cadeia de caracteres de consulta para option é fornecido, o middleware processa a
atribuição de valor antes que o middleware do MVC renderize a resposta:
A ordem de execução do middleware é definida pela ordem dos registros IStartupFilter :
Várias implementações de IStartupFilter podem interagir com os mesmos objetos. Se a ordem for
importante, ordene seus registros de serviço IStartupFilter para corresponder à ordem em que os
middlewares devem ser executados.
Bibliotecas podem adicionar middleware com uma ou mais implementações de IStartupFilter que são
executadas antes ou depois de outro middleware de aplicativo registrado com IStartupFilter . Para invocar
um middleware IStartupFilter antes de um middleware adicionado pelo IStartupFilter de uma
biblioteca, posicione o registro do serviço antes da biblioteca ser adicionada ao contêiner de serviço. Para
invocá-lo posteriormente, posicione o registro do serviço após a biblioteca ser adicionada.
Adicionar configuração na inicialização usando um assembly externo

Uma implementação IHostingStartup permite adicionar melhorias a um aplicativo durante a inicialização de
um assembly externo fora da classe Startup do aplicativo. Para obter mais informações, veja Aprimorar um
aplicativo de um assembly externo.
Recursos adicionais
Host no ASP.NET Core
Usar vários ambientes no ASP.NET Core
Middleware do ASP.NET Core
Registro em log no ASP.NET Core
Configuração no ASP.NET Core
Injeção de dependência no ASP.NET
Core
Por Steve Smith, Scott Addie e Luke Latham

O ASP.NET Core dá suporte ao padrão de design de software de DI (injeção de
dependência), que é uma técnica para conseguir IoC (inversão de controle) entre
classes e suas dependências.
Para obter mais informações específicas sobre injeção de dependência em
controladores de MVC, consulte Injeção de dependência em controladores no
ASP.NET Core.
Visão geral da injeção de dependência

Uma dependência é qualquer objeto exigido por outro objeto. Examine a classe
MyDependency a seguir com um método WriteMessage do qual outras classes em um
aplicativo dependem:
public class MyDependency

{
public MyDependency()
{
}
public Task WriteMessage(string message)

{
Console.WriteLine(
$"MyDependency.WriteMessage called. Message: {message}");
return Task.FromResult(0);
}
}
Uma instância da classe MyDependency pode ser criada para tornar o método
WriteMessage disponível para uma classe. A classe MyDependency é uma dependência
da classe IndexModel :
public class IndexModel : PageModel

{
MyDependency _dependency = new MyDependency();
public async Task OnGetAsync()

{
await _dependency.WriteMessage(
"IndexModel.OnGetAsync created this message.");
}
}
Uma instância da classe MyDependency pode ser criada para tornar o método
WriteMessage disponível para uma classe. A classe MyDependency é uma dependência
da classe HomeController :
public class HomeController : Controller

{
MyDependency _dependency = new MyDependency();
public async Task<IActionResult> Index()

{
await _dependency.WriteMessage(
"HomeController.Index created this message.");
return View();
}
}
A classe cria e depende diretamente da instância MyDependency . As dependências de

código (como no exemplo anterior) são problemáticas e devem ser evitadas por estes
motivos:
Para substituir MyDependency por uma implementação diferente, a classe deve ser
modificada.
Se MyDependency tiver dependências, elas deverão ser configuradas pela classe. Em
um projeto grande com várias classes dependendo da MyDependency , o código de
configuração fica pulverizado por todo o aplicativo.
É difícil testar a unidade dessa implementação. O aplicativo deve usar uma
simulação ou stub da classe MyDependency , o que não é possível com essa
abordagem.
Injeção de dependência trata desses problemas da seguinte maneira:
Usando uma interface para abstrair a implementação da dependência.
Registrando a dependência em um contêiner de serviço. O ASP.NET Core fornece
um contêiner de serviço interno, o IServiceProvider. Os serviços são registrados
no método Startup.ConfigureServices do aplicativo.
Injeção do serviço no construtor da classe na qual ele é usado. A estrutura assume
a responsabilidade de criar uma instância da dependência e de descartá-la quando
não for mais necessária.
No exemplo de aplicativo, a interface IMyDependency define um método que o serviço
fornece ao aplicativo:
public interface IMyDependency

{
Task WriteMessage(string message);
}
public interface IMyDependency

{
Task WriteMessage(string message);
}
Essa interface é implementada por um tipo concreto, MyDependency :

public class MyDependency : IMyDependency
{
private readonly ILogger<MyDependency> _logger;
public MyDependency(ILogger<MyDependency> logger)

{
_logger = logger;
}

{
_logger.LogInformation(
"MyDependency.WriteMessage called. Message: {MESSAGE}",
message);
}
}

{
private readonly ILogger<MyDependency> _logger;
public MyDependency(ILogger<MyDependency> logger)

{
_logger = logger;
}

{
"MyDependency.WriteMessage called. Message: {MESSAGE}",
message);
}
}
MyDependency solicita um ILogger<TCategoryName> em seu construtor. Não é

incomum usar a injeção de dependência de uma maneira encadeada. Por sua vez,
cada dependência solicitada solicita suas próprias dependências. O contêiner resolve
as dependências no grafo e retorna o serviço totalmente resolvido. O conjunto de
dependências que precisa ser resolvido normalmente é chamado de árvore de
dependência, grafo de dependência ou grafo de objeto.
IMyDependency e ILogger<TCategoryName>devem ser registrados no contêiner do
serviço. IMyDependency está registrado em Startup.ConfigureServices .
ILogger<TCategoryName> é registrado pela infraestrutura de abstrações de registro em
log, portanto, é um serviço fornecido por estrutura registrado por padrão pela
estrutura.
No exemplo de aplicativo, o serviço IMyDependency está registrado com o tipo
concreto MyDependency . O registro define o escopo do tempo de vida do serviço para
o tempo de vida de uma única solicitação. Descreveremos posteriormente neste
tópico os tempos de vida do serviço.
{
{
});
services.AddScoped<IMyDependency, MyDependency>();
services.AddTransient<IOperationTransient, Operation>();
services.AddScoped<IOperationScoped, Operation>();
services.AddSingleton<IOperationSingleton, Operation>();
services.AddSingleton<IOperationSingletonInstance>(new Operation(Guid.Empty));
// OperationService depends on each of the other Operation types.

services.AddTransient<OperationService, OperationService>();
}

{
services.AddMvc();

}
NOTE
Cada método de extensão services.Add{SERVICE_NAME} adiciona (e possivelmente
configura) serviços. Por exemplo, services.AddMvc() adiciona os serviços exigidos pelo
MVC e por Razor Pages. Recomendamos que os aplicativos sigam essa convenção. Coloque
os métodos de extensão no namespace Microsoft.Extensions.DependencyInjection para
encapsular grupos de registros de serviço.
Se o construtor do serviço exigir um primitivo, como um string , o primitivo poderá

ser injetado usando a configuração ou o padrão de opções:

{
public MyDependency(IConfiguration config)
{
var myStringValue = config["MyStringKey"];
// Use myStringValue
}
...
}
Uma instância do serviço é solicitada por meio do construtor de uma classe, onde o
serviço é usado e atribuído a um campo particular. O campo é usado para acessar o
serviço conforme o necessário na classe.
No exemplo de aplicativo, a instância IMyDependency é solicitada e usada para chamar
o método WriteMessage do serviço:

{
private readonly IMyDependency _myDependency;
public IndexModel(
IMyDependency myDependency,
OperationService operationService,
IOperationTransient transientOperation,
IOperationScoped scopedOperation,
IOperationSingleton singletonOperation,
IOperationSingletonInstance singletonInstanceOperation)
{
_myDependency = myDependency;
OperationService = operationService;
TransientOperation = transientOperation;
ScopedOperation = scopedOperation;
SingletonOperation = singletonOperation;
SingletonInstanceOperation = singletonInstanceOperation;
}
public OperationService OperationService { get; }

public IOperationTransient TransientOperation { get; }
public IOperationScoped ScopedOperation { get; }
public IOperationSingleton SingletonOperation { get; }
public IOperationSingletonInstance SingletonInstanceOperation { get; }

{
await _myDependency.WriteMessage(
}
}
public class MyDependencyController : Controller

{
public MyDependencyController(IMyDependency myDependency)

{
}
// GET: /mydependency/
{
"MyDependencyController.Index created this message.");
return View();
}
}
Serviços fornecidos pela estrutura

O método Startup.ConfigureServices é responsável por definir os serviços usados
pelo aplicativo, incluindo recursos de plataforma como o Entity Framework Core e o
ASP.NET Core MVC. Inicialmente, a IServiceCollection fornecida ao
ConfigureServices tem os seguintes serviços definidos (dependendo de como o host
foi configurado):
TIPO DE SERVIÇO TEMPO DE VIDA
Microsoft.AspNetCore.Hosting.Builder.IApplica Transitório
tionBuilderFactory
Microsoft.AspNetCore.Hosting.IApplicationLife Singleton
time
Microsoft.AspNetCore.Hosting.IHostingEnviro Singleton
nment
Microsoft.AspNetCore.Hosting.IStartup Singleton
Microsoft.AspNetCore.Hosting.IStartupFilter Transitório
Microsoft.AspNetCore.Hosting.Server.IServer Singleton
Microsoft.AspNetCore.Http.IHttpContextFacto Transitório
ry
Microsoft.Extensions.Logging.ILogger<T> Singleton
Microsoft.Extensions.Logging.ILoggerFactory Singleton
Microsoft.Extensions.ObjectPool.ObjectPoolPr Singleton
ovider
Microsoft.Extensions.Options.IConfigureOptio Transitório
ns<T>
Microsoft.Extensions.Options.IOptions<T> Singleton
System.Diagnostics.DiagnosticSource Singleton
System.Diagnostics.DiagnosticListener Singleton
Quando um método de extensão de coleta do serviço estiver disponível para registrar

um serviço (e seus serviços dependentes, se for necessário), a convenção é usar um
único método de extensão Add{SERVICE_NAME} para registrar todos os serviços
exigidos por esse serviço. O código a seguir é um exemplo de como adicionar outros
serviços ao contêiner usando os métodos de extensão AddDbContext, AddIdentity e
AddMvc:
{
services.AddMvc();
}
Para saber mais, confira a Classe ServiceCollection na documentação da API.
Tempos de vida do serviço

Escolha um tempo de vida apropriado para cada serviço registrado. Os serviços do
ASP.NET Core podem ser configurados com os seguintes tempos de vida:
Transitório
Os serviços com tempo de vida transitório são criados sempre que são solicitados.
Esse tempo de vida funciona melhor para serviços leves e sem estado.
Com escopo
Os serviços com tempo de vida com escopo são criados uma vez por solicitação.
WARNING
Ao usar um serviço com escopo em um middleware, injete o serviço no método Invoke ou
InvokeAsync . Não injete por meio de injeção de construtor porque isso força o serviço a se
comportar como um singleton. Para obter mais informações, consulte Middleware do
ASP.NET Core.
Singleton
Serviços de tempo de vida singleton são criados na primeira solicitação (ou quando
ConfigureServices é executado e uma instância é especificada com o registro do
serviço). Cada solicitação subsequente usa a mesma instância. Se o aplicativo exigir
um comportamento de singleton, recomendamos permitir que o contêiner do serviço
gerencie o tempo de vida do serviço. Não implemente o padrão de design singleton e
forneça o código de usuário para gerenciar o tempo de vida do objeto na classe.
WARNING
É perigoso resolver um serviço com escopo de um singleton. Pode fazer com que o serviço
tenha um estado incorreto durante o processamento das solicitações seguintes.
Comportamento da injeção de construtor

Os serviços podem ser resolvidos por dois mecanismos:
IServiceProvider
ActivatorUtilities – Permite a criação de objetos sem registro do serviço no
contêiner de injeção de dependência. ActivatorUtilities é usado com abstrações
voltadas ao usuário, como Auxiliares de Marca, controladores MVC e associadores
de modelo.
Os construtores podem aceitar argumentos que não são fornecidos pela injeção de
dependência, mas que precisam atribuir valores padrão.
Quando os serviços são resolvidos por IServiceProvider ou ActivatorUtilities ,a
injeção do construtor exige um construtor público.
Quando os serviços são resolvidos por ActivatorUtilities , a injeção de construtor
exige a existência de apenas de um construtor aplicável. Há suporte para sobrecargas
de construtor, mas somente uma sobrecarga pode existir, cujos argumentos podem
ser todos atendidos pela injeção de dependência.
Contextos de Entity Framework

Os contextos do Entity Framework devem ser adicionados ao contêiner de serviços
usando o tempo de vida com escopo. Isso é tratado automaticamente com uma
chamada para o método AddDbContext ao registrar o contexto do banco de dados.
Os serviços que usam o contexto de banco de dados também devem usar o tempo de
vida com escopo.
Opções de tempo de vida e de registro

Para demonstrar a diferença entre as opções de tempo de vida e de registro,
considere as interfaces a seguir, que representam tarefas como uma operação com
um identificador exclusivo, OperationId . Dependendo de como o tempo de vida de
um serviço de operações é configurado para as interfaces a seguir, o contêiner fornece
a mesma instância do serviço, ou outra diferente, quando recebe uma solicitação de
uma classe:
public interface IOperation

{
Guid OperationId { get; }
}
public interface IOperationTransient : IOperation

{
}
public interface IOperationScoped : IOperation

{
}
public interface IOperationSingleton : IOperation

{
}
public interface IOperationSingletonInstance : IOperation

{
}
public interface IOperation
{
Guid OperationId { get; }
}
public interface IOperationTransient : IOperation

{
}
public interface IOperationScoped : IOperation

{
}
public interface IOperationSingleton : IOperation

{
}
public interface IOperationSingletonInstance : IOperation

{
}
As interfaces são implementadas na classe Operation . O construtor Operation gera

um GUID, caso um não seja fornecido:
public class Operation : IOperationTransient,

IOperationScoped,
IOperationSingleton,
IOperationSingletonInstance
{
public Operation() : this(Guid.NewGuid())
{
}
public Operation(Guid id)

{
OperationId = id;
}
public Guid OperationId { get; private set; }

}
public class Operation : IOperationTransient,

IOperationScoped,
IOperationSingleton,
IOperationSingletonInstance
{
public Operation() : this(Guid.NewGuid())
{
}
public Operation(Guid id)

{
OperationId = id;
}
public Guid OperationId { get; private set; }

}
Há um OperationService registrado que depende de cada um dos outros Operation

tipos. Quando OperationService é solicitado por meio da injeção de dependência, ele
recebe a uma nova instância de cada serviço, ou uma instância existente com base no
tempo de vida do serviço dependente.
Se os serviços temporários forem criados mediante solicitação, o OperationId do
serviço IOperationTransient será diferente do OperationId do OperationService .
OperationService recebe uma nova instância da classe IOperationTransient . A
nova instância produz outro OperationId .
Se os serviços com escopo forem criados por solicitação, o OperationId do
serviço IOperationScoped será o mesmo de OperationService dentro de uma
solicitação. Em todas as solicitações, os dois serviços compartilham um valor de
OperationId diferente.
Se os serviços singleton e de instância singleton forem criados uma vez e usados
em todas as solicitações e em todos os serviços, o OperationId será constante
entre todas as solicitações de serviço.
public class OperationService

{
public OperationService(
IOperationSingletonInstance instanceOperation)
{
SingletonInstanceOperation = instanceOperation;
}

}
public class OperationService

{
public OperationService(IOperationTransient transientOperation,
IOperationSingletonInstance instanceOperation)
{
SingletonInstanceOperation = instanceOperation;
}

}
Em Startup.ConfigureServices , cada tipo é adicionado ao contêiner de acordo com

seu tempo de vida nomeado:
{
{
});

}

{
services.AddMvc();

}
O serviço IOperationSingletonInstance está usando uma instância específica com

uma ID conhecida de Guid.Empty . Fica claro quando esse tipo está em uso (seu GUID
contém apenas zeros).
O exemplo de aplicativo demonstra os tempos de vida do objeto dentro e entre
solicitações individuais. O exemplo de aplicativo IndexModel solicita cada tipo
IOperation e o OperationService . Depois, a página exibe todos os valores de
OperationId da classe de modelo de página e do serviço por meio de atribuições de
propriedade:
{
public IndexModel(
IMyDependency myDependency,
{
OperationService = operationService;
SingletonInstanceOperation = singletonInstanceOperation;
}
public OperationService OperationService { get; }


{
}
}
O exemplo de aplicativo demonstra os tempos de vida do objeto dentro e entre

solicitações individuais. O exemplo de aplicativo inclui um OperationsController que
solicita cada tipo de IOperation e o OperationService . A ação Index define os
serviços no ViewBag para exibição dos valores OperationId do serviço:
public class OperationsController : Controller
{
private readonly OperationService _operationService;
private readonly IOperationTransient _transientOperation;
private readonly IOperationScoped _scopedOperation;
private readonly IOperationSingleton _singletonOperation;
private readonly IOperationSingletonInstance _singletonInstanceOperation;
public OperationsController(
{
_operationService = operationService;
_transientOperation = transientOperation;
_scopedOperation = scopedOperation;
_singletonOperation = singletonOperation;
_singletonInstanceOperation = singletonInstanceOperation;
}
public IActionResult Index()

{
// Viewbag contains controller-requested services.
ViewBag.Transient = _transientOperation;
ViewBag.Scoped = _scopedOperation;
ViewBag.Singleton = _singletonOperation;
ViewBag.SingletonInstance = _singletonInstanceOperation;
// Operation service has its own requested services.

ViewBag.Service = _operationService;
return View();
}
}
As duas saídas a seguir mostram os resultados das duas solicitações:

Primeira solicitação:
Operações do controlador:
Transitória: d233e165-f417-469b-a866-1cf1935d2518
Com escopo: 5d997e2d-55f5-4a64-8388-51c4e3a1ad19
Singleton: 01271bc1-9e31-48e7-8f7c-7261b040ded9
Instância: 00000000-0000-0000-0000-000000000000
OperationService operações:
Transitória: c6b049eb-1318-4e31-90f1-eb2dd849ff64
Com escopo: 5d997e2d-55f5-4a64-8388-51c4e3a1ad19
Instância: 00000000-0000-0000-0000-000000000000
Segunda solicitação:
Operações do controlador:
Transitória: b63bd538-0a37-4ff1-90ba-081c5138dda0
Com escopo: 31e820c5-4834-4d22-83fc-a60118acb9f4
Instância: 00000000-0000-0000-0000-000000000000
OperationService operações:
Transitória: c4cbacb8-36a2-436d-81c8-8c1b78808aaf
Com escopo: 31e820c5-4834-4d22-83fc-a60118acb9f4
Instância: 00000000-0000-0000-0000-000000000000
Observe qual dos valores de OperationId varia em uma solicitação, e entre as
solicitações:
Os objetos transitórios sempre são diferentes. Observe que o valor OperationId
transitório da primeira e da segunda solicitações é diferente para as duas
operações OperationService e em todas as solicitações. Uma nova instância é
fornecida para cada solicitação e serviço.
Os objetos com escopo são os mesmos em uma solicitação, mas diferentes entre
solicitações.
Os pbjetos singleton são os mesmos para cada objeto e solicitação,
independentemente de uma instância Operation ser fornecida em
ConfigureServices .
Chamar os serviços desde o principal

Crie um IServiceScope com IServiceScopeFactory.CreateScope para resolver um
serviço com escopo dentro do escopo do aplicativo. Essa abordagem é útil para
acessar um serviço com escopo durante a inicialização para executar tarefas de
inicialização. O exemplo a seguir mostra como obter um contexto para o
MyScopedService em Program.Main :

{
var host = CreateWebHostBuilder(args).Build();
using (var serviceScope = host.Services.CreateScope())

{
var services = serviceScope.ServiceProvider;
try
{
var serviceContext = services.GetRequiredService<MyScopedService>();
// Use the context here
}
catch (Exception ex)
{
var logger = services.GetRequiredService<ILogger<Program>>();
logger.LogError(ex, "An error occurred.");
}
}
host.Run();
}
Validação de escopo
Quando o aplicativo está em execução no ambiente de desenvolvimento, o provedor
de serviço padrão executa verificações para saber se:
Os serviços com escopo não são resolvidos direta ou indiretamente pelo provedor
de serviço raiz.
Os serviços com escopo não são injetados direta ou indiretamente em singletons.
O provedor de serviços raiz é criado quando BuildServiceProvider é chamado. O
tempo de vida do provedor de serviço raiz corresponde ao tempo de vida do
aplicativo/servidor quando o provedor começa com o aplicativo e é descartado
quando o aplicativo é desligado.
Os serviços com escopo são descartados pelo contêiner que os criou. Se um serviço
com escopo é criado no contêiner raiz, o tempo de vida do serviço é promovido
efetivamente para singleton, porque ele só é descartado pelo contêiner raiz quando o
aplicativo/servidor é desligado. A validação dos escopos de serviço detecta essas
situações quando BuildServiceProvider é chamado.
Para obter mais informações, consulte Host da Web do ASP.NET Core.
Serviços de solicitação
Os serviços disponíveis em uma solicitação do ASP.NET de HttpContext são
expostos por meio da coleção HttpContext.RequestServices.
Os Serviços de Solicitação representam os serviços configurados e solicitados como
parte do aplicativo. Quando os objetos especificam dependências, elas são atendidas
pelos tipos encontrados em RequestServices , não em ApplicationServices .
Em geral, o aplicativo não deve usar essas propriedades diretamente. Em vez disso,
solicite os tipos exigidos pelas classes por meio de construtores de classe e permita
que a estrutura injete as dependências. Isso resulta em classes que são mais fáceis de
testar (confira os tópicos Testar e depurar).
NOTE
Prefira solicitar dependências como parâmetros de construtor para acessar a coleção
RequestServices .
Projetar serviços para injeção de dependência

As melhores práticas são:
Projetar serviços para usar a injeção de dependência a fim de obter suas
dependências.
Evite chamadas de método estático com estado (uma prática conhecida como
adesão estática).
Evite a instanciação direta das classes dependentes em serviços. A instanciação
direta acopla o código a uma implementação específica.
Seguindo os Princípios SOLID de Design Orientado a Objeto, as classes de aplicativo
naturalmente tendem a ser pequenas, bem fatoradas e facilmente testadas.
Se parecer que uma classe tem muitas dependências injetadas, normalmente é um
sinal de que a classe tem muitas responsabilidades e está violando o Princípio da
Responsabilidade Única (SRP ). Tente refatorar a classe movendo algumas de suas
responsabilidades para uma nova classe. Lembre-se de que as classes de modelo de
página de Razor Pages e as classes do controlador de MVC devem se concentrar em
questões de interface do usuário. Os detalhes de implementação de acesso aos dados
e as regras de negócios devem ser mantidos em classes apropriadas a esses
interesses separados.
Descarte de serviços
O contêiner chama Dispose para os tipos IDisposable criados por ele. Se uma
instância for adicionada ao contêiner pelo código do usuário, ele não será descartado
automaticamente.
// Services that implement IDisposable:

public class Service1 : IDisposable {}
public interface ISomeService {}

public class SomeServiceImplementation : ISomeService, IDisposable {}

{
// The container creates the following instances and disposes them
automatically:
services.AddScoped<Service1>();
services.AddSingleton<Service2>();
services.AddSingleton<ISomeService>(sp => new SomeServiceImplementation());
// The container doesn't create the following instances, so it doesn't dispose

of
// the instances automatically:
services.AddSingleton<Service3>(new Service3());
services.AddSingleton(new Service3());
}
NOTE
No ASP.NET Core 1.0, as chamadas do contêiner descartam todos os objetos IDisposable ,
incluindo aqueles que ele não criou.
Substituição do contêiner de serviço padrão

O contêiner de serviço interno deve atender às necessidades da estrutura e da
maioria dos aplicativos do consumidor. É recomendado usar o contêiner interno, a
menos que você precise de um recurso específico que não seja compatível com ele.
Alguns dos recursos compatíveis com contêineres de terceiros não encontrados no
contêiner interno:
Injeção de propriedade
Injeção com base no nome
Contêineres filho
Gerenciamento de tempo de vida personalizado
Suporte de Func<T> para inicialização lenta
Confira o arquivo readme.md de injeção de dependência para obter uma lista de

alguns dos contêineres que dão suporte a adaptadores.
O exemplo a seguir substitui o contêiner interno por Autofac:
Instale os pacotes de contêiner apropriados:
Autofac
Autofac.Extensions.DependencyInjection
Configure o contêiner no Startup.ConfigureServices e retorne um
IServiceProvider :
public IServiceProvider ConfigureServices(IServiceCollection services)

{
services.AddMvc();
// Add other framework services
// Add Autofac
var containerBuilder = new ContainerBuilder();
containerBuilder.RegisterModule<DefaultModule>();
containerBuilder.Populate(services);
var container = containerBuilder.Build();
return new AutofacServiceProvider(container);
}
Para usar um contêiner de terceiros, Startup.ConfigureServices deve retornar

IServiceProvider .
Configure o Autofac em DefaultModule :
public class DefaultModule : Module

{
protected override void Load(ContainerBuilder builder)
{
builder.RegisterType<CharacterRepository>
().As<ICharacterRepository>();
}
}
Em tempo de execução, o Autofac é usado para resolver tipos e injetar dependências.

Para saber mais sobre como usar o Autofac com o ASP.NET Core, consulte a
documentação do Autofac.
Acesso thread-safe
Os serviços Singleton precisam ser thread-safe. Se um serviço singleton tiver uma
dependência em um serviço transitório, o serviço transitório também precisará ser
thread-safe, dependendo de como ele é usado pelo singleton.
O método de fábrica de um único serviço, como o segundo argumento para
AddSingleton<TService>(IServiceCollection, Func<IServiceProvider,TService>), não
precisa ser thread-safe. Como um construtor do tipo ( static ), ele tem garantia de ser
chamado uma vez por um único thread.
Recomendações
A resolução de serviço baseada em async/await e Task não é compatível. O
C# não é compatível com os construtores assíncronos. Portanto, o padrão
recomendado é usar os métodos assíncronos após a resolução síncrona do
serviço.
Evite armazenar dados e a configuração diretamente no contêiner do serviço.
Por exemplo, o carrinho de compras de um usuário normalmente não deve ser
adicionado ao contêiner do serviço. A configuração deve usar o padrão de
opções. Da mesma forma, evite objetos de "suporte de dados" que existem
somente para permitir o acesso a outro objeto. É melhor solicitar o item real
por meio da DI.
Evite o acesso estático aos serviços (por exemplo, digitando estaticamente
IApplicationBuilder.ApplicationServices para usar em outro lugar).
Evite usar o padrão do localizador de serviço. Por exemplo, não invoque
GetService para obter uma instância de serviço quando for possível usar a DI.
Outra variação de localizador de serviço a ser evitada é injetar um alocador
que resolve as dependências em tempo de execução. Essas duas práticas
misturam estratégias de inversão de controle.
Evite o acesso estático a HttpContext (por exemplo,
IHttpContextAccessor.HttpContext).
Como todos os conjuntos de recomendações, talvez você encontre situações em que é
necessário ignorar uma recomendação. As exceções são raras —principalmente casos
especiais dentro da própria estrutura.
A DI é uma alternativa aos padrões de acesso a objeto estático/global. Talvez você
não obtenha os benefícios da DI se combiná-lo com o acesso a objeto estático.
Recursos adicionais
Injeção de dependência em exibições no ASP.NET Core
Injeção de dependência em controladores no ASP.NET Core
Injeção de dependência em manipuladores de requisito no ASP.NET Core
<xref:test/index>
Ativação de middleware baseada em alocador no ASP.NET Core
Como escrever um código limpo no ASP.NET Core com injeção de dependência
(MSDN )
Design de aplicativo gerenciado por contêiner, prelúdio: a que local o contêiner
pertence?
Princípio de Dependências Explícitas
Inversão de Contêineres de Controle e o padrão de Injeção de Dependência
(Martin Fowler)
New is Glue ("colando" o código em uma implementação específica)
Como registrar um serviço com várias interfaces na DI do ASP.NET Core
Roteamento no ASP.NET Core
Por Ryan Nowak, Steve Smith e Rick Anderson

A funcionalidade de roteamento é responsável por mapear uma solicitação de entrada para um manipulador
de rotas. As rotas são definidas no aplicativo e configuradas quando o aplicativo é iniciado. Uma rota pode
opcionalmente extrair os valores da URL contida na solicitação e esses valores podem então ser usados para
o processamento da solicitação. Usando as informações de rota do aplicativo, a funcionalidade de
roteamento também é capaz de gerar URLs que são mapeadas para manipuladores de rotas. Portanto, o
roteamento pode encontrar um manipulador de rotas com base em uma URL ou encontrar a URL
correspondente a um determinado manipulador de rotas com base nas informações do manipulador de
rotas.
IMPORTANT
Este documento aborda o roteamento de nível inferior do ASP.NET Core. Para obter informações sobre o roteamento
do ASP.NET Core MVC, confira Roteamento para ações do controlador no ASP.NET Core.
Conceitos básicos sobre roteamento

O roteamento usa rotas (implementações de IRouter) para:
Mapear solicitações de entrada para manipuladores de rotas.
Gerar as URLs usadas nas respostas.
Em geral, um aplicativo tem uma única coleção de rotas. Quando uma solicitação é recebida, a coleção de
rotas é processada na ordem. A solicitação de entrada procura uma rota que corresponde à URL de
solicitação chamando o método RouteAsync em cada rota disponível na coleção de rotas. Por outro lado,
uma resposta pode usar o roteamento para gerar URLs (por exemplo, para redirecionamento ou links) com
base nas informações de rotas e evitar a necessidade de embutir as URLs em código, o que ajuda na
facilidade de manutenção.
O roteamento está conectado ao pipeline do middleware pela classe RouterMiddleware. O ASP.NET Core
MVC adiciona o roteamento ao pipeline do middleware como parte de sua configuração. Para saber mais
sobre o uso do roteamento como um componente autônomo, confira a seção Usar o middleware de
roteamento.
Correspondência de URL
Correspondência de URL é o processo pelo qual o roteamento expede uma solicitação de entrada para um
manipulador. Esse processo se baseia nos dados do caminho da URL, mas pode ser estendido para
considerar qualquer dado na solicitação. A capacidade de expedir solicitações para manipuladores separados
é fundamental para dimensionar o tamanho e a complexidade de um aplicativo.
As solicitações de entrada entram no RouterMiddleware , que chama o método RouteAsync em cada rota na
sequência. A instância IRouter escolhe se deseja manipular a solicitação definindo o RouteContext.Handler
como um RequestDelegate não nulo. Se uma rota definir um manipulador para a solicitação, o
processamento de rotas será interrompido e o manipulador será invocado para processar a solicitação. Se
todas as rotas forem testadas e nenhum manipulador for encontrado para a solicitação, o middleware
chamará o próximo e o próximo middleware no pipeline da solicitação será invocado.
A entrada primária para RouteAsync é o RouteContext.HttpContext associado à solicitação atual. O
RouteContext.Handler e o RouteContext.RouteData são os resultados definidos depois que uma rota é
correspondida.
Uma correspondência durante RouteAsync também define as propriedades de RouteContext.RouteData para
os valores apropriados com base no processamento da solicitação executado até o momento. Se uma rota
corresponde a uma solicitação, o RouteContext.RouteData contém informações de estado importantes sobre
o resultado.
RouteData.Values é um dicionário de valores de rota produzido por meio da rota. Esses valores geralmente
são determinados pela criação de token da URL e podem ser usados para aceitar a entrada do usuário ou
tomar outras decisões de expedição dentro do aplicativo.
RouteData.DataTokens é um recipiente de propriedades de dados adicionais relacionados à rota
correspondente. DataTokens são fornecidos para dar suporte à associação de dados de estado com cada
rota para que o aplicativo possa tomar decisões posteriormente com base em qual rota foi correspondida.
Esses valores são definidos pelo desenvolvedor e não afetam de forma alguma o comportamento do
roteamento. Além disso, os valores armazenados em stash em RouteData.DataTokens podem ser de qualquer
tipo, ao contrário de RouteData.Values , que precisa ser facilmente conversível de/em cadeias de caracteres.
RouteData.Routers é uma lista das rotas que participaram da correspondência bem-sucedida da solicitação.
As rotas podem ser aninhadas uma dentro da outra. A propriedade Routers reflete o caminho pela árvore
lógica de rotas que resultou em uma correspondência. Em geral, o primeiro item em Routers é a coleção de
rotas e deve ser usado para a geração de URL. O último item em Routers é o manipulador de rotas que
teve uma correspondência.
Geração de URL
Geração de URL é o processo pelo qual o roteamento pode criar um caminho de URL de acordo com um
conjunto de valores de rota. Isso permite uma separação lógica entre os manipuladores e as URLs que os
acessam.
A geração de URL segue um processo iterativo semelhante, mas começa com o código da estrutura ou do
usuário chamando o método GetVirtualPath da coleção de rotas. Em seguida, cada rota terá seu método
GetVirtualPath chamado em sequência, até que um VirtualPathData não nulo seja retornado.
As entradas primárias para GetVirtualPath são:

VirtualPathContext.HttpContext
VirtualPathContext.Values
VirtualPathContext.AmbientValues
As rotas usam principalmente os valores de rota fornecidos por Values e AmbientValues para decidir se é
possível gerar uma URL e quais valores serão incluídos. Os AmbientValues são o conjunto de valores de rota
produzidos pela correspondência da solicitação atual com o sistema de roteamento. Por outro lado, Values
são os valores de rota que especificam como gerar a URL desejada para a operação atual. O HttpContext é
fornecido para o caso de uma rota precisar obter serviços ou dados adicionais associados ao contexto atual.
TIP
Considere VirtualPathContext.Values como um conjunto de substituições de VirtualPathContext.AmbientValues. A
geração de URL tenta reutilizar os valores de rota da solicitação atual para facilitar a geração de URLs para links
usando a mesma rota ou os mesmos valores de rota.
A saída de GetVirtualPath é um VirtualPathData. VirtualPathData é um paralelo de RouteData .
VirtualPathData contém o VirtualPath da URL de saída e algumas propriedades adicionais que devem ser
definidas pela rota.
A propriedade VirtualPathData.VirtualPath contém o caminho virtual produzido pela rota. Dependendo das
suas necessidades, talvez você precise processar ainda mais o caminho. Se você desejar renderizar a URL
gerada em HTML, preceda o caminho base do aplicativo.
O VirtualPathData.Router é uma referência à rota que gerou a URL com êxito.
As propriedades de VirtualPathData.DataTokens são um dicionário de dados adicionais relacionados à rota
que gerou a URL. Isso é o paralelo de RouteData.DataTokens.
Criando rotas
O roteamento fornece a classe Route como a implementação padrão de IRouter. Route usa a sintaxe de
modelo de rota para definir padrões que corresponderão ao caminho da URL quando RouteAsync for
chamado. Route usa o mesmo modelo de rota para gerar uma URL quando GetVirtualPath é chamado.
A maioria dos aplicativos cria rotas chamando MapRoute ou um dos métodos de extensão semelhantes
definidos em IRouteBuilder. Todos esses métodos criam uma instância de Route e adicionam-na à coleção
de rotas.
MapRoute não usa um parâmetro de manipulador de rota. MapRoute apenas adiciona rotas que são
manipuladas pelo DefaultHandler. Como o manipulador padrão é um IRouter , ele pode optar por não
manipular a solicitação. Por exemplo, o ASP.NET Core MVC normalmente é configurado como um
manipulador padrão que só manipula as solicitações que correspondem a um controlador e a uma ação
disponíveis. Para saber mais sobre o roteamento para o MVC, confira Roteamento para ações do
controlador no ASP.NET Core.
O exemplo de código a seguir é um exemplo de uma chamada MapRoute usada por uma definição de rota
típica do ASP.NET Core MVC:
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
Esse modelo corresponde a um caminho de URL, como /Products/Details/17 e extrai os valores de rota
{ controller = Products, action = Details, id = 17 } . Os valores de rota são determinados pela divisão do
caminho da URL em segmentos e pela correspondência de cada segmento com o nome parâmetro de rota
no modelo de rota. Os parâmetros de rota são nomeados. Eles são definidos com a colocação do nome do
parâmetro em chaves { ... } .
O modelo anterior também poderia corresponder ao caminho da URL / e produziria os valores
{ controller = Home, action = Index } . Isso ocorre porque os parâmetros de rota {controller} e {action}
têm valores padrão e o parâmetro de rota id é opcional. Um sinal de igual = seguido de um valor após o
nome do parâmetro de rota define um valor padrão para o parâmetro. Um ponto de interrogação ? após o
nome do parâmetro de rota define o parâmetro como opcional. Os parâmetros de rota com um valor padrão
sempre produzem um valor de rota quando a rota corresponde. Os parâmetros opcionais não produzem um
valor de rota quando não há nenhum segmento de caminho de URL correspondente.
Consulte route-template-reference para obter uma descrição completa dos recursos e da sintaxe de modelo
de rota.
Este exemplo inclui uma restrição de rota:
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id:int}");
Esse modelo corresponde a um caminho de URL, como /Products/Details/17 , mas não como
/Products/Details/Apples . A definição do parâmetro de rota {id:int} define uma restrição de rota para o
parâmetro de rota id . As restrições de rota implementam IRouteConstraint e inspecionam valores de rota
para verificá-los. Neste exemplo, o valor de rota id precisa ser conversível em um inteiro. Consulte route-
constraint-reference para obter uma explicação mais detalhada das restrições de rota que são fornecidas
pela estrutura.
Sobrecargas adicionais de MapRoute aceitam valores para constraints , dataTokens e defaults . Esses
parâmetros adicionais de MapRoute são definidos como o tipo object . O uso típico desses parâmetros é
passar um objeto de tipo anônimo, no qual os nomes da propriedade do tipo anônimo correspondem aos
nomes do parâmetro de rota.
Os dois seguintes exemplos criam rotas equivalentes:
routes.MapRoute(
name: "default_route",
template: "{controller}/{action}/{id?}",
defaults: new { controller = "Home", action = "Index" });
routes.MapRoute(
name: "default_route",
TIP
A sintaxe embutida para a definição de restrições e padrões pode ser interessante para rotas simples. No entanto, há
recursos, como tokens de dados, que não têm suporte na sintaxe embutida.
O exemplo a seguir demonstra mais alguns cenários:
routes.MapRoute(
name: "blog",
template: "Blog/{*article}",
defaults: new { controller = "Blog", action = "ReadArticle" });
Esse modelo corresponde a um caminho de URL, como /Blog/All-About-Routing/Introduction , e extrai os

valores { controller = Blog, action = ReadArticle, article = All-About-Routing/Introduction } . Os valores
de rota padrão para controller e action são produzidos pela rota, mesmo que não haja nenhum
parâmetro de rota correspondente no modelo. Os valores padrão podem ser especificados no modelo de
rota. O parâmetro de rota article é definido como um catch-all pela aparência de um asterisco * antes
do nome do parâmetro de rota. Os parâmetros de rota catch-all capturam o restante do caminho de URL e
também podem corresponder à cadeia de caracteres vazia.
Este exemplo adiciona restrições de rota e tokens de dados:
routes.MapRoute(
name: "us_english_products",
template: "en-US/Products/{id}",
defaults: new { controller = "Products", action = "Details" },
constraints: new { id = new IntRouteConstraint() },
dataTokens: new { locale = "en-US" });
Este modelo corresponde a um caminho de URL como /en-US/Products/5 e extrai os valores de

{ controller = Products, action = Details, id = 5 } e os tokens de dados { locale = en-US } .
Geração de URL
A classe Route também pode executar a geração de URL pela combinação de um conjunto de valores de
rota com seu modelo de rota. Logicamente, este é o processo inverso de correspondência do caminho de
URL.
TIP
Para entender melhor a geração de URL, imagine qual URL você deseja gerar e, em seguida, pense em como um
modelo de rota corresponderia a essa URL. Quais valores serão produzidos? Este é o equivalente aproximado de como
funciona a geração de URL na classe Route .
Este exemplo usa uma rota de estilo básica do ASP.NET Core MVC:
routes.MapRoute(
name: "default",
Com os valores de rota { controller = Products, action = List } , essa rota gera a URL /Products/List . Os
valores de rota são substituídos pelos parâmetros de rota correspondentes para formar o caminho de URL.
Como id é um parâmetro de rota opcional, não há problema algum se ele não tem um valor.
Com os valores de rota { controller = Home, action = Index } , essa rota gera a URL / . Os valores de rota
fornecidos correspondem aos valores padrão para que os segmentos correspondentes a esses valores
possam ser omitidos com segurança. As duas URLs geradas fazem uma viagem de ida e volta com essa
definição de rota e produzem os mesmos valores de rota que foram usados para gerar a URL.
TIP
Um aplicativo que usa o ASP.NET Core MVC deve usar UrlHelper para gerar URLs, em vez de chamar o roteamento
diretamente.
Para saber mais sobre a geração de URL, confira url-generation-reference.
Usar o middleware de roteamento

Referencie o metapacote Microsoft.AspNetCore.App no arquivo de projeto do aplicativo.
Referencie o metapacote Microsoft.AspNetCore.All no arquivo de projeto do aplicativo.
Referencie o Microsoft.AspNetCore.Routing no arquivo de projeto do aplicativo.
Adicione o roteamento ao contêiner de serviço em Startup.ConfigureServices :

{
services.AddRouting();
}

{
services.AddRouting();
}
As rotas precisam ser configuradas no método Startup.Configure . O aplicativo de exemplo usa estas APIs:
RouteBuilder
Build
MapGet – Corresponde apenas às solicitações HTTP GET.
UseRouter
var trackPackageRouteHandler = new RouteHandler(context =>
{
var routeValues = context.GetRouteData().Values;
return context.Response.WriteAsync(
$"Hello! Route values: {string.Join(", ", routeValues)}");
});
var routeBuilder = new RouteBuilder(app, trackPackageRouteHandler);
routeBuilder.MapRoute(
"Track Package Route",
"package/{operation:regex(^track|create|detonate$)}/{id:int}");
routeBuilder.MapGet("hello/{name}", context =>

{
var name = context.GetRouteValue("name");
// The route handler when HTTP GET "hello/<anything>" matches
// To match HTTP GET "hello/<anything>/<anything>,
// use routeBuilder.MapGet("hello/{*name}"
return context.Response.WriteAsync($"Hi, {name}!");
});
var routes = routeBuilder.Build();

app.UseRouter(routes);
var trackPackageRouteHandler = new RouteHandler(context =>

{
var routeValues = context.GetRouteData().Values;
return context.Response.WriteAsync(
$"Hello! Route values: {string.Join(", ", routeValues)}");
});
var routeBuilder = new RouteBuilder(app, trackPackageRouteHandler);
routeBuilder.MapRoute(
"Track Package Route",
"package/{operation:regex(^track|create|detonate$)}/{id:int}");
routeBuilder.MapGet("hello/{name}", context =>

{
var name = context.GetRouteValue("name");
// The route handler when HTTP GET "hello/<anything>" matches
// To match HTTP GET "hello/<anything>/<anything>,
// use routeBuilder.MapGet("hello/{*name}"
return context.Response.WriteAsync($"Hi, {name}!");
});
var routes = routeBuilder.Build();

app.UseRouter(routes);
A tabela a seguir mostra as respostas com os URIs fornecidos.
URI RESPOSTA
/package/create/3 Olá! Valores de rota: [operation, create], [id, 3]
/package/track/-3 Olá! Valores de rota: [operation, track], [id, -3]
/package/track/-3/ Olá! Valores de rota: [operation, track], [id, -3]
/package/track/ <Fall through, no match>

URI RESPOSTA
GET /hello/Joe Olá, Joe!
POST /hello/Joe <Fall through, matches HTTP GET only>
GET /hello/Joe/Smith <Fall through, no match>
Se você estiver configurando uma única rota, chame UseRouter passando uma instância de IRouter . Você
não precisa usar RouteBuilder.
O framework fornece um conjunto de métodos de extensão para a criação de rotas, como:
MapRoute
MapGet
MapPost
MapPut
MapDelete
MapVerb
Alguns desses métodos, como MapGet , exigem que um RequestDelegate seja fornecido. O RequestDelegate
é usado como o manipulador de rotas quando a rota corresponde. Outros métodos nesta família permitem
configurar um pipeline de middleware a ser usado como o manipulador de rotas. Se o método Map não
aceitar um manipulador, como MapRoute , ele usará o DefaultHandler.
Os métodos Map[Verb] usam restrições para limitar a rota ao Verbo HTTP no nome do método. Por
exemplo, veja MapGet e MapVerb.
Referência de modelo de rota

Os tokens entre chaves ( { ... } ) definem os parâmetros de rota que serão associados se a rota for
correspondida. Você pode definir mais de um parâmetro de rota em um segmento de rota, mas eles
precisam ser separados por um valor literal. Por exemplo, {controller=Home}{action=Index} não é uma rota
válida, já que não há nenhum valor literal entre {controller} e {action} . Esses parâmetros de rota
precisam ter um nome e podem ter atributos adicionais especificados.
Um texto literal diferente dos parâmetros de rota (por exemplo, {id} ) e do separador de caminho /
precisa corresponder ao texto na URL. A correspondência de texto não diferencia maiúsculas de minúsculas
e se baseia na representação decodificada do caminho de URLs. Para encontrar a correspondência do
delimitador de parâmetro de rota literal { ou } , faça seu escape repetindo o caractere ( {{ ou }} ).
Padrões de URL que tentam capturar um nome de arquivo com uma extensão de arquivo opcional
apresentam considerações adicionais. Por exemplo, considere o modelo files/{filename}.{ext?} . Quando
filename e ext existem, ambos os valores são populados. Se apenas filename existir na URL, a rota
encontrará a correspondência, pois o ponto à direita . é opcional. As URLs a seguir correspondem a essa
rota:
/files/myFile.txt
/files/myFile
Você pode usar o caractere * como um prefixo para um parâmetro de rota a ser associado ao restante do
URI. Isso é chamado de parâmetro catch-all. Por exemplo, blog/{*slug} corresponde a qualquer URI que
começa com /blog e tem qualquer valor depois dele (que é atribuído ao valor de rota slug ). Os
parâmetros catch-all também podem corresponder à cadeia de caracteres vazia.
O parâmetro catch-all faz o escape dos caracteres corretos quando a rota é usada para gerar uma URL,
incluindo os caracteres separadores de caminho ( / ). Por exemplo, a rota foo/{*path} com valores de rota
{ path = "my/path" } gera foo/my%2Fpath . Observe o escape da barra invertida. Para fazer a viagem de ida
e volta dos caracteres separadores de caminho, use o prefixo do parâmetro da rota ** . A rota foo/{**path}
com { path = "my/path" } gera foo/my/path .
Os parâmetros de rota podem ter valores padrão, designados pela especificação do padrão após o nome do
parâmetro, separados por um sinal de igual ( = ). Por exemplo, {controller=Home} define Home como o valor
padrão de controller . O valor padrão é usado se nenhum valor está presente na URL para o parâmetro.
Além dos valores padrão, os parâmetros de rota podem ser opcionais, especificados ao acrescentar um
ponto de interrogação ( ? ) ao final do nome do parâmetro, como em id? . A diferença entre os parâmetro
de rota de valores opcionais e os padrão é que um parâmetro de rota com um valor padrão sempre produz
um valor e um parâmetro opcional somente tem um valor quando ele é fornecido pela URL de solicitação.
Os parâmetros de rota podem ter restrições, que precisam corresponder ao valor de rota associado da URL.
A adição de dois-pontos ( : ) e do nome da restrição após o nome do parâmetro de rota especifica uma
restrição embutida em um parâmetro de rota. Se a restrição exigir argumentos, eles ficarão entre parênteses
( ) após o nome da restrição. Várias restrições embutidas podem ser especificadas por meio do acréscimo
de outros dois-pontos ( : ) e do nome da restrição. O nome da restrição e os argumentos são passados para
o serviço IInlineConstraintResolver para criar uma instância de IRouteConstraint a ser usada no
processamento de URL. Se o construtor de restrições exigir serviços, eles serão resolvidos nos serviços de
aplicativos da injeção da dependência. Por exemplo, o modelo de rota blog/{article:minlength(10)}
especifica uma restrição minlength com o argumento 10 . Para obter mais informações sobre as restrições
de rota e uma listagem das restrições fornecidas pela estrutura, confira a seção Referência de restrição de
rota.
Os parâmetros de rota podem ter restrições, que precisam corresponder ao valor de rota associado da URL.
A adição de dois-pontos ( : ) e do nome da restrição após o nome do parâmetro de rota especifica uma
restrição embutida em um parâmetro de rota. Se a restrição exigir argumentos, eles ficarão entre parênteses
( ) após o nome da restrição. Várias restrições embutidas podem ser especificadas por meio do acréscimo
de outros dois-pontos ( : ) e do nome da restrição. O nome da restrição e os argumentos são passados para
o serviço IInlineConstraintResolver para criar uma instância de IRouteConstraint a ser usada no
processamento de URL. Por exemplo, o modelo de rota blog/{article:minlength(10)} especifica uma
restrição minlength com o argumento 10 . Para obter mais informações sobre as restrições de rota e uma
listagem das restrições fornecidas pela estrutura, confira a seção Referência de restrição de rota.
Os parâmetros de rota também podem ter transformadores de parâmetro, que transformam o valor de um
parâmetro ao gerar links e combinar ações e páginas com URIs. Assim como as restrições, os
transformadores de parâmetro podem ser adicionados embutidos a um parâmetro de rota colocando dois-
pontos ( : ) e o nome do transformador após o nome do parâmetro de rota. Por exemplo, o modelo de rota
blog/{article:slugify} especifica um transformador slugify .
A tabela a seguir demonstra alguns modelos de rota e seu comportamento.
URL DE CORRESPONDÊNCIA DE
MODELO DE ROTA EXEMPLO OBSERVAÇÕES
hello /hello Somente corresponde ao caminho

único /hello
{Page=Home} / Faz a correspondência e define Page

como Home
URL DE CORRESPONDÊNCIA DE
MODELO DE ROTA EXEMPLO OBSERVAÇÕES
{Page=Home} /Contact Faz a correspondência e define Page

como Contact
{controller}/{action}/{id?} /Products/List É mapeado para o controlador

Products e a ação List
{controller}/{action}/{id?} /Products/Details/123 É mapeado para o controlador

Products e a ação Details . id
definido como 123
{controller=Home}/{action=Index}/{id / É mapeado para o controlador Home

?} e o método Index ; id é ignorado.
Em geral, o uso de um modelo é a abordagem mais simples para o roteamento. Restrições e padrões
também podem ser especificados fora do modelo de rota.
TIP
Habilite o Log para ver como as implementações de roteamento internas, como Route , correspondem às
solicitações.
Nomes reservados de roteamento

As seguintes palavras-chave são nomes reservados e não podem ser usadas como nomes de rota ou
parâmetros:
action
area
controller
handler
page
Referência de restrição de rota

As restrições da rota são executadas quando uma Route correspondeu à sintaxe da URL de entrada e criou
um token do caminho de URL para valores de rota. Em geral, as restrições da rota inspecionam o valor de
rota associado por meio do modelo de rota e tomam uma decisão do tipo "sim/não" sobre se o valor é
aceitável ou não. Algumas restrições da rota usam dados fora do valor de rota para considerar se a
solicitação pode ser encaminhada. Por exemplo, a HttpMethodRouteConstraint pode aceitar ou rejeitar uma
solicitação de acordo com o verbo HTTP.
WARNING
Evite usar restrições para validação de entrada porque isso significa que uma entrada inválida resultará em um 404
– Não Encontrado e não em um 400 – Solicitação Inválida com uma mensagem de erro apropriada. As restrições de
rota são usadas para desfazer a ambiguidade entre rotas semelhantes, não para validar as entradas de uma rota
específica.
A tabela a seguir demonstra algumas restrições de rota e seu comportamento esperado.

CORRESPONDÊNCIAS DE
RESTRIÇÃO EXEMPLO EXEMPLO OBSERVAÇÕES
int {id:int} 123456789 , -123456789 Corresponde a qualquer

inteiro
bool {active:bool} true , FALSE Corresponde a true ou

false (não diferencia
maiúsculas de minúsculas)
datetime {dob:datetime} 2016-12-31 , Corresponde a um valor

2016-12-31 7:32pm DateTime válido (na
cultura invariável – veja o
aviso)
decimal {price:decimal} 49.99 , -1,000.01 Corresponde a um valor

decimal válido (na
cultura invariável – veja o
aviso)
double {weight:double} 1.234 , -1,001.01e8 Corresponde a um valor

double válido (na cultura
invariável – veja o aviso)
float {weight:float} 1.234 , -1,001.01e8 Corresponde a um valor

float válido (na cultura
invariável – veja o aviso)
guid {id:guid} CD2C1638-1638-72D5- Corresponde a um valor

1638-DEADBEEF1638 Guid válido
,
{CD2C1638-1638-72D5-
1638-DEADBEEF1638}
long {ticks:long} 123456789 , -123456789 Corresponde a um valor

long válido
minlength(value) {username:minlength(4)} Rick A cadeia de caracteres

deve ter, no mínimo, 4
caracteres
maxlength(value) {filename:maxlength(8)} Richard A cadeia de caracteres não

pode ser maior que 8
caracteres
length(length) {filename:length(12)} somefile.txt A cadeia de caracteres

deve ter exatamente 12
caracteres
length(min,max) {filename:length(8,16)} somefile.txt A cadeia de caracteres

deve ter, pelo menos, 8 e
não mais de 16 caracteres
min(value) {age:min(18)} 19 O valor inteiro deve ser,

pelo menos, 18
CORRESPONDÊNCIAS DE
RESTRIÇÃO EXEMPLO EXEMPLO OBSERVAÇÕES
max(value) {age:max(120)} 91 O valor inteiro não deve

ser maior que 120
range(min,max) {age:range(18,120)} 91 O valor inteiro deve ser,

pelo menos, 18, mas não
maior que 120
alpha {name:alpha} Rick A cadeia de caracteres

deve consistir em um ou
mais caracteres alfabéticos
( a - z , não diferencia
maiúsculas de minúsculas)
regex(expression) {ssn:regex(^\\d{{3}}- 123-45-6789 A cadeia de caracteres

\\d{{2}}-\\d{{4}}$)} deve corresponder à
expressão regular (veja as
dicas sobre como definir
uma expressão regular)
required {name:required} Rick Usado para impor que um

valor não parâmetro está
presente durante a
geração de URL
Várias restrições delimitadas por vírgula podem ser aplicadas a um único parâmetro. Por exemplo, a
restrição a seguir restringe um parâmetro para um valor inteiro de 1 ou maior:
[Route("users/{id:int:min(1)}")]
public User GetUserById(int id) { }
WARNING
As restrições de rota que verificam a URL e são convertidas em um tipo CLR (como int ou DateTime ) sempre
usam a cultura invariável. Essas restrições consideram que a URL não é localizável. As restrições de rota fornecidas pela
estrutura não modificam os valores armazenados nos valores de rota. Todos os valores de rota analisados com base
na URL são armazenados como cadeias de caracteres. Por exemplo, a restrição float tenta converter o valor de rota
em um float, mas o valor convertido é usado somente para verificar se ele pode ser convertido em um float.
Expressões regulares
A estrutura do ASP.NET Core adiciona
RegexOptions.IgnoreCase | RegexOptions.Compiled | RegexOptions.CultureInvariant ao construtor de
expressão regular. Confira RegexOptions para obter uma descrição desses membros.
As expressões regulares usam delimitadores e tokens semelhantes aos usados pelo Roteamento e pela
linguagem C#. Os tokens de expressão regular precisam ter escape. Para usar a expressão regular
^\d{3}-\d{2}-\d{4}$ no Roteamento, ela precisa ter os caracteres \ digitados como \\ no arquivo de
origem C# para fazer o escape do caractere de escape da cadeia de caracteres \ (a menos que literais de
cadeia de caracteres textuais sejam usados). Os caracteres { , } , [ e ] precisam ser inseridos duas vezes
para fazer o escape dos caracteres delimitadores do parâmetro de Roteamento. A tabela abaixo mostra uma
expressão regular e a versão com escape.
EXPRESSÃO COM ESCAPE
^\d{3}-\d{2}-\d{4}$ ^\\d{{3}}-\\d{{2}}-\\d{{4}}$
^[a-z]{2}$ ^[[a-z]]{{2}}$
As expressões regulares usadas no roteamento geralmente começam com o caractere ^ (corresponde à

posição inicial da cadeia de caracteres) e terminam com o caractere $ (corresponde à posição final da
cadeia de caracteres). Os caracteres ^ e $ garantem que a expressão regular corresponde a todo o valor
do parâmetro de rota. Sem os caracteres ^ e $ , a expressão regular corresponde a qualquer subcadeia de
caracteres na cadeia de caracteres, o que geralmente não é o desejado. A tabela abaixo mostra alguns
exemplos e explica por que eles encontram ou não uma correspondência.
EXPRESSÃO CADEIA DE CARACTERES CORRESPONDER A COMENTÁRIO
[a-z]{2} hello Sim A subcadeia de caracteres

corresponde
[a-z]{2} 123abc456 Sim A subcadeia de caracteres

corresponde
[a-z]{2} mz Sim Corresponde à expressão
[a-z]{2} MZ Sim Não diferencia maiúsculas

de minúsculas
^[a-z]{2}$ hello Não Confira ^ e $ acima
^[a-z]{2}$ 123abc456 Não Confira ^ e $ acima
Para saber mais sobre a sintaxe de expressões regulares, confira Expressões regulares do .NET Framework.
Para restringir um parâmetro a um conjunto conhecido de valores possíveis, use uma expressão regular. Por
exemplo, {action:regex(^(list|get|create)$)} apenas corresponde o valor da rota action a list , get ou
create . Se passada para o dicionário de restrições, a cadeia de caracteres ^(list|get|create)$ é
equivalente. As restrições passadas para o dicionário de restrições (não embutidas em um modelo) que não
correspondem a uma das restrições conhecidas também são tratadas como expressões regulares.
Referência de parâmetro de transformador

Transformadores de parâmetro:
Executar ao gerar um link para um Route .
Implementar Microsoft.AspNetCore.Routing.IOutboundParameterTransformer .
São configurados usando ConstraintMap.
Usam o valor de rota do parâmetro e o transformam em um novo valor de cadeia de caracteres.
O valor transformado é usado no link gerado.
Por exemplo, um transformador de parâmetro slugify personalizado em padrão de rota
blog\{article:slugify} com Url.Action(new { article = "MyTestArticle" }) gera blog\my-test-article .
Os transformadores de parâmetro também são usados pelas estruturas para transformar o URI em que o
ponto de extremidade é resolvido. Por exemplo, o ASP.NET Core MVC usa os transformadores de
parâmetro para transformar o valor de rota usado para corresponder a um area , controller , action e
page .
routes.MapRoute(
name: "default",
template: "{controller=Home:slugify}/{action=Index:slugify}/{id?}");
Com a rota anterior, a ação é combinada com o URI

SubscriptionManagementController.GetAll()
/subscription-management/get-all . Um transformador de parâmetro não altera os valores de rota usados
para gerar um link. Url.Action("GetAll", "SubscriptionManagement") gera /subscription-management/get-all .
ASP.NET Core fornece convenções de API para usar transformadores de parâmetro com as rotas geradas:
ASP.NET Core MVC tem a convenção de API
Microsoft.AspNetCore.Mvc.ApplicationModels.RouteTokenTransformerConvention . Essa convenção aplica um
transformador de parâmetro especificado a todas as rotas de atributo no aplicativo. O transformador de
parâmetro transforma os tokens de rota do atributo conforme elas são substituídas. Para obter mais
informações, confira Usar um transformador de parâmetro para personalizar a substituição de token.
Razor Pages têm a convenção de API
Microsoft.AspNetCore.Mvc.ApplicationModels.PageRouteTransformerConvention . Essa convenção aplica-se
um transformador de parâmetro especificado para todas as Razor Pages descobertas automaticamente.
O transformador de parâmetro transforma a pasta e segmentos de nome de arquivo de rotas de página
do Razor. Para obter mais informações, confira Usar um transformador de parâmetros para personalizar
rotas de página.
Referência de geração de URL

O exemplo a seguir mostra como gerar um link para uma rota com base em um dicionário de valores de
rota e em um RouteCollection.
app.Run(async (context) =>

{
var dictionary = new RouteValueDictionary
{
{ "operation", "create" },
{ "id", 123}
};
var vpc = new VirtualPathContext(context, null, dictionary,

"Track Package Route");
var path = routes.GetVirtualPath(vpc).VirtualPath;
context.Response.ContentType = "text/html";
await context.Response.WriteAsync("Menu<hr/>");
await context.Response.WriteAsync(
$"<a href='{path}'>Create Package 123</a><br/>");
});
{
var dictionary = new RouteValueDictionary
{
{ "operation", "create" },
{ "id", 123}
};
var vpc = new VirtualPathContext(context, null, dictionary,

"Track Package Route");
var path = routes.GetVirtualPath(vpc).VirtualPath;
await context.Response.WriteAsync("Menu<hr/>");
$"<a href='{path}'>Create Package 123</a><br/>");
});
O VirtualPath gerado no final do exemplo anterior é /package/create/123 . O dicionário fornece os valores

de rota operation e id do modelo "Rastrear rota do pacote", package/{operation}/{id} . Para obter
detalhes, consulte o código de exemplo na seção Usar o middleware de roteamento ou no aplicativo de
exemplo.
O segundo parâmetro para o construtor VirtualPathContext é uma coleção de valores de ambiente. Os
valores de ambiente proporcionam conveniência, limitando o número de valores que um desenvolvedor
precisa especificar em determinado contexto de solicitação. Os valores de rota atuais da solicitação atual são
considerados valores de ambiente para a geração de link. Em um aplicativo ASP.NET Core MVC, se você
está na ação About do HomeController , não é necessário especificar o valor de rota do controlador a ser
vinculado à ação Index . O valor de ambiente Home é usado.
Os valores de ambiente que não correspondem a um parâmetro são ignorados e os valores de ambiente
também são ignorados quando um valor fornecido de forma explícita o substitui, seguindo da esquerda para
a direita na URL.
Os valores que são fornecidos de forma explícita, mas que não correspondem a nada, são adicionados à
cadeia de caracteres de consulta. A tabela a seguir mostra o resultado do uso do modelo de rota
{controller}/{action}/{id?} .
VALORES DE AMBIENTE VALORES EXPLÍCITOS RESULTADO
controller="Home" action="About" /Home/About
controller="Home" controller="Order",action="About" /Order/About
controller="Home",color="Red" action="About" /Home/About
controller="Home" action="About",color="Red" /Home/About?color=Red
Se uma rota tem um valor padrão que não corresponde a um parâmetro e esse valor é fornecido de forma
explícita, ele precisa corresponder ao valor padrão:
routes.MapRoute("blog_route", "blog/{*slug}",
defaults: new { controller = "Blog", action = "ReadPost" });
A geração de link somente gera um link para essa rota quando os valores correspondentes do controlador e
da ação são fornecidos.
Por Rick Anderson

O ASP.NET Core configura o comportamento do aplicativo com base no ambiente de tempo de execução
usando uma variável de ambiente.
Ambientes
O ASP.NET Core lê a variável de ambiente ASPNETCORE_ENVIRONMENT na inicialização do aplicativo e armazena
o valor em IHostingEnvironment.EnvironmentName. Você pode definir ASPNETCORE_ENVIRONMENT como
qualquer valor, mas há suporte para três valores na estrutura: Desenvolvimento, Preparo e Produção. Se
ASPNETCORE_ENVIRONMENT não estiver definido, o padrão será Production .

{
{
}
if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Staging_2"))

{
app.UseHsts();
}
app.UseMvc();
}
O código anterior:
Chama UseDeveloperExceptionPage quando ASPNETCORE_ENVIRONMENT é definido como Development .
Chama UseExceptionHandler quando o valor de ASPNETCORE_ENVIRONMENT é definido com um dos
seguintes:
Staging
Production
Staging_2
O Auxiliar de Marcação de Ambiente usa o valor de IHostingEnvironment.EnvironmentName para incluir ou

excluir a marcação no elemento:
@page
@inject Microsoft.AspNetCore.Hosting.IHostingEnvironment hostingEnv
@model AboutModel
@{
}
<p> ASPNETCORE_ENVIRONMENT = @hostingEnv.EnvironmentName</p>
No Windows e no macOS, valores e variáveis de ambiente não diferenciam maiúsculas de minúsculas.

Valores e variáveis de ambiente do Linux diferenciam maiúsculas de minúsculas por padrão.
Desenvolvimento
O ambiente de desenvolvimento pode habilitar recursos que não devem ser expostos em produção. Por
exemplo, os modelos do ASP.NET Core habilitam a página de exceção do desenvolvedor no ambiente de
desenvolvimento.
O ambiente de desenvolvimento do computador local pode ser definido no arquivo
Properties\launchSettings.json do projeto. Os valores de ambiente definidos em launchSettings.json
substituem os valores definidos no ambiente do sistema.
O seguinte JSON mostra três perfis de um arquivo launchSettings.json:
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "http://localhost:54339/",
"sslPort": 0
}
},
"profiles": {
"IIS Express": {
"commandName": "IISExpress",
"launchBrowser": true,
"environmentVariables": {
"ASPNETCORE_My_Environment": "1",
"ASPNETCORE_DETAILEDERRORS": "1",
"ASPNETCORE_ENVIRONMENT": "Staging"
}
},
"EnvironmentsSample": {
"commandName": "Project",
},
"applicationUrl": "http://localhost:54340/"
},
"Kestrel Staging": {
"ASPNETCORE_My_Environment": "1",
"ASPNETCORE_DETAILEDERRORS": "1",
},
}
}
}
NOTE
A propriedade applicationUrl no launchSettings.json pode especificar uma lista de URLs de servidores. Use um
ponto e vírgula entre as URLs na lista:
"EnvironmentsSample": {
"applicationUrl": "https://localhost:5001;http://localhost:5000",
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
Quando o aplicativo é inicializado com dotnet run, o primeiro perfil com "commandName": "Project" é usado. O
valor de commandName especifica o servidor Web a ser iniciado. commandName pode ser qualquer um dos
seguintes:
IIS Express
IIS
Projeto (que inicia o Kestrel)
Quando um aplicativo for iniciado com dotnet run:
launchSettings.json é lido, se está disponível. As configurações de environmentVariables em
launchSettings.json substituem as variáveis de ambiente.
O ambiente de hospedagem é exibido.
A saída a seguir mostra um aplicativo iniciado com dotnet run:
PS C:\Websites\EnvironmentsSample> dotnet run

Using launch settings from C:\Websites\EnvironmentsSample\Properties\launchSettings.json...
Hosting environment: Staging
Content root path: C:\Websites\EnvironmentsSample
Now listening on: http://localhost:54340
Application started. Press Ctrl+C to shut down.
A guia Depurar das propriedades do projeto do Visual Studio fornece uma GUI para editar o arquivo
launchSettings.json:
As alterações feitas nos perfis do projeto poderão não ter efeito até que o servidor Web seja reiniciado. O
Kestrel precisa ser reiniciado antes de detectar as alterações feitas ao seu ambiente.
WARNING
launchSettings.json não deve armazenar segredos. A ferramenta Secret Manager pode ser usado para armazenar
segredos de desenvolvimento local.
Ao usar Visual Studio Code, variáveis de ambiente podem ser definidas no arquivo .vscode/launch.json. O
exemplo a seguir define o ambiente como Development :
{
"version": "0.2.0",
"configurations": [
{
"name": ".NET Core Launch (web)",
... additional VS Code configuration settings ...
"env": {
}
}
]
}
Um arquivo .vscode/launch.json do projeto não é lido ao iniciar o aplicativo com dotnet run da mesma
maneira que Properties/launchSettings.json. Ao inicializar um aplicativo em desenvolvimento que não tem um
arquivo launchSettings.json, defina o ambiente com uma variável de ambiente ou um argumento de linha de
comando para o comando dotnet run .
Produção
O ambiente de produção deve ser configurado para maximizar a segurança, o desempenho e a robustez do
aplicativo. Algumas configurações comuns que são diferentes do desenvolvimento incluem:
Cache.
Recursos do lado do cliente são agrupados, minimizados e potencialmente atendidos por meio de uma
CDN.
Páginas de erro de diagnóstico desabilitadas.
Páginas de erro amigáveis habilitadas.
Log de produção e monitoramento habilitados. Por exemplo, Application Insights.
Definir o ambiente
Geralmente, é útil definir um ambiente específico para teste. Se o ambiente não for definido, ele usará
Production como padrão, o que desabilitará a maioria dos recursos de depuração. O método para configurar
o ambiente depende do sistema operacional.
Serviço de Aplicativo do Azure
Para definir o ambiente no Serviço de Aplicativo do Azure, execute as seguintes etapas:
1. Selecione o aplicativo na folha Serviços de Aplicativos.
2. No grupo CONFIGURAÇÕES, selecione a folha Configurações do aplicativo.
3. Na área Configurações do aplicativo, selecione Adicionar nova configuração.
4. Para Inserir um nome, forneça ASPNETCORE_ENVIRONMENT . Para Inserir um valor, fornecer o ambiente (por
exemplo, Staging ).
5. Marque a caixa de seleção Configuração do Slot se desejar que a configuração do ambiente permaneça
no slot atual quando os slots de implantação forem trocados. Para obter mais informações, veja
Documentação do Azure: que configurações são trocadas?.
6. Selecione Salvar na parte superior da folha.
O Serviço de Aplicativo do Azure reinicia automaticamente o aplicativo após uma configuração de aplicativo
(variável de ambiente) ser adicionada, alterada ou excluída no portal do Azure.
Windows
Para definir o ASPNETCORE_ENVIRONMENT para a sessão atual quando o aplicativo for iniciado usando dotnet run,
os comandos a seguir serão usados:
Prompt de comando
set ASPNETCORE_ENVIRONMENT=Development
PowerShell
$Env:ASPNETCORE_ENVIRONMENT = "Development"
Esses comandos somente têm efeito para a janela atual. Quando a janela é fechada, a configuração
ASPNETCORE_ENVIRONMENT é revertida para a configuração padrão ou o valor de computador.
Para definir o valor globalmente no Windows, use uma das seguintes abordagens:
Abra o Painel de Controle > Sistema > Configurações avançadas do sistema e adicione ou edite
o valor ASPNETCORE_ENVIRONMENT :
Abra um prompt de comando administrativo e use o comando setx ou abra um prompt de comando
administrativo do PowerShell e use [Environment]::SetEnvironmentVariable :
Prompt de comando
setx ASPNETCORE_ENVIRONMENT Development /M
O comutador /M indica para definir a variável de ambiente no nível do sistema. Se o comutador /M

não for usado, a variável de ambiente será definida para a conta de usuário.
PowerShell
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "Machine")
O valor da opção Machine indica para definir a variável de ambiente no nível do sistema. Se o valor da
opção for alterado para User , a variável de ambiente será definida para a conta de usuário.
Quando a variável de ambiente ASPNETCORE_ENVIRONMENT é definida globalmente, ela entra em vigor para
dotnet run em qualquer janela de comando aberta depois que o valor é definido.
web.config
Para definir a variável de ambiente ASPNETCORE_ENVIRONMENT com web.config, consulte a seção Definindo
variáveis de ambiente de Referência de configuração do Módulo do ASP.NET Core. Quando a variável de
ambiente ASPNETCORE_ENVIRONMENT é definida com web.config, seu valor substitui uma configuração no nível
do sistema.
Por pool de aplicativos do IIS
Para definir a variável de ambiente ASPNETCORE_ENVIRONMENT para um aplicativo em execução em um Pool de
aplicativos isolado (compatível com IIS 10.0 ou posterior), consulte a seção Comando AppCmd.exe do tópico
Variáveis de ambiente <environmentVariables>. Quando a variável de ambiente ASPNETCORE_ENVIRONMENT é
definida para um pool de aplicativos, seu valor substitui uma configuração no nível do sistema.
IMPORTANT
Ao hospedar um aplicativo no IIS e adicionar ou alterar a variável de ambiente ASPNETCORE_ENVIRONMENT , use qualquer
uma das abordagens a seguir para que o novo valor seja escolhido por aplicativos:
Execute net stop was /y seguido por net start w3svc em um prompt de comando.
Reinicie o servidor.
macOS
A configuração do ambiente atual para macOS pode ser feita em linha ao executar o aplicativo:
ASPNETCORE_ENVIRONMENT=Development dotnet run
Como alternativa, defina o ambiente com export antes de executar o aplicativo:
export ASPNETCORE_ENVIRONMENT=Development
As variáveis de ambiente no nível do computador são definidas no arquivo .bashrc ou .bash_profile. Edite o
arquivo usando qualquer editor de texto. Adicione a seguinte instrução:
export ASPNETCORE_ENVIRONMENT=Development
Linux
Para distribuições Linux, use o comando export no prompt de comando para as configurações de variável
baseadas na sessão e o arquivo bash_profile para as configurações de ambiente no nível do computador.
Configuração por ambiente
Para carregar a configuração por ambiente, recomendamos:
Arquivos appsettings (*appsettings.<>.json). Confira Configuração: provedor de configuração de arquivo.
Variáveis de ambiente (definidas em cada sistema em que o aplicativo está hospedado). Confira
Configuração: provedor de configuração do arquivo e Armazenamento seguro de segredos do aplicativo
em desenvolvimento: variáveis de ambiente.
Gerenciador de Segredo (somente no ambiente de desenvolvimento). Consulte Armazenamento seguro
dos segredos do aplicativo em desenvolvimento no ASP.NET Core.
Métodos e classe Startup baseados no ambiente

Convenções da classe Startup
Quando um aplicativo ASP.NET Core é iniciado, a classe Startup inicia o aplicativo. O aplicativo pode definir
classes Startup separadas para ambientes diferentes (por exemplo, StartupDevelopment ), e a classe Startup
adequada é selecionada em tempo de execução. A classe cujo sufixo do nome corresponde ao ambiente atual
é priorizada. Se uma classe Startup{EnvironmentName} correspondente não for encontrada, a classe Startup
será usada.
Para implementar classes Startup com base em ambiente, crie uma classe Startup{EnvironmentName} para
cada ambiente no uso e classe Startup de fallback:
// Startup class to use in the Development environment

public class StartupDevelopment
{
{
...
}

{
...
}
}
// Startup class to use in the Production environment

public class StartupProduction
{
{
...
}

{
...
}
}
// Fallback Startup class

// Selected if the environment doesn't match a Startup{EnvironmentName} class
{
{
...
}

{
...
}
}
Use a sobrecarga UseStartup (IWebHostBuilder, String) que aceita um nome de assembly:

{
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args)

{
var assemblyName = typeof(Startup).GetTypeInfo().Assembly.FullName;
return WebHost.CreateDefaultBuilder(args)
.UseStartup(assemblyName);
}

{
CreateWebHost(args).Run();
}
public static IWebHost CreateWebHost(string[] args)

{
.UseStartup(assemblyName)
.Build();
}

{
{

.UseStartup(assemblyName)
.Build();
host.Run();
}
}
Convenções do método Startup

Configure e ConfigureServices são compatíveis com versões específicas do ambiente dos formatos
Configure<EnvironmentName> e Configure<EnvironmentName>Services :
{
{
}

{
StartupConfigureServices(services);
}
public void ConfigureStagingServices(IServiceCollection services)

{
StartupConfigureServices(services);
}
private void StartupConfigureServices(IServiceCollection services)

{
{
});
services.AddMvc()
}

{
{
}
if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Staging_2"))

{
app.UseHsts();
}
app.UseMvc();
}
public void ConfigureStaging(IApplicationBuilder app, IHostingEnvironment env)

{
if (!env.IsStaging())
{
throw new Exception("Not staging.");
}
app.UseHsts();
app.UseMvc();
}
}
Recursos adicionais
IHostingEnvironment.EnvironmentName
Por Luke Latham

A configuração de aplicativos no ASP.NET Core se baseia em pares chave-valor estabelecidos por
provedores de configuração. Os provedores de configuração leem os dados de configuração em pares
chave-valor de várias fontes de configuração:
Azure Key Vault
Argumentos de linha de comando
Provedores personalizados (instalados ou criados)
Arquivos de diretório
Variáveis de ambiente
Objetos do .NET na memória
Arquivos de configurações
Azure Key Vault
O padrão de opções é uma extensão dos conceitos de configuração descritos neste tópico. As opções
usam classes para representar grupos de configurações relacionadas. Para saber mais sobre como usar
o padrão de opções, confira Padrão de opções no ASP.NET Core.
Os exemplos apresentados neste tópico dependem do seguinte:
Definição do caminho de base do aplicativo com SetBasePath. SetBasePath é disponibilizado para
um aplicativo fazendo referência ao pacote Microsoft.Extensions.Configuration.FileExtensions.
Resolução de seções dos arquivos de configuração com GetSection. GetSection é disponibilizado a
um aplicativo fazendo referência ao pacote Microsoft.Extensions.Configuration.
Configuração de associação a classes .NET com Bind e Get<T>. Bind e Get<T> são
disponibilizados a um aplicativo fazendo referência ao pacote
Microsoft.Extensions.Configuration.Binder. Get<T> está disponível no ASP.NET Core 1.1 ou
posterior.
Esses três pacotes estão incluídos no metapacote Microsoft.AspNetCore.App.
Esses três pacotes estão incluídos no metapacote Microsoft.AspNetCore.All.
Configuração do host versus aplicativo
Antes do aplicativo ser configurado e iniciado, um host é configurado e iniciado. O host é responsável
pelo gerenciamento de tempo de vida e pela inicialização do aplicativo. O aplicativo e o host são
configurados usando os provedores de configuração descritos neste tópico. Os pares chave-valor de
configuração do host se tornam parte da configuração global do aplicativo. Para saber mais sobre
como os provedores de configuração são usados quando o host for compilado, e como as fontes de
configuração afetam o host e a configuração, confira Host no ASP.NET Core.
Segurança
Adote as melhores práticas a seguir:
Nunca armazene senhas ou outros dados confidenciais no código do provedor de configuração ou
nos arquivos de configuração de texto sem formatação.
Não use segredos de produção em ambientes de teste ou de desenvolvimento.
Especifique segredos fora do projeto para que eles não sejam acidentalmente comprometidos com
um repositório de código-fonte.
Saiba mais sobre como usar vários ambientes e gerenciar o armazenamento seguro de segredos de
aplicativo em desenvolvimento com o Gerenciador de Segredo (inclui recomendações sobre como usar
variáveis de ambiente para armazenar dados confidenciais). O Gerenciador de Segredo usa o Provedor
de Configuração de Arquivo para armazenar segredos do usuário em um arquivo JSON no sistema
local. O Provedor de Configuração de Arquivo será descrito mais adiante neste tópico.
O Azure Key Vault é uma opção para o armazenamento seguro de segredos do aplicativo. Para obter
mais informações, consulte Provedor de configuração de Cofre de chaves do Azure no ASP.NET Core.
Dados de configuração hierárquica

A API de Configuração é capaz de manter dados de configuração hierárquica nivelando os dados
hierárquicos com o uso de um delimitador nas chaves de configuração.
No seguinte arquivo JSON, há quatro chaves em uma hierarquia estruturada com duas seções:
{
"section0": {
"key0": "value",
"key1": "value"
},
"section1": {
"key0": "value",
"key1": "value"
}
}
Quando o arquivo é lido na configuração, ocorre a criação de chaves exclusivas para manter a estrutura
hierárquica de dados original da fonte de configuração. As seções e as chaves são niveladas usando
dois-pontos ( : ) para manter a estrutura original:
section0:key0
section0:key1
section1:key0
section1:key1
Os métodos GetSection e GetChildren estão disponíveis para isolar as seções e os filhos de uma seção
nos dados de configuração. Esses métodos serão descritos posteriormente em GetSection, GetChildren
e Exists.
Convenções
Na inicialização do aplicativo, as fontes de configuração são lidas na ordem especificada pelos
provedores de configuração.
Os Provedores de Configuração de Arquivo têm a capacidade de recarregar a configuração quando um
arquivo de configurações subjacente é alterado após a inicialização do aplicativo. O Provedor de
Configuração de Arquivo será descrito mais adiante neste tópico.
IConfiguration está disponível no contêiner DI (injeção de dependência) do aplicativo. Os provedores
de configuração não podem utilizar a DI, pois ela não é disponibilizada quando eles são configurados
pelo host.
As chaves de configuração adotam as convenções a seguir:
As chaves não diferenciam maiúsculas de minúsculas. Por exemplo, ConnectionString e
connectionstring são tratados como chaves equivalentes.
Se um valor para a mesma chave for definido pelos mesmos provedores de configuração, ou por
outros, o último valor definido na chave será o valor usado.
Chaves hierárquicas
Ao interagir com a API de configuração, um separador de dois-pontos ( : ) funciona em
todas as plataformas.
Nas variáveis de ambiente, talvez um separador de dois-pontos não funcione em todas as
plataformas. Um sublinhado duplo ( __ ) é compatível com todas as plataformas e é
convertido em dois-pontos.
No Azure Key Vault, as chaves hierárquicas usam -- (dois traços) como separador. Você
deve fornecer o código para substituir os traços por dois-pontos quando os segredos forem
carregados na configuração do aplicativo.
O ConfigurationBinder dá suporte a matrizes de associação para objetos usando os índices em
chaves de configuração. A associação de matriz está descrita na seção Associar uma matriz a uma
classe.
Os valores de configuração adotam as convenções a seguir:
Os valores são cadeias de caracteres.
Não é possível armazenar valores nulos na configuração ou associá-los a objetos.
Provedores
A tabela a seguir mostra os provedores de configuração disponíveis para aplicativos ASP.NET Core.
PROVIDER FORNECE A CONFIGURAÇÃO DE …
Provedor de Configuração do Azure Key Vault (tópicos Azure Key Vault

de Segurança)
Provedor de Configuração de Linha de Comando Parâmetros de linha de comando
Provedor de Configuração personalizado Fonte personalizada
Provedor de Configuração de Variáveis de Ambiente Variáveis de ambiente

Provedor de Configuração de Arquivo Arquivos (INI, JSON, XML)
Provedor de Configuração de Chave por Arquivo Arquivos de diretório
Provedor de Configuração de Memória Coleções na memória
Segredos do usuário (Gerenciador de Segredo) (tópicos Arquivo no diretório de perfil do usuário

de Segurança)
Provedor de Configuração do Azure Key Vault (tópicos Azure Key Vault

de Segurança)

de Segurança)

de Segurança)
Na inicialização, as fontes de configuração são lidas na ordem especificada pelos provedores de

configuração. Os provedores de configuração descritos neste tópico estão descritos em ordem
alfabética, não na ordem na qual seu código pode organizá-los. Organize os provedores de
configuração em seu código para atender às suas prioridades para as fontes de configuração
subjacentes.
Uma sequência comum de provedores de configuração é:
1. Arquivos (appsettings.json, appsettings.{Environment}.json, em que {Environment} é o ambiente de
hospedagem atual do aplicativo)
2. Azure Key Vault
3. Segredos do usuário (Gerenciador de Segredo) (apenas no ambiente de desenvolvimento)
4. Variáveis de ambiente
5. Argumentos de linha de comando
É comum posicionar o Provedor de Configuração de Linha de Comando por último em uma série de
provedores, a fim de permitir que os argumentos de linha de comando substituam a configuração
definida por outros provedores.
Essa sequência de provedores é aplicada quando você inicializa um novo WebHostBuilder com
CreateDefaultBuilder. Para saber mais, veja o tópico Host da Web: configurar um host.
Essa sequência de provedores pode ser criada para o aplicativo (não o host) com um
ConfigurationBuilder e uma chamada para seu método Build em Startup :
public Startup(IHostingEnvironment env)

{
var builder = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true,
reloadOnChange: true);
var appAssembly = Assembly.Load(new AssemblyName(env.ApplicationName));
if (appAssembly != null)
{
builder.AddUserSecrets(appAssembly, optional: true);
}
builder.AddEnvironmentVariables();
Configuration = builder.Build();
}

{
services.AddSingleton<IConfiguration>(Configuration);
}
No exemplo anterior, o nome do ambiente ( env.EnvironmentName ) e o nome do assembly de aplicativo (

env.ApplicationName ) são fornecidos pelo IHostingEnvironment. Para obter mais informações, consulte
Usar vários ambientes no ASP.NET Core.
ConfigureAppConfiguration
Chame ConfigureAppConfiguration ao criar o Host da Web para especificar os provedores de
configuração do aplicativo, além daqueles adicionados automaticamente por CreateDefaultBuilder:
{
public static Dictionary<string, string> arrayDict = new Dictionary<string, string>
{
{"array:entries:0", "value0"},
{"array:entries:5", "value5"}
};

{
}

{
config.SetBasePath(Directory.GetCurrentDirectory());
config.AddInMemoryCollection(arrayDict);
config.AddJsonFile("json_array.json", optional: false, reloadOnChange: false);
config.AddJsonFile("starship.json", optional: false, reloadOnChange: false);
config.AddXmlFile("tvshow.xml", optional: false, reloadOnChange: false);
config.AddEFConfiguration(options => options.UseInMemoryDatabase("InMemoryDb"));
config.AddCommandLine(args);
})
}
Provedor de Configuração de Linha de Comando

O CommandLineConfigurationProvider carrega a configuração dos pares chave-valor do argumento
de linha de comando em tempo de execução.
Para ativar a configuração de linha de comando, o método de extensão AddCommandLine é chamado
em uma instância do ConfigurationBuilder.
AddCommandLine é chamado automaticamente quando você inicializa um novo WebHostBuilder com
CreateDefaultBuilder. Para saber mais, veja o tópico Host da Web: configurar um host.
CreateDefaultBuilder também carrega:
Configuração opcional de appsettings.json e appsettings.{Environment}.json.
Segredos do usuário (Gerenciador de Segredo) (no ambiente de desenvolvimento).
Variáveis de ambiente.
CreateDefaultBuilder adiciona o Provedor de Configuração de Linha de Comando por último. Os
argumentos de linha de comando passados em tempo de execução substituem a configuração definida
por outros provedores.
CreateDefaultBuilder age quando o host é construído. Portanto, a configuração de linha de comando
ativada por pode afetar como o host é configurado.
CreateDefaultBuilder
Chame ConfigureAppConfiguration ao criar o host para especificar a configuração do aplicativo.

AddCommandLine já foi chamado por CreateDefaultBuilder . Se precisar oferecer configuração de
aplicativo e ainda poder substituir essa configuração por argumentos de linha de comando, chame os
provedores adicionais do aplicativo em ConfigureAppConfiguration e chame AddCommandLine por fim.
{
{
}

{
// Call other providers here and call AddCommandLine last.
})
}
Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:

Aplique a configuração ao WebHostBuilder com o método UseConfiguration.
AddCommandLine já foi chamado por CreateDefaultBuilder quando UseConfiguration é chamado. Se
precisar oferecer configuração de aplicativo e ainda poder substituir essa configuração por argumentos
de linha de comando, chame os provedores adicionais do aplicativo em um ConfigurationBuilder e
chame AddCommandLine por fim.

{
{
}

{
var config = new ConfigurationBuilder()
// Call other providers here and call AddCommandLine last.
.AddCommandLine(args)
.Build();
.UseConfiguration(config)
}
}

Para ativar a configuração de linha de comando, chame o método de extensão AddCommandLine em
uma instância do ConfigurationBuilder.
Chamar o provedor por último permite que os argumentos de linha de comando passados em tempo
de execução substituam a configuração definida por outros provedores de configuração.
Aplique a configuração ao WebHostBuilder com o método UseConfiguration:
// Call additional providers here as needed.
// Call AddCommandLine last to allow arguments to override other configuration.
.Build();

.UseKestrel()
Exemplo
O aplicativo de exemplo 2.x aproveita a vantagem do método de conveniência estático
CreateDefaultBuilder para criar o host, que inclui uma chamada para AddCommandLine.
O aplicativo de exemplo 1.x chama AddCommandLine em um ConfigurationBuilder.

1. Abra um prompt de comando no diretório do projeto.
2. Forneça um argumento de linha de comando para o comando dotnet run ,
dotnet run CommandLineKey=CommandLineValue .
3. Quando o aplicativo estiver em execução, abra um navegador para o aplicativo em
http://localhost:5000 .
4. Observe que a saída contém o par chave-valor do argumento de linha de comando de configuração
fornecido para dotnet run .
Arguments
O valor deve vir após um sinal de igual ( = ), ou a chave deve ter um prefixo ( -- ou / ) quando o
valor vier após um espaço. O valor pode ser nulo se um sinal de igual for usado (por exemplo,
CommandLineKey= ).
PREFIXO DA CHAVE EXEMPLO
Nenhum prefixo CommandLineKey1=value1
Dois traços ( -- ) --CommandLineKey2=value2 ,

--CommandLineKey2 value2
Barra ( / ) /CommandLineKey3=value3 ,
/CommandLineKey3 value3
No mesmo comando, não combine pares chave-valor do argumento de linha de comando que usam
um sinal de igual com pares chave-valor que usam um espaço.
Exemplo de comandos:
dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3

dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run CommandLineKey1= CommandLineKey2=value2
Mapeamentos de comutador
Os mapeamentos de comutador permitem fornecer a lógica de substituição do nome da chave.
Quando você cria manualmente a configuração com um ConfigurationBuilder, pode fornecer um
dicionário de substituições de opções para o método AddCommandLine.
Ao ser usado, o dicionário de mapeamentos de comutador é verificado para oferecer uma chave que
corresponda à chave fornecida por um argumento de linha de comando. Se a chave de linha de
comando for encontrada no dicionário, o valor do dicionário (a substituição da chave) será passado de
volta para definir o par chave-valor na configuração do aplicativo. Um mapeamento de comutador é
necessário para qualquer chave de linha de comando prefixada com um traço único ( - ).
Regras de chave do dicionário de mapeamentos de comutador:
Os comutadores devem começar com um traço ( - ) ou traço duplo ( -- ).
O dicionário de mapeamentos de comutador chave não deve conter chaves duplicadas.
Chame ConfigureAppConfiguration ao criar o host para especificar a configuração do aplicativo:

{
public static readonly Dictionary<string, string> _switchMappings =
new Dictionary<string, string>
{
{ "-CLKey1", "CommandLineKey1" },
{ "-CLKey2", "CommandLineKey2" }
};

{
}
// Do not pass the args to CreateDefaultBuilder

WebHost.CreateDefaultBuilder()
{
config.AddCommandLine(args, _switchMappings);
})
}
Conforme mostrado no exemplo anterior, a chamada para CreateDefaultBuilder não deve passar
argumentos ao usar mapeamentos de opção. A chamada AddCommandLine do método
CreateDefaultBuilder não inclui opções mapeadas, e não é possível passar o dicionário de
mapeamento de opções para CreateDefaultBuilder . Se os argumentos incluírem uma opção mapeada
e forem passados para CreateDefaultBuilder , o provedor AddCommandLine não inicializará com um
FormatException. A solução não é passar os argumentos para CreateDefaultBuilder , mas, em vez
disso, permitir que o método AddCommandLine do método ConfigurationBuilder processe os dois
argumentos e o dicionário de mapeamento de opções.
{
{
}

{
var switchMappings = new Dictionary<string, string>
{
};

.AddCommandLine(args, switchMappings)
.Build();
// Do not pass the args to CreateDefaultBuilder

return WebHost.CreateDefaultBuilder()
}
}
Conforme mostrado no exemplo anterior, a chamada para CreateDefaultBuilder não deve passar
argumentos ao usar mapeamentos de opção. A chamada AddCommandLine do método
CreateDefaultBuilder não inclui opções mapeadas, e não é possível passar o dicionário de
mapeamento de opções para CreateDefaultBuilder . Se os argumentos incluírem uma opção mapeada
e forem passados para CreateDefaultBuilder , o provedor AddCommandLine não inicializará com um
FormatException. A solução não é passar os argumentos para CreateDefaultBuilder , mas, em vez
disso, permitir que o método AddCommandLine do método ConfigurationBuilder processe os dois
argumentos e o dicionário de mapeamento de opções.

{
var switchMappings = new Dictionary<string, string>
{
};

.AddCommandLine(args, switchMappings)
.Build();

.UseKestrel()
.Start();
using (host)
{
Console.ReadLine();
}
}
Depois que o dicionário de mapeamentos de comutador for criado, ele conterá os dados mostrados na
tabela a seguir.
CHAVE VALOR
-CLKey1 CommandLineKey1
-CLKey2 CommandLineKey2
Se as chaves mapeadas para opção forem usadas ao iniciar o aplicativo, a configuração receberá o
valor de configuração na chave fornecida pelo dicionário:
dotnet run -CLKey1=value1 -CLKey2=value2
Após a execução do comando anterior, a configuração conterá os valores mostrados na tabela a seguir.
CHAVE VALOR
CommandLineKey1 value1
CommandLineKey2 value2
Provedor de Configuração de Variáveis de Ambiente

O EnvironmentVariablesConfigurationProvider carrega a configuração dos pares chave-valor da
variável de ambiente em tempo de execução.
Para ativar a configuração das variáveis de ambiente, chame o método de extensão
AddEnvironmentVariables em uma instância do ConfigurationBuilder.
Ao trabalhar com chaves hierárquicas nas variáveis de ambiente, talvez um separador de dois-pontos (
: ) não funcione em todas as plataformas. Um sublinhado duplo ( __ ) é compatível com todas as
plataformas e é substituído por dois-pontos.
O Serviço de Aplicativo do Azure permite que você defina variáveis de ambiente no portal do Azure
que podem substituir a configuração do aplicativo usando o Provedor de Configuração de Variáveis de
Ambiente. Para saber mais, confira Aplicativos do Azure: substituir a configuração do aplicativo usando
o portal do Azure.
AddEnvironmentVariables é chamado automaticamente quando você inicializa um novo
WebHostBuilder com CreateDefaultBuilder. Para saber mais, veja o tópico Host da Web: configurar um
host.
Configuração opcional de appsettings.json e appsettings.{Environment}.json.
Argumentos de linha de comando.
O Provedor de Configuração de Variáveis de Ambiente é chamado depois que a configuração é
estabelecida por meio dos segredos do usuário e dos arquivos appsettings. Chamar o provedor nessa
posição permite que as variáveis de ambiente sejam lidas em tempo de execução para substituir a
configuração definida por segredos do usuário e arquivos appsettings.
Chame ConfigureAppConfiguration ao criar o host para especificar a configuração do aplicativo.
AddEnvironmentVariables para variáveis de ambiente com o prefixo ASPNETCORE_ já foi chamado por
CreateDefaultBuilder . Se precisar fornecer configuração do aplicativo com base em variáveis de
ambiente adicionais, chame os provedores adicionais do aplicativo no ConfigureAppConfiguratione
chame AddEnvironmentVariables com o prefixo.

{
{
}

{
// Call AddEnvironmentVariables last if you need to allow environment
// variables to override values from other providers.
config.AddEnvironmentVariables(prefix: "PREFIX_");
})
}

Chame o método de extensão AddEnvironmentVariables em uma instância de ConfigurationBuilder.
Aplique a configuração ao WebHostBuilder com o método UseConfiguration.
AddEnvironmentVariables para variáveis de ambiente com o prefixo ASPNETCORE_ já foi chamado por
CreateDefaultBuilder . Se precisar fornecer configuração do aplicativo com base em variáveis de
ambiente adicionais, chame os provedores adicionais do aplicativo no ConfigureAppConfiguratione
chame AddEnvironmentVariables com o prefixo.

{
{
}

{
// Call AddEnvironmentVariables last if you need to allow environment
// variables to override values from other providers.
.AddEnvironmentVariables(prefix: "PREFIX_")
.Build();
}
}

.AddEnvironmentVariables()
.Build();

.UseKestrel()
Exemplo
CreateDefaultBuilder para criar o host, que inclui uma chamada para AddEnvironmentVariables .
O aplicativo de exemplo 1.x chama AddEnvironmentVariables em um ConfigurationBuilder .

1. Execute o aplicativo de exemplo. Abra um navegador para o aplicativo em http://localhost:5000 .
2. Observe que a saída contém o par chave-valor da variável de ambiente ENVIRONMENT . O valor reflete
o ambiente no qual o aplicativo está em execução, normalmente Development ao executar
localmente.
Para encurtar a lista de variáveis de ambiente renderizadas pelo aplicativo, o aplicativo filtra as
variáveis de ambiente para mostrar as que começam com o seguinte:
ASPNETCORE_
urls
Registrando em log
AMBIENTE
contentRoot
AllowedHosts
applicationName
CommandLine
Se você quiser expor todas as variáveis de ambiente disponíveis para o aplicativo, altere o
FilteredConfiguration em Pages/Index.cshtml.cs para o seguinte:
Se você quiser expor todas as variáveis de ambiente disponíveis para o aplicativo, altere o
FilteredConfiguration em Controllers/HomeController.cs para o seguinte:
FilteredConfiguration = _config.AsEnumerable();
Prefixos
Variáveis de ambiente carregadas na configuração do aplicativo são filtradas quando você fornece um
prefixo para o método AddEnvironmentVariables . Por exemplo, para filtrar as variáveis de ambiente no
prefixo CUSTOM_ , forneça o prefixo para o provedor de configuração:

.AddEnvironmentVariables("CUSTOM_")
.Build();
O prefixo é removido na criação dos pares chave-valor de configuração.

O método de conveniência estático CreateDefaultBuilder cria um WebHostBuilder para estabelecer o
host do aplicativo. Quando WebHostBuilder é criado, ele encontra a configuração de seu host nas
variáveis de ambiente prefixadas com ASPNETCORE_ .
Prefixos de cadeia de conexão
A API de configuração tem regras de processamento especiais para quatro variáveis de ambiente de
cadeia de conexão envolvidas na configuração de cadeias de conexão do Azure para o ambiente de
aplicativo. As variáveis de ambiente com os prefixos mostrados na tabela são carregadas no aplicativo
se nenhum prefixo for fornecido para AddEnvironmentVariables .
PREFIXO DA CADEIA DE CONEXÃO PROVIDER
CUSTOMCONNSTR_ Provedor personalizado
MYSQLCONNSTR_ MySQL
SQLAZURECONNSTR_ Banco de Dados SQL do Azure
SQLCONNSTR_ SQL Server
Quando uma variável de ambiente for descoberta e carregada na configuração com qualquer um dos
quatro prefixos mostrados na tabela:
A chave de configuração é criada removendo o prefixo da variável de ambiente e adicionando uma
seção de chave de configuração ( ConnectionStrings ).
Um novo par chave-valor de configuração é criado para representar o provedor de conexão de
banco de dados (exceto para CUSTOMCONNSTR_ , que não tem um provedor indicado).
CHAVE DE CONFIGURAÇÃO ENTRADA DE CONFIGURAÇÃO DO

CHAVE DE VARIÁVEL DE AMBIENTE CONVERTIDA PROVEDOR
CUSTOMCONNSTR_<KEY> ConnectionStrings:<KEY> Entrada de configuração não criada.
MYSQLCONNSTR_<KEY> ConnectionStrings:<KEY> Chave:

ConnectionStrings:
<KEY>_ProviderName
:
Valor: MySql.Data.MySqlClient
SQLAZURECONNSTR_<KEY> ConnectionStrings:<KEY> Chave:

ConnectionStrings:
<KEY>_ProviderName
:
Valor: System.Data.SqlClient
SQLCONNSTR_<KEY> ConnectionStrings:<KEY> Chave:

ConnectionStrings:
<KEY>_ProviderName
:
Valor: System.Data.SqlClient
Provedor de Configuração de Arquivo

FileConfigurationProvider é a classe base para carregamento da configuração do sistema de arquivos.
Os provedores de configuração a seguir são dedicados a tipos específicos de arquivos:
Provedor de Configuração INI
Provedor de Configuração JSON
Provedor de Configuração XML
Provedor de Configuração INI
O IniConfigurationProvider carrega a configuração de pares chave-valor do arquivo INI em tempo de
execução.
Para ativar a configuração de arquivo INI, chame o método de extensão AddIniFile em uma instância
do ConfigurationBuilder.
Os dois-pontos podem ser usados como um delimitador de seção na configuração do arquivo INI.
As sobrecargas permitem especificar:
Se o arquivo é opcional.
Se a configuração será recarregada caso o arquivo seja alterado.
O IFileProvider usado para acessar o arquivo.

{
{
}

{
config.AddIniFile("config.ini", optional: true, reloadOnChange: true);
})
}

Ao chamar CreateDefaultBuilder , chame UseConfiguration com a configuração:

{
{
}

{
.AddIniFile("config.ini", optional: true, reloadOnChange: true)
.Build();
}
}

.AddIniFile("config.ini", optional: true, reloadOnChange: true)
.Build();

.UseKestrel()
Um exemplo genérico de um arquivo de configuração INI:
[section0]
key0=value
key1=value
[section1]
subsection:key=value
[section2:subsection0]
key=value
[section2:subsection1]
key=value
O arquivo de configuração anterior carrega as seguintes chaves com value :

section0:key0
section0:key1
section1:subsection:key
section2:subsection0:key
section2:subsection1:key
Provedor de Configuração JSON
O JsonConfigurationProvider carrega a configuração de pares chave-valor do arquivo JSON em
tempo de execução.
Para ativar a configuração de arquivo JSON, chame o método de extensão AddJsonFile em uma
instância do ConfigurationBuilder.
AddJsonFileé chamado automaticamente duas vezes quando você inicializa um novo WebHostBuilder
com CreateDefaultBuilder. O método é chamado para carregar a configuração de:
appsettings.json – Esse arquivo é lido primeiro. A versão do ambiente do arquivo pode substituir os
valores fornecidos pelo arquivo appsettings.json.
appsettings.{Environment}.json – A versão de ambiente do arquivo é carregada com base em
IHostingEnvironment.EnvironmentName.
Para saber mais, veja o tópico Host da Web: configurar um host.
O Provedor de Configuração JSON é estabelecido primeiro. Portanto, os segredos do usuário, as
variáveis de ambiente e os argumentos de linha de comando substituem a configuração definida pelos
arquivos appsettings.
Chame ConfigureAppConfiguration ao criar o host para especificar a configuração do aplicativo para
arquivos que não sejam appsettings.json e appsettings.{Environment}.json:

{
{
}

{
config.AddJsonFile("config.json", optional: true, reloadOnChange: true);
})
}

Você pode chamar diretamente o método de extensão AddJsonFile em uma instância do
ConfigurationBuilder.

{
{
}

{
.AddJsonFile("config.json", optional: true, reloadOnChange: true)
.Build();
}
}

.AddJsonFile("config.json", optional: true, reloadOnChange: true)
.Build();

.UseKestrel()
Exemplo
CreateDefaultBuilder para criar o host, que inclui duas chamadas para AddJsonFile . A configuração é
carregada de appsettings.json e de appsettings.{Environment}.json.
O aplicativo de exemplo 1.x chama AddJsonFile duas vezes em um ConfigurationBuilder . A
configuração é carregada de appsettings.json e de appsettings.{Environment}.json.
1. Execute o aplicativo de exemplo. Abra um navegador para o aplicativo em http://localhost:5000 .
2. Observe que a saída contém pares chave-valor para a configuração mostrada na tabela de acordo
com o ambiente. Chaves de configuração de registro usam os dois-pontos ( : ) como um separador
hierárquico.
CHAVE VALOR DE DESENVOLVIMENTO VALOR DE PRODUÇÃO
Logging:LogLevel:System Informações Informações
Logging:LogLevel:Microsoft Informações Informações
Logging:LogLevel:Default Depurar Erro
AllowedHosts * *
Provedor de Configuração XML

O XmlConfigurationProvider carrega a configuração de pares chave-valor do arquivo XML em tempo
de execução.
Para ativar a configuração de arquivo XML, chame o método de extensão AddXmlFile em uma
instância do ConfigurationBuilder.
O nó raiz do arquivo de configuração é ignorado quando os pares chave-valor da configuração são
criados. Não especifique um DTD (definição de tipo de documento) ou um namespace no arquivo.
{
{
}

{
config.AddXmlFile("config.xml", optional: true, reloadOnChange: true);
})
}


{
{
}

{
.AddXmlFile("config.xml", optional: true, reloadOnChange: true)
.Build();
}
}


.AddXmlFile("config.xml", optional: true, reloadOnChange: true)
.Build();

.UseKestrel()
Os arquivos de configuração XML podem usar nomes de elemento distintos para seções repetidas:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<section0>
<key0>value</key0>
<key1>value</key1>
</section0>
<section1>
<key0>value</key0>
<key1>value</key1>
</section1>
</configuration>

section0:key0
section0:key1
section1:key0
section1:key1
Elementos repetidos que usam o mesmo nome de elemento funcionarão se o atributo name for usado
para diferenciar os elementos:

<configuration>
<section name="section0">
<key name="key0">value</key>
</section>
<section name="section1">
</section>
</configuration>

section:section0:key:key0
É possível usar atributos para fornecer valores:

<configuration>
<key attribute="value" />
<section>
<key attribute="value" />
</section>
</configuration>

key:attribute
section:key:attribute
Provedor de Configuração de Chave por Arquivo

O KeyPerFileConfigurationProvider usa arquivos do diretório como pares chave-valor de configuração.
A chave é o nome do arquivo. O valor contém o conteúdo do arquivo. O Provedor de Configuração de
Chave por arquivo é usado em cenários de hospedagem do Docker.
Para ativar a configuração de chave por arquivo, chame o método de extensão AddKeyPerFile em uma
instância do ConfigurationBuilder. O directoryPath para os arquivos deve ser um caminho absoluto.
Um delegado Action<KeyPerFileConfigurationSource> que configura a origem.
Se o diretório é opcional, e o caminho para o diretório.

{
{
}

{
config.AddKeyPerFile(directoryPath: path, optional: true);
})
}
var path = Path.Combine(Directory.GetCurrentDirectory(), "path/to/files");

.AddKeyPerFile(directoryPath: path, optional: true)
.Build();

.UseKestrel()
Provedor de Configuração de Memória

O MemoryConfigurationProvider usa uma coleção na memória como pares chave-valor de
configuração.
Para ativar a configuração de coleção na memória, chame o método de extensão
AddInMemoryCollection em uma instância do ConfigurationBuilder.
O provedor de configuração pode ser inicializado com um IEnumerable<KeyValuePair<String,String>> .
{
public static readonly Dictionary<string, string> _dict =
new Dictionary<string, string>
{
{"MemoryCollectionKey1", "value1"},
{"MemoryCollectionKey2", "value2"}
};

{
}

{
config.AddInMemoryCollection(_dict);
})
}


{
{
}

{
var dict = new Dictionary<string, string>
{
};

.AddInMemoryCollection(dict)
.Build();
}
}

{
};

.AddInMemoryCollection(dict)
.Build();

.UseKestrel()
GetValue
ConfigurationBinder.GetValue<T> extrai um valor de configuração com uma chave especificada e o
converte para o tipo especificado. Uma sobrecarga permite que você forneça um valor padrão se a
chave não for encontrada.
O exemplo a seguir extrai o valor de cadeia de caracteres da configuração com a chave NumberKey ,
digita o valor como um int e armazena o valor na variável intValue . Se NumberKey não for
encontrado em chaves de configuração, intValue recebe o valor padrão de 99 :
var intValue = config.GetValue<int>("NumberKey", 99);
GetSection, GetChildren e Exists

Para os exemplos a seguir, considere o seguinte arquivo JSON. Há quatro chaves em duas seções, cada
uma delas inclui um par de subseções:
{
"section0": {
"key0": "value",
"key1": "value"
},
"section1": {
"key0": "value",
"key1": "value"
},
"section2": {
"subsection0" : {
"key0": "value",
"key1": "value"
},
"subsection1" : {
"key0": "value",
"key1": "value"
}
}
}
Quando o arquivo é lido na configuração, as seguintes chaves hierárquicas exclusivas são criadas para
conter os valores de configuração:
section0:key0
section0:key1
section1:key0
section1:key1
section2:subsection0:key0
GetSection
IConfiguration.GetSection extrai uma subseção de configuração com a chave de subseção especificada.
Para retornar um IConfigurationSection que contenha apenas os pares chave-valor em section1 ,
chame GetSection e forneça o nome da seção:
var configSection = _config.GetSection("section1");
Da mesma forma, para obter os valores de chaves em section2:subsection0 , chame GetSection e

forneça o caminho de seção:
var configSection = _config.GetSection("section2:subsection0");
GetSection nunca retorna null . Se uma seção correspondente não for encontrada, um
IConfigurationSection vazio será retornado.
GetChildren
Uma chamada para IConfiguration.GetChildren em section2 obtém um
IEnumerable<IConfigurationSection> que inclui:
subsection0
subsection1
var configSection = _config.GetSection("section2");
var children = configSection.GetChildren();
Exists
Use ConfigurationExtensions.Exists para determinar se há uma seção de configuração:
var sectionExists = _config.GetSection("section2:subsection2").Exists();
Considerando os dados de exemplo, sectionExists é false , pois não existe uma seção
section2:subsection2 nos dados de configuração.
Associar a uma classe

A configuração pode ser associada a classes que representam grupos de configurações relacionadas
usando o padrão de opções. Para obter mais informações, consulte Padrão de opções no ASP.NET
Core.
Os valores de configuração retornam como cadeias de caracteres, mas chamar Bind permite a
construção de objetos POCO.
O aplicativo de exemplo contém um modelo Starship (Models/Starship.cs):
public class Starship
{
public string Registry { get; set; }
public string Class { get; set; }
public decimal Length { get; set; }
public bool Commissioned { get; set; }
}
public class Starship

{
public string Registry { get; set; }
public string Class { get; set; }
public decimal Length { get; set; }
public bool Commissioned { get; set; }
}
A seção starship do arquivo starship.json cria a configuração quando o aplicativo de exemplo usa o
Provedor de Configuração JSON para carregar a configuração:
{
"starship": {
"name": "USS Enterprise",
"registry": "NCC-1701",
"class": "Constitution",
"length": 304.8,
"commissioned": false
},
"trademark": "Paramount Pictures Corp. http://www.paramount.com"
}
{
"starship": {
"name": "USS Enterprise",
"registry": "NCC-1701",
"class": "Constitution",
"length": 304.8,
"commissioned": false
},
"trademark": "Paramount Pictures Corp. http://www.paramount.com"
}
Os seguintes pares chave-valor de configuração são criados:
CHAVE VALOR
starship:name USS Enterprise
starship:registry NCC-1701
starship:class Constituição
starship:length 304,8
starship:commissioned False
CHAVE VALOR
marca Paramount Pictures Corp. http://www.paramount.com
O aplicativo de exemplo chama GetSection com a chave starship . Os pares chave-valor starship
são isolados. O método Bind é chamado na subseção passando uma instância da classe Starship .
Depois de associar os valores de instância, a instância é atribuída a uma propriedade para renderização:
var starship = new Starship();

_config.GetSection("starship").Bind(starship);
Starship = starship;
var starship = new Starship();

_config.GetSection("starship").Bind(starship);
viewModel.Starship = starship;
Associar a um gráfico de objeto

Bind é capaz de associar um grafo de objeto POCO inteiro.
O exemplo contém um modelo TvShow cujo grafo do objeto inclui as classes Metadata e Actors
(Models/TvShow.cs):
public class TvShow

{
public Metadata Metadata { get; set; }
public Actors Actors { get; set; }
public string Legal { get; set; }
}
public class Metadata

{
public string Series { get; set; }
public string Title { get; set; }
public DateTime AirDate { get; set; }
public int Episodes { get; set; }
}
public class Actors

{
public string Names { get; set; }
}
public class TvShow
{
public Metadata Metadata { get; set; }
public Actors Actors { get; set; }
public string Legal { get; set; }
}
public class Metadata

{
public string Series { get; set; }
public DateTime AirDate { get; set; }
public int Episodes { get; set; }
}
public class Actors

{
public string Names { get; set; }
}
O aplicativo de exemplo tem um arquivo tvshow.xml que contém os dados de configuração:

<configuration>
<tvshow>
<metadata>
<series>Dr. Who</series>
<title>The Sun Makers</title>
<airdate>11/26/1977</airdate>
<episodes>4</episodes>
</metadata>
<actors>
<names>Tom Baker, Louise Jameson, John Leeson</names>
</actors>
<legal>(c)1977 BBC https://www.bbc.co.uk/programmes/b006q2x0</legal>
</tvshow>
</configuration>

<configuration>
<tvshow>
<metadata>
<series>Dr. Who</series>
<title>The Sun Makers</title>
<airdate>11/26/1977</airdate>
<episodes>4</episodes>
</metadata>
<actors>
<names>Tom Baker, Louise Jameson, John Leeson</names>
</actors>
<legal>(c)1977 BBC https://www.bbc.co.uk/programmes/b006q2x0</legal>
</tvshow>
</configuration>
A configuração está associada ao método do grafo de objeto TvShow inteiro com o método Bind .A
instância associada é atribuída a uma propriedade para renderização:
var tvShow = new TvShow();

_config.GetSection("tvshow").Bind(tvShow);
TvShow = tvShow;
var tvShow = new TvShow();
_config.GetSection("tvshow").Bind(tvShow);
viewModel.TvShow = tvShow;
ConfigurationBinder.Get<T> associa e retorna o tipo especificado. O Get<T> é mais conveniente do

que usar Bind . O código a seguir mostra como usar Get<T> com o exemplo anterior, que permite que
a instância associada seja diretamente atribuída à propriedade usada para renderização:
TvShow = _config.GetSection("tvshow").Get<TvShow>();
viewModel.TvShow = _config.GetSection("tvshow").Get<TvShow>();
Associar uma matriz a uma classe

O aplicativo de exemplo demonstra os conceitos explicados nesta seção.
O Bind dá suporte a matrizes de associação para objetos usando os índices em chaves de configuração.
Qualquer formato de matriz que exponha um segmento de chave numérica ( :0: , :1: , … :{n}: ) é
capaz de associar matrizes a uma matriz de classe POCO.
NOTE
A associação é fornecida por convenção. Provedores de configuração personalizados não são necessários para
implementar a associação de matriz.
Processamento de matriz na memória

Considere as chaves de configuração e os valores mostrados na tabela a seguir.
CHAVE VALOR
array:0 value0
array:1 value1
array:2 value2
array:4 value4
array:5 value5
Essas chaves e valores são carregados no aplicativo de exemplo usando o Provedor de Configuração
de Memória:
{
{
};

{
}

{
})
}

{
{
var arrayDict = new Dictionary<string, string>
{
};

.AddInMemoryCollection(arrayDict)
.AddJsonFile("json_array.json", optional: false, reloadOnChange: false)
reloadOnChange: true)
.AddJsonFile("starship.json", optional: false, reloadOnChange: false)
.AddXmlFile("tvshow.xml", optional: false, reloadOnChange: false)
.AddEFConfiguration(options => options.UseInMemoryDatabase("InMemoryDb"))
.AddCommandLine(Program.Args);
}
A matriz ignora um valor para o índice #3. O associador de configuração não é capaz de associar
valores nulos ou criar entradas nulas em objetos associados, o que fica claro em um momento quando
o resultado da associação dessa matriz a um objeto é demonstrado.
No aplicativo de exemplo, uma classe POCO está disponível para armazenar os dados de configuração
associados:
public class ArrayExample

{
public string[] Entries { get; set; }
}
public class ArrayExample

{
public string[] Entries { get; set; }
}
Os dados de configuração estão associados ao objeto:
var arrayExample = new ArrayExample();

_config.GetSection("array").Bind(arrayExample);
A sintaxe ConfigurationBinder.Get<T> também pode ser usada, o que resulta em um código mais
compacto:
ArrayExample = _config.GetSection("array").Get<ArrayExample>();
viewModel.ArrayExample = _config.GetSection("array").Get<ArrayExample>();
O objeto associado, uma instância de ArrayExample , recebe os dados da matriz de configuração.
ÍNDICE ARRAYEXAMPLES.ENTRIES VALOR ARRAYEXAMPLES.ENTRIES
0 value0
1 value1
2 value2
3 value4
4 value5
O índice #3 no objeto associado contém os dados de configuração para a chave de configuração

array:4 e seu valor de value4 . Quando os dados de configuração que contêm uma matriz são
associados, os índices da matriz nas chaves de configuração são simplesmente usados para iterar os
dados de configuração ao criar o objeto. Um valor nulo não pode ser mantido nos dados de
configuração, e uma entrada de valor nulo não será criada em um objeto de associação quando uma
matriz nas chaves de configuração ignorar um ou mais índices.
O item de configuração ausente para o índice #3 pode ser fornecido antes da associação à instância
ArrayExamples por qualquer provedor de configuração que produza o par chave-valor correto na
configuração. Se o exemplo incluir um Provedor de Configuração JSON adicional com o par chave-
valor ausente, o ArrayExamples.Entries coincidirá com a matriz de configuração completa:
missing_value.json:
{
"array:entries:3": "value3"
}
No ConfigureAppConfiguration:
config.AddJsonFile("missing_value.json", optional: false, reloadOnChange: false);
No construtor Startup :
.AddJsonFile("missing_value.json", optional: false, reloadOnChange: false);
O par chave-valor mostrado na tabela é carregado na configuração.
CHAVE VALOR
array:entries:3 value3
Se a instância da classe ArrayExamples for associada após o Provedor de Configuração JSON incluir a
entrada para o índice #3, a matriz ArrayExamples.Entries incluirá o valor.
ÍNDICE ARRAYEXAMPLES.ENTRIES VALOR ARRAYEXAMPLES.ENTRIES
0 value0
1 value1
2 value2
3 value3
4 value4
5 value5
Processamento de matriz JSON

Se um arquivo JSON contiver uma matriz, as chaves de configuração serão criadas para os elementos
da matriz com um índice de seção de base zero. No arquivo de configuração a seguir, subsection é
uma matriz:
{
"json_array": {
"key": "valueA",
"subsection": [
"valueB",
"valueC",
"valueD"
]
}
}
{
"json_array": {
"key": "valueA",
"subsection": [
"valueB",
"valueC",
"valueD"
]
}
}
O Provedor de Configuração JSON lê os dados de configuração para os seguintes pares chave-valor:
CHAVE VALOR
json_array:key valueA
json_array:subsection:0 valueB
json_array:subsection:1 valueC
json_array:subsection:2 valueD
No aplicativo de exemplo, a seguinte classe POCO está disponível para associar os pares chave-valor
de configuração:
public class JsonArrayExample

{
public string Key { get; set; }
public string[] Subsection { get; set; }
}
public class JsonArrayExample

{
public string Key { get; set; }
public string[] Subsection { get; set; }
}
Após a associação, JsonArrayExample.Key contém o valor valueA . Os valores de subseção são

armazenados na propriedade matriz POCO, Subsection .
ÍNDICE JSONARRAYEXAMPLE.SUBSECTION VALOR JSONARRAYEXAMPLE.SUBSECTION
0 valueB
1 valueC
2 valueD
Provedor de Configuração personalizado

O aplicativo de exemplo demonstra como criar um provedor de configuração básico que lê os pares
chave-valor da configuração de um banco de dados usando Entity Framework (EF ).
O provedor tem as seguintes características:
O banco de dados EF na memória é usado para fins de demonstração. Para usar um banco de dados
que exija uma cadeia de conexão, implemente um ConfigurationBuilder secundário para fornecer a
cadeia de conexão de outro provedor de configuração.
O provedor lê uma tabela de banco de dados na configuração na inicialização. O provedor não
consulta o banco de dados em uma base por chave.
O recarregamento na alteração não está implementado, portanto, a atualização do banco de dados
após a inicialização do aplicativo não tem efeito sobre a configuração do aplicativo.
Defina uma entidade EFConfigurationValue para armazenar valores de configuração no banco de
dados.
Models/EFConfigurationValue.cs:
public class EFConfigurationValue

{
public string Id { get; set; }
public string Value { get; set; }
}
public class EFConfigurationValue

{
public string Id { get; set; }
public string Value { get; set; }
}
Adicione um EFConfigurationContext para armazenar e acessar os valores configurados.

EFConfigurationProvider/EFConfigurationContext.cs:
public class EFConfigurationContext : DbContext

{
public EFConfigurationContext(DbContextOptions options) : base(options)
{
}
public DbSet<EFConfigurationValue> Values { get; set; }

}
public class EFConfigurationContext : DbContext

{
public EFConfigurationContext(DbContextOptions options) : base(options)
{
}
public DbSet<EFConfigurationValue> Values { get; set; }

}
Crie uma classe que implementa IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:
public class EFConfigurationSource : IConfigurationSource
{
private readonly Action<DbContextOptionsBuilder> _optionsAction;
public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction)

{
_optionsAction = optionsAction;
}
public IConfigurationProvider Build(IConfigurationBuilder builder)

{
return new EFConfigurationProvider(_optionsAction);
}
}
public class EFConfigurationSource : IConfigurationSource

{
private readonly Action<DbContextOptionsBuilder> _optionsAction;
public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction)

{
_optionsAction = optionsAction;
}
public IConfigurationProvider Build(IConfigurationBuilder builder)

{
return new EFConfigurationProvider(_optionsAction);
}
}
Crie o provedor de configuração personalizado através da herança de ConfigurationProvider. O

provedor de configuração inicializa o banco de dados quando ele está vazio.
EFConfigurationProvider/EFConfigurationProvider.cs:
public class EFConfigurationProvider : ConfigurationProvider
{
public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
{
OptionsAction = optionsAction;
}
Action<DbContextOptionsBuilder> OptionsAction { get; }
// Load config data from EF DB.

public override void Load()
{
var builder = new DbContextOptionsBuilder<EFConfigurationContext>();
OptionsAction(builder);
using (var dbContext = new EFConfigurationContext(builder.Options))

{
dbContext.Database.EnsureCreated();
Data = !dbContext.Values.Any()
? CreateAndSaveDefaultValues(dbContext)
: dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
}
}
private static IDictionary<string, string> CreateAndSaveDefaultValues(

EFConfigurationContext dbContext)
{
// Quotes (c)2005 Universal Pictures: Serenity
// https://www.uphe.com/movies/serenity
var configValues = new Dictionary<string, string>
{
{ "quote1", "I aim to misbehave." },
{ "quote2", "I swallowed a bug." },
{ "quote3", "You can't stop the signal, Mal." }
};
dbContext.Values.AddRange(configValues
.Select(kvp => new EFConfigurationValue
{
Id = kvp.Key,
Value = kvp.Value
})
.ToArray());
dbContext.SaveChanges();
return configValues;
}
}
public class EFConfigurationProvider : ConfigurationProvider
{
public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
{
OptionsAction = optionsAction;
}
Action<DbContextOptionsBuilder> OptionsAction { get; }
// Load config data from EF DB.

public override void Load()
{
var builder = new DbContextOptionsBuilder<EFConfigurationContext>();
OptionsAction(builder);
using (var dbContext = new EFConfigurationContext(builder.Options))

{
dbContext.Database.EnsureCreated();
Data = !dbContext.Values.Any()
? CreateAndSaveDefaultValues(dbContext)
: dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
}
}
private static IDictionary<string, string> CreateAndSaveDefaultValues(

EFConfigurationContext dbContext)
{
// Quotes (c)2005 Universal Pictures: Serenity
// https://www.uphe.com/movies/serenity
var configValues = new Dictionary<string, string>
{
{ "quote1", "I aim to misbehave." },
{ "quote2", "I swallowed a bug." },
{ "quote3", "You can't stop the signal, Mal." }
};
dbContext.Values.AddRange(configValues
.Select(kvp => new EFConfigurationValue
{
Id = kvp.Key,
Value = kvp.Value
})
.ToArray());
dbContext.SaveChanges();
return configValues;
}
}
Um método de extensão AddEFConfiguration permite adicionar a fonte de configuração a um

ConfigurationBuilder .
Extensions/EntityFrameworkExtensions.cs:
public static class EntityFrameworkExtensions
{
public static IConfigurationBuilder AddEFConfiguration(
this IConfigurationBuilder builder,
Action<DbContextOptionsBuilder> optionsAction)
{
return builder.Add(new EFConfigurationSource(optionsAction));
}
}
public static class EntityFrameworkExtensions

{
public static IConfigurationBuilder AddEFConfiguration(
this IConfigurationBuilder builder,
Action<DbContextOptionsBuilder> optionsAction)
{
return builder.Add(new EFConfigurationSource(optionsAction));
}
}
O código a seguir mostra como usar o EFConfigurationProvider personalizado em Program.cs:

{
{
};

{
}

{
})
}
{
{
var arrayDict = new Dictionary<string, string>
{
};

.AddInMemoryCollection(arrayDict)
.AddJsonFile("json_array.json", optional: false, reloadOnChange: false)
.AddJsonFile("starship.json", optional: false, reloadOnChange: false)
.AddXmlFile("tvshow.xml", optional: false, reloadOnChange: false)
.AddEFConfiguration(options => options.UseInMemoryDatabase("InMemoryDb"))
.AddCommandLine(Program.Args);
}
Acessar a configuração durante a inicialização

Injete IConfigurationno construtor Startup para acessar os valores de configuração em
Startup.ConfigureServices . Para acessar a configuração em Startup.Configure , injete IConfiguration
diretamente no método ou use a instância do construtor:

{
private readonly IConfiguration _config;
public Startup(IConfiguration config)

{
_config = config;
}

{
var value = _config["key"];
}
public void Configure(IApplicationBuilder app, IConfiguration config)

{
var value = config["key"];
}
}
Para obter um exemplo de como acessar a configuração usando os métodos de conveniência de

inicialização, consulte Inicialização do aplicativo: métodos de conveniência.
Acessar a configuração em uma página do Razor Pages ou

exibição do MVC
Para acessar definições de configuração em uma página do Razor Pages ou uma exibição do MVC,
adicione usando diretiva (referência de C#: usando diretiva) para o namespace
Microsoft.Extensions.Configuration e injete IConfiguration na página ou na exibição.
Em uma página do Razor:
@page
@model IndexModel
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
<!DOCTYPE html>
<html lang="en">
<head>
<title>Index Page</title>
</head>
<body>
<h1>Access configuration in a Razor Pages page</h1>
<p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>
Em uma exibição do MVC:
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
<!DOCTYPE html>
<html lang="en">
<head>
<title>Index View</title>
</head>
<body>
<h1>Access configuration in an MVC view</h1>
<p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>
Adicionar configuração de um assembly externo

Uma implementação IHostingStartup permite adicionar melhorias a um aplicativo durante a
inicialização de um assembly externo fora da classe Startup do aplicativo. Para obter mais
informações, consulte Aprimorar um aplicativo por meio de um assembly externo no ASP.NET Core
com IHostingStartup.
Recursos adicionais
Padrão de opções no ASP.NET Core
Detalhes da configuração da Microsoft
Padrão de opções no ASP.NET Core
Por Luke Latham

O padrão de opções usa classes para representar grupos de configurações relacionadas. Quando as definições
de configuração são isoladas por cenário em classes separadas, o aplicativo segue dois princípios importantes
de engenharia de software:
O ISP (Princípio de Segregação da Interface): os cenários (classes) que dependem das definições de
configuração dependem apenas das definições de configuração usadas por eles.
Separação de Interesses: as configurações para diferentes partes do aplicativo não são dependentes nem
acopladas entre si.
Exiba ou baixe o código de exemplo (como baixar) Este artigo é mais fácil de ser acompanhado com o aplicativo
de exemplo.
Pré-requisitos
Referencie o metapacote Microsoft.AspNetCore.App ou adicione uma referência de pacote ao pacote
Microsoft.Extensions.Options.ConfigurationExtensions.
Referencie o metapacote Microsoft.AspNetCore.All ou adicione uma referência de pacote ao pacote
Microsoft.Extensions.Options.ConfigurationExtensions.
Adicione uma referência de pacote ao pacote Microsoft.Extensions.Options.ConfigurationExtensions.
Configuração de opções básicas

A configuração de opções básicas é demonstrada como o Exemplo #1 no aplicativo de exemplo.
Uma classe de opções deve ser não abstrata com um construtor público sem parâmetros. A classe a seguir,
MyOptions , tem duas propriedades, Option1 e Option2 . A configuração de valores padrão é opcional, mas o
construtor de classe no exemplo a seguir define o valor padrão de Option1 . Option2 tem um valor padrão
definido com a inicialização da propriedade diretamente (Models/MyOptions.cs):
public class MyOptions

{
public MyOptions()
{
// Set default value.
Option1 = "value1_from_ctor";
}
public string Option1 { get; set; }

public int Option2 { get; set; } = 5;
}
A classe MyOptions é adicionada ao contêiner de serviço com Configure<TOptions>(IServiceCollection,

IConfiguration) e é associada à configuração:
// Example #1: Basic options
// Register the Configuration instance which MyOptions binds against.
services.Configure<MyOptions>(Configuration);
O seguinte modelo de página usa a injeção de dependência de construtor com IOptions<TOptions> para
acessar as configurações (Pages/Index.cshtml.cs):
private readonly MyOptions _options;
public IndexModel(
IOptions<MyOptions> optionsAccessor,
IOptions<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig,
IOptions<MySubOptions> subOptionsAccessor,
IOptionsSnapshot<MyOptions> snapshotOptionsAccessor,
IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
_options = optionsAccessor.Value;
_optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.Value;
_subOptions = subOptionsAccessor.Value;
_snapshotOptions = snapshotOptionsAccessor.Value;
_named_options_1 = namedOptionsAccessor.Get("named_options_1");
}
// Example #1: Simple options

var option1 = _options.Option1;
var option2 = _options.Option2;
SimpleOptions = $"option1 = {option1}, option2 = {option2}";
O arquivo appsettings.json de exemplo especifica valores para option1 e option2 :
{
"option1": "value1_from_json",
"option2": -1,
"subsection": {
"suboption1": "subvalue1_from_json",
"suboption2": 200
},
"Logging": {
"LogLevel": {
"Default": "Warning"
}
},
"AllowedHosts": "*"
}
Quando o aplicativo é executado, o método OnGet do modelo de página retorna uma cadeia de caracteres que
mostra os valores da classe de opção:
option1 = value1_from_json, option2 = -1

NOTE
Ao usar um ConfigurationBuilder personalizado para carregar opções de configuração de um arquivo de configuração,
confirme se o caminho de base está corretamente configurado:
var configBuilder = new ConfigurationBuilder()

.AddJsonFile("appsettings.json", optional: true);
var config = configBuilder.Build();
services.Configure<MyOptions>(config);
Não é necessário configurar o caminho de base explicitamente ao carregar opções de configuração do arquivo de
configuração por meio do CreateDefaultBuilder.
Configurar opções simples com um delegado

A configuração de opções simples com um delegado é demonstrada como o Exemplo #2 no aplicativo de
exemplo.
Use um delegado para definir valores de opções. O aplicativo de exemplo usa a classe
MyOptionsWithDelegateConfig ( Models/MyOptionsWithDelegateConfig.cs):
public class MyOptionsWithDelegateConfig

{
public MyOptionsWithDelegateConfig()
{
// Set default value.
Option1 = "value1_from_ctor";
}
public string Option1 { get; set; }

public int Option2 { get; set; } = 5;
}
No código a seguir, um segundo serviço IConfigureOptions<TOptions> é adicionado ao contêiner de serviço. Ele

usa um delegado para configurar a associação com MyOptionsWithDelegateConfig :
// Example #2: Options bound and configured by a delegate

services.Configure<MyOptionsWithDelegateConfig>(myOptions =>
{
myOptions.Option1 = "value1_configured_by_delegate";
myOptions.Option2 = 500;
});
Index.cshtml.cs:
private readonly MyOptionsWithDelegateConfig _optionsWithDelegateConfig;

public IndexModel(
{
}
// Example #2: Options configured by delegate

var delegate_config_option1 = _optionsWithDelegateConfig.Option1;
var delegate_config_option2 = _optionsWithDelegateConfig.Option2;
SimpleOptionsWithDelegateConfig =
$"delegate_option1 = {delegate_config_option1}, " +
$"delegate_option2 = {delegate_config_option2}";
Adicione vários provedores de configuração. Provedores de configuração estão disponíveis em pacotes NuGet.
Eles são aplicados na ordem em que são registrados.
Cada chamada à Configure<TOptions> adiciona um serviço IConfigureOptions<TOptions> ao contêiner de
serviço. No exemplo anterior, os valores Option1 e Option2 são especificados em appsettings.json, mas os
valores Option1 e Option2 são substituídos pelo delegado configurado.
Quando mais de um serviço de configuração é habilitado, a última fonte de configuração especificada vence e
define o valor de configuração. Quando o aplicativo é executado, o método OnGet do modelo de página
retorna uma cadeia de caracteres que mostra os valores da classe de opção:
delegate_option1 = value1_configured_by_delgate, delegate_option2 = 500
Configuração de subopções
A configuração de subopções básicas é demonstrada no Exemplo #3 no aplicativo de exemplo.
Os aplicativos devem criar classes de opções que pertencem a grupos de cenários específicos (classes) no
aplicativo. Partes do aplicativo que exigem valores de configuração devem ter acesso apenas aos valores de
configuração usados por elas.
Ao associar opções à configuração, cada propriedade no tipo de opções é associada a uma chave de
configuração do formato property[:sub-property:] . Por exemplo, a propriedade MyOptions.Option1 é associada
à chave Option1 , que é lida da propriedade option1 em appsettings.json.
No código a seguir, um terceiro serviço IConfigureOptions<TOptions> é adicionado ao contêiner de serviço. Ele
associa MySubOptions à seção subsection do arquivo appsettings.json:
// Example #3: Sub-options

// Bind options using a sub-section of the appsettings.json file.
services.Configure<MySubOptions>(Configuration.GetSection("subsection"));
O método de extensão GetSection exige o pacote NuGet

Microsoft.Extensions.Options.ConfigurationExtensions. Se o aplicativo usa o metapacote
Microsoft.AspNetCore.App (ASP.NET Core 2.1 ou posterior), o pacote é automaticamente incluído.
O arquivo appsettings.json de exemplo define um membro subsection com chaves para suboption1 e
suboption2 :
{
"option1": "value1_from_json",
"option2": -1,
"subsection": {
"suboption1": "subvalue1_from_json",
"suboption2": 200
},
"Logging": {
"LogLevel": {
}
},
"AllowedHosts": "*"
}
A classe MySubOptions define as propriedades SubOption1 e SubOption2 , para armazenar os valores de opções
(Models/MySubOptions.cs):
public class MySubOptions

{
public MySubOptions()
{
// Set default values.
SubOption1 = "value1_from_ctor";
SubOption2 = 5;
}
public string SubOption1 { get; set; }

public int SubOption2 { get; set; }
}
O método OnGet do modelo da página retorna uma cadeia de caracteres com os valores de opções
(Pages/Index.cshtml.cs):
private readonly MySubOptions _subOptions;
public IndexModel(
{
}
// Example #3: Sub-options
var subOption1 = _subOptions.SubOption1;
var subOption2 = _subOptions.SubOption2;
SubOptions = $"subOption1 = {subOption1}, subOption2 = {subOption2}";
Quando o aplicativo é executado, o método OnGet retorna uma cadeia de caracteres que mostra os valores da
classe de subopção:
subOption1 = subvalue1_from_json, subOption2 = 200
Opções fornecidas por um modelo de exibição ou com a injeção de

exibição direta
As opções fornecidas por um modelo de exibição ou com a injeção de exibição direta são demonstradas como o
Exemplo #4 no aplicativo de exemplo.
As opções podem ser fornecidas em um modelo de exibição ou pela injeção de IOptions<TOptions>
diretamente em uma exibição (Pages/Index.cshtml.cs):
private readonly MyOptions _options;
public IndexModel(
{
}
// Example #4: Bind options directly to the page

MyOptions = _options;
Para a injeção direta, injete IOptions<MyOptions> com uma diretiva @inject :
@page
@model IndexModel
@using Microsoft.Extensions.Options
@using UsingOptionsSample.Models
@inject IOptions<MyOptions> OptionsAccessor
@{
ViewData["Title"] = "Using Options Sample";
}
Quando o aplicativo é executado, os valores de opções são mostrados na página renderizada:

Recarregar dados de configuração com IOptionsSnapshot
O recarregamento de dados de configuração com IOptionsSnapshot é demonstrado no Exemplo #5 no
aplicativo de exemplo.
IOptionsSnapshot dá suporte a opções de recarregamento com sobrecarga mínima de processamento.
As opções são calculadas uma vez por solicitação, quando acessadas e armazenadas em cache durante o tempo
de vida da solicitação.
IOptionsSnapshot é um instantâneo de IOptionsMonitor<TOptions> e é atualizado automaticamente sempre
que o monitor dispara alterações com base na alteração da fonte de dados.
O exemplo a seguir demonstra como um novo IOptionsSnapshot é criado após a alteração de appsettings.json
(Pages/Index.cshtml.cs). Várias solicitações ao servidor retornam valores de constante fornecidos pelo arquivo
appsettings.json, até que o arquivo seja alterado e a configuração seja recarregada.
private readonly MyOptions _snapshotOptions;
public IndexModel(
{
}
// Example #5: Snapshot options

var snapshotOption1 = _snapshotOptions.Option1;
var snapshotOption2 = _snapshotOptions.Option2;
SnapshotOptions =
$"snapshot option1 = {snapshotOption1}, " +
$"snapshot option2 = {snapshotOption2}";
A seguinte imagem mostra is valores option1 e option2 iniciais carregados do arquivo appsettings.json:
snapshot option1 = value1_from_json, snapshot option2 = -1
Altere os valores no arquivo appsettings.json para value1_from_json UPDATED e 200 . Salve o arquivo
appsettings.json. Atualize o navegador para ver se os valores de opções foram atualizados:
snapshot option1 = value1_from_json UPDATED, snapshot option2 = 200
Suporte de opções nomeadas com IConfigureNamedOptions

O suporte de opções nomeadas com IConfigureNamedOptions é demonstrado no Exemplo #6 no aplicativo de
exemplo.
O suporte de opções nomeadas permite que o aplicativo faça a distinção entre as configurações de opções
nomeadas. No aplicativo de exemplo, as opções nomeadas são declaradas com a
OptionsServiceCollectionExtensions.Configure<TOptions>(IServiceCollection, String, Action<TOptions>), que,
por sua vez, chama o método ConfigureNamedOptions<TOptions>.Configure do método de extensão:
// Example #6: Named options (named_options_1)

// Register the ConfigurationBuilder instance which MyOptions binds against.
// Specify that the options loaded from configuration are named
// "named_options_1".
services.Configure<MyOptions>("named_options_1", Configuration);
// Example #6: Named options (named_options_2)

// Specify that the options loaded from the MyOptions class are named
// "named_options_2".
// Use a delegate to configure option values.
services.Configure<MyOptions>("named_options_2", myOptions =>
{
myOptions.Option1 = "named_options_2_value1_from_action";
});
O aplicativo de exemplo acessa as opções nomeadas com IOptionsSnapshot<TOptions>.Get

(Pages/Index.cshtml.cs):
private readonly MyOptions _named_options_1;

private readonly MyOptions _named_options_2;
public IndexModel(
{
}
// Example #6: Named options
var named_options_1 =
$"named_options_1: option1 = {_named_options_1.Option1}, " +
$"option2 = {_named_options_1.Option2}";
var named_options_2 =
$"named_options_2: option1 = {_named_options_2.Option1}, " +
$"option2 = {_named_options_2.Option2}";
NamedOptions = $"{named_options_1} {named_options_2}";
Executando o aplicativo de exemplo, as opções nomeadas são retornadas:
named_options_1: option1 = value1_from_json, option2 = -1

named_options_2: option1 = named_options_2_value1_from_action, option2 = 5
Os valores named_options_1 são fornecidos pela configuração, que são carregados do arquivo appsettings.json.
Os valores named_options_2 são fornecidos pelo:
Delegado named_options_2 em ConfigureServices para Option1 .
Valor padrão para Option2 fornecido pela classe MyOptions .
Configurar todas as opções com o método ConfigureAll

Configure todas as instâncias de opções com o método OptionsServiceCollectionExtensions.ConfigureAll. O
código a seguir configura Option1 para todas as instâncias de configuração com um valor comum. Adicione o
seguinte código manualmente ao método Configure :
services.ConfigureAll<MyOptions>(myOptions =>
{
myOptions.Option1 = "ConfigureAll replacement value";
});
A execução do aplicativo de exemplo após a adição do código produz o seguinte resultado:
named_options_1: option1 = ConfigureAll replacement value, option2 = -1

named_options_2: option1 = ConfigureAll replacement value, option2 = 5
NOTE
Todas as opções são instâncias nomeadas. As instâncias IConfigureOption existentes são tratadas como sendo
direcionadas à instância Options.DefaultName , que é string.Empty . IConfigureNamedOptions também implementa
IConfigureOptions . A implementação padrão de IOptionsFactory<TOptions> (fonte de referência tem uma lógica para
usar cada uma de forma adequada. A opção nomeada null é usada para direcionar todas as instâncias nomeadas, em
vez de uma instância nomeada específica (ConfigureAll e PostConfigureAll usa essa convenção).
Validação de opções
A validação de opções permite validar as opções depois de configurá-las. Chame Validate com um método de
validação que retorna true quando as opções são válidas, e false quando não são:
// Registration
services.AddOptions<MyOptions>("optionalOptionsName")
.Configure(o => { }) // Configure the options
.Validate(o => YourValidationShouldReturnTrueIfValid(o),
"custom error");
// Consumption
var monitor = services.BuildServiceProvider()
.GetService<IOptionsMonitor<MyOptions>>();
try
{
var options = monitor.Get("optionalOptionsName");
}
catch (OptionsValidationException e)
{
// e.OptionsName returns "optionalOptionsName"
// e.OptionsType returns typeof(MyOptions)
// e.Failures returns a list of errors, which would contain
// "custom error"
}
O exemplo anterior define a instância de opções nomeadas como optionalOptionsName . A instância de opções
padrão é Options.DefaultName .
A validação é executada após a criação da instância de opções. A instância de opções tem garantia de passar
pela validação, na primeira vez em que for acessada.
IMPORTANT
A validação não protege contra modificações de opções, depois que as opções são inicialmente configuradas e validadas.
O método Validateaceita um Func<TOptions, bool> . Para personalizar totalmente a validação, implemente

IValidateOptions<TOptions> , que permite:
A validação de vários tipos de opções:

class ValidateTwo : IValidateOptions<Option1>, IValidationOptions<Option2>
A validação que depende de outro tipo de opção:
public DependsOnAnotherOptionValidator(IOptions<AnotherOption> options)
IValidateOptions valida:
Uma instância específica de opções nomeadas.
Todas as opções quando name for null .
Retornar um ValidateOptionsResult da implementação da interface:
public interface IValidateOptions<TOptions> where TOptions : class

{
ValidateOptionsResult Validate(string name, TOptions options);
}
A validação adiantada (fail fast na inicialização) e a validação de dados baseada em anotação estão agendadas
para um lançamento futuro.
IPostConfigureOptions
Defina a pós-configuração com IPostConfigureOptions<TOptions>. A pós-configuração é executada depois
que ocorre toda a configuração de IConfigureOptions<TOptions>:
services.PostConfigure<MyOptions>(myOptions =>
{
myOptions.Option1 = "post_configured_option1_value";
});
PostConfigure<TOptions> está disponível para pós-configurar opções nomeadas:
services.PostConfigure<MyOptions>("named_options_1", myOptions =>

{
});
Use PostConfigureAll<TOptions> para pós-configurar todas as instâncias de configuração:
services.PostConfigureAll<MyOptions>(myOptions =>
{
});
Alocador de opções, monitoramento e cache

IOptionsMonitor é usado para notificações quando instâncias TOptions são alteradas. IOptionsMonitor dá
suporte a opções recarregáveis, notificações de alteração e IPostConfigureOptions .
IOptionsFactory<TOptions> é responsável por criar novas instâncias de opção. Ele tem um único método
Create. A implementação padrão usa todos os IConfigureOptions e IPostConfigureOptions registrados e
executa toda a configuração primeiro, seguido da pós-configuração. Ela faz distinção entre
IConfigureNamedOptions e IConfigureOptions e chama apenas a interface apropriada.
IOptionsMonitorCache<TOptions> é usado por IOptionsMonitor para armazenar instâncias TOptions em

cache. O IOptionsMonitorCache invalida as instâncias de opções no monitor, de modo que o valor seja
recalculado (TryRemove). Os valores também podem ser manualmente inseridos com TryAdd. O método Clear
é usado quando todas as instâncias nomeadas devem ser recriadas sob demanda.
Acessando opções durante a inicialização

IOptions pode ser usado em Startup.Configure , pois os serviços são criados antes da execução do método
Configure .
public void Configure(IApplicationBuilder app, IOptions<MyOptions> optionsAccessor)

{
var option1 = optionsAccessor.Value.Option1;
}
IOptions não deve ser usado em Startup.ConfigureServices . Pode haver um estado inconsistente de opções
devido à ordenação dos registros de serviço.
Recursos adicionais
Registro em log no ASP.NET Core
Por Steve Smith e Tom Dykstra

O ASP.NET Core oferece suporte a uma API de registro em log que funciona com uma variedade de
provedores de logs internos e terceirizados. Este artigo mostra como usar a API de registro em log com
provedores internos.
Adicionar provedores
Um provedor de log exibe ou armazena logs. Por exemplo, o provedor de Console exibe os logs no console, e
o provedor do Azure Application Insights armazena-os no Azure Application Insights. Os logs podem ser
enviados para vários destinos por meio da adição de vários provedores.
Para adicionar um provedor, chame o método de extensão Add{provider name} do provedor no Program.cs:

{
var webHost = new WebHostBuilder()
.UseKestrel()
{
var env = hostingContext.HostingEnvironment;
config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
.AddJsonFile($"appsettings.{env.EnvironmentName}.json",
optional: true, reloadOnChange: true);
config.AddEnvironmentVariables();
})
.ConfigureLogging((hostingContext, logging) =>
{
logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
logging.AddConsole();
logging.AddDebug();
logging.AddEventSourceLogger();
})
.Build();
webHost.Run();
}
O modelo de projeto padrão chama o método de extensão CreateDefaultBuilder, que adiciona os seguintes
provedores de log:
Console
Depurar
EventSource (a partir do ASP.NET Core 2.2)
{
BuildWebHost(args).Run();
}
public static IWebHost BuildWebHost(string[] args) =>

.Build();
Se você usar CreateDefaultBuilder , poderá substituir os provedores padrão por aqueles que preferir. Chame
ClearProviders e adicione os provedores desejados.

{
var host = BuildWebHost(args);
var todoRepository = host.Services.GetRequiredService<ITodoRepository>();

todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });
var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("Seeded the database.");
host.Run();
}

.ConfigureLogging(logging =>
{
logging.ClearProviders();
})
.Build();
Para usar um provedor, instale o pacote NuGet e chame o método de extensão do provedor em uma instância
de ILoggerFactory:
public void Configure(IApplicationBuilder app,

IHostingEnvironment env,
{
loggerFactory
.AddConsole()
.AddDebug();
A DI (injeção de dependência) do ASP.NET Core fornece a instância de ILoggerFactory . Os métodos de

extensão AddConsole e AddDebug são definidos nos pacotes Microsoft.Extensions.Logging.Console e
Microsoft.Extensions.Logging.Debug. Cada método de extensão chama o método
ILoggerFactory.AddProvider , passando uma instância do provedor.
NOTE
O aplicativo de exemplo adiciona provedores de log no método Startup.Configure . Para obter saída de log do
código que é executado anteriormente, adicione provedores de log no construtor de classe Startup .
Saiba mais sobre provedores de log internos e provedores de log de terceiros mais adiante no artigo.
Criar logs
Obtenha um objeto ILogger<TCategoryName> da DI.
O exemplo de controlador a seguir cria os logs Information e Warning . A categoria é
TodoApiSample.Controllers.TodoController (o nome de classe totalmente qualificado do TodoController no
aplicativo de exemplo):
public class TodoController : Controller

{
private readonly ITodoRepository _todoRepository;
private readonly ILogger _logger;
public TodoController(ITodoRepository todoRepository,

ILogger<TodoController> logger)
{
_todoRepository = todoRepository;
_logger = logger;
}
public IActionResult GetById(string id)

{
_logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
var item = _todoRepository.Find(id);
if (item == null)
{
_logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
return new ObjectResult(item);
}
O exemplo do Razor Pages a seguir cria logs com Information como o nível e
TodoApiSample.Pages.AboutModel como a categoria:
public class AboutModel : PageModel

{
public AboutModel(ILogger<AboutModel> logger)

{
_logger = logger;
}
public void OnGet()

{
Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
_logger.LogInformation("Message displayed: {Message}", Message);
}
{

{
_logger = logger;
}

{
if (item == null)
{
return NotFound();
}
}
O exemplo acima cria logs com Information e Warning como o nível e a classe TodoController como a
categoria.
O nível de log indica a gravidade do evento registrado. A categoria do log é uma cadeia de caracteres
associada a cada log. A instância ILogger<T> cria logs que têm o nome totalmente qualificado do tipo T
como a categoria. Níveis e categorias serão explicados com mais detalhes posteriormente neste artigo.
Criar logs na inicialização
Para gravar logs na classe Startup , inclua um parâmetro ILogger na assinatura de construtor:
{
public Startup(IConfiguration configuration, ILogger<Startup> logger)

{
_logger = logger;
}

{
services.AddMvc();
// Add our repository type

services.AddSingleton<ITodoRepository, TodoRepository>();
_logger.LogInformation("Added TodoRepository to services");
}

{
{
_logger.LogInformation("In Development environment");
}
else
{
app.UseHsts();
}
app.UseMvc();
}
}
Criar logs no programa

Para gravar logs na classe Program , obtenha uma instância ILogger da DI:
{
var todoRepository = host.Services.GetRequiredService<ITodoRepository>();

todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });
var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("Seeded the database.");
host.Run();
}

{
logging.ClearProviders();
})
.Build();
Sem métodos de agente assíncronos

O registro em log deve ser tão rápido que não justifique o custo de desempenho de código assíncrono. Se o
armazenamento de dados em log estiver lento, não grave diretamente nele. Grave as mensagens de log em
um repositório rápido primeiro e, depois, mova-as para um repositório lento. Por exemplo, registre em uma
fila de mensagens que seja lida e persistida em um armazenamento lento por outro processo.
Configuração
A configuração do provedor de logs é fornecida por um ou mais provedores de sincronização:
Formatos de arquivo (INI, JSON e XML ).
Objetos do .NET na memória.
O armazenamento do Secret Manager não criptografado.
Um repositório de usuário criptografado, como o Azure Key Vault.
Provedores personalizados (instalados ou criados).
Por exemplo, a configuração de log geralmente é fornecida pela seção Logging dos arquivos de
configurações do aplicativo. O exemplo a seguir mostra o conteúdo de um típico arquivo
appsettings.Development.json:
{
"Logging": {
"LogLevel": {
"Default": "Debug",
"System": "Information",
"Microsoft": "Information"
},
"Console":
{
"IncludeScopes": true
}
}
}
A propriedade Logging pode ter LogLevel e propriedades do provedor de logs (o Console é mostrado).
A propriedade LogLevel em Logging especifica o nível mínimo para log nas categorias selecionadas. No
exemplo, as categorias System e Microsoft têm log no nível Information , e todas as outras no nível Debug .
Outras propriedades em Logging especificam provedores de logs. O exemplo se refere ao provedor de
Console. Se um provedor oferecer suporte a escopos de log, IncludeScopes indicará se eles estão habilitados.
Uma propriedade de provedor (como Console , no exemplo) também pode especificar uma propriedade
LogLevel . LogLevel em um provedor especifica os níveis de log para esse provedor.
Se os níveis forem especificados em Logging.{providername}.LogLevel , eles substituirão o que estiver definido

em Logging.LogLevel .
{
"Logging": {
"LogLevel": {
"Default": "Debug",
}
}
}
Chaves LogLevel representam nomes de log. A chave Default aplica-se a logs não listados de forma
explícita. O valor representa o nível de log aplicado ao log fornecido.
Saiba mais sobre como implementar provedores de configuração em Configuração no ASP.NET Core.
Exemplo de saída de registro em log

Com o código de exemplo mostrado na seção anterior, os logs serão exibidos no console quando o aplicativo
for executado pela linha de comando. Aqui está um exemplo da saída do console:
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) -
ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
Executing HttpStatusCodeResult, setting HTTP status code 404
Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 42.9286ms
Request finished in 148.889ms 404
Os logs anteriores foram gerados por meio de uma solicitação HTTP Get para o aplicativo de exemplo em
http://localhost:5000/api/todo/0 .
Veja um exemplo de como os mesmos logs aparecem na janela Depuração quando você executa o aplicativo
de exemplo no Visual Studio:
Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request starting HTTP/1.1 GET

http://localhost:53104/api/todo/0
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executing action method
TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
TodoApi.Controllers.TodoController:Information: Getting item 0
TodoApi.Controllers.TodoController:Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult:Information: Executing HttpStatusCodeResult, setting HTTP
status code 404
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executed action
TodoApi.Controllers.TodoController.GetById (TodoApi) in 152.5657ms
Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request finished in 316.3195ms 404
Os logs criados pelas chamadas ILogger mostradas na seção anterior começam com
"TodoApi.Controllers.TodoController". Os logs que começam com categorias "Microsoft" são de código da
estrutura ASP.NET Core. O ASP.NET Core e o código do aplicativo estão usando a mesma API de registro
em log e os mesmos provedores.
O restante deste artigo explica alguns detalhes e opções para registro em log.
Pacotes NuGet
As interfaces ILogger e ILoggerFactory estão em Microsoft.Extensions.Logging.Abstractions e as
implementações padrão para elas estão em Microsoft.Extensions.Logging.
Categoria de log
Quando um objeto ILogger é criado, uma categoria é especificada para ele. Essa categoria é incluída em
cada mensagem de log criada por essa instância de Ilogger . A categoria pode ser qualquer cadeia de
caracteres, mas a convenção é usar o nome da classe, como "TodoApi.Controllers.TodoController".
Use ILogger<T> para obter uma instância ILogger que usa o nome de tipo totalmente qualificado do T
como a categoria:
{

{
_logger = logger;
}

{

{
_logger = logger;
}
Para especificar explicitamente a categoria, chame ILoggerFactory.CreateLogger :

{

ILoggerFactory logger)
{
_logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
}

{

ILoggerFactory logger)
{
_logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
}
ILogger<T> é equivalente a chamar CreateLogger com o nome de tipo totalmente qualificado de T .
Nível de log
Todo log especifica um valor LogLevel. O nível de log indica a gravidade ou importância. Por exemplo, você
pode gravar um log Information quando um método é finalizado normalmente e um log Warning quando
um método retorna um código de status 404 Não Encontrado.
O código a seguir cria os logs Information e Warning :
{
if (item == null)
{
return NotFound();
}
}

{
if (item == null)
{
return NotFound();
}
}
No código anterior, o primeiro parâmetro é a ID de evento de log. O segundo parâmetro é um modelo de

mensagem com espaços reservados para valores de argumento fornecidos pelos parâmetros de método
restantes. Os parâmetros de método serão explicados com posteriormente neste artigo, na seção de modelos
de mensagem.
Os métodos de log que incluem o nível no nome do método (por exemplo, LogInformation e LogWarning )
são métodos de extensão para ILogger. Esses métodos chamam um método Log que recebe um parâmetro
LogLevel . Você pode chamar o método Log diretamente em vez de um desses métodos de extensão, mas a
sintaxe é relativamente complicada. Para saber mais, veja ILogger e o código-fonte de extensões de agente.
O ASP.NET Core define os seguintes níveis de log, ordenados aqui da menor para a maior gravidade.
Trace = 0
Para obter informações que normalmente são valiosas somente para depuração. Essas mensagens
podem conter dados confidenciais de aplicativos e, portanto, não devem ser habilitadas em um
ambiente de produção. Desabilitado por padrão.
Debug = 1
Para obter informações que possam ser úteis durante o desenvolvimento e a depuração. Exemplo:
Entering method Configure with flag set to true. habilite logs de nível Debug em produção somente
ao solucionar problemas, devido ao alto volume de logs.
Information = 2
Para rastrear o fluxo geral do aplicativo. Esses logs normalmente têm algum valor a longo prazo.
Exemplo: Request received for path /api/todo
Warning = 3
Para eventos anormais ou inesperados no fluxo de aplicativo. Eles podem incluir erros ou outras
condições que não fazem com que o aplicativo pare, mas que talvez precisem ser investigados.
Exceções manipuladas são um local comum para usar o nível de log Warning . Exemplo:
FileNotFoundException for file quotes.txt.
Error = 4
Para erros e exceções que não podem ser manipulados. Essas mensagens indicam uma falha na
atividade ou na operação atual (como a solicitação HTTP atual) e não uma falha em todo o aplicativo.
Mensagem de log de exemplo: Cannot insert record due to duplicate key violation.
Critical = 5
Para falhas que exigem atenção imediata. Exemplos: cenários de perda de dados, espaço em disco
insuficiente.
Use o nível de log para controlar a quantidade de saída de log que é gravada em uma mídia de
armazenamento específica ou em uma janela de exibição. Por exemplo:
Em produção, envie Trace por meio do nível Information para um armazenamento de dados com
volume. Envie Warning por meio de Critical para um armazenamento de dados com valor.
Durante o desenvolvimento, envie Warning por meio Critical para o console e adicione Trace por meio
de Information ao solucionar problemas.
A seção Filtragem de log mais adiante neste artigo explicará como controlar os níveis de log que um
provedor manipula.
O ASP.NET Core grava logs para eventos de estrutura. Os exemplos de log anteriores neste artigo excluíram
logs abaixo do nível Information , portanto, logs de nível Debug ou Trace não foram criados. Veja um
exemplo de logs de console produzidos por meio da execução do aplicativo de exemplo configurado para
mostrar logs Debug :
Request starting HTTP/1.1 GET http://localhost:62555/api/todo/0
dbug: Microsoft.AspNetCore.Routing.Tree.TreeRouter[1]
Request successfully matched the route with name 'GetTodo' and template 'api/Todo/{id}'.
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
Action 'TodoApi.Controllers.TodoController.Update (TodoApi)' with id '089d59b6-92ec-472d-b552-
cc613dfd625d' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
Action 'TodoApi.Controllers.TodoController.Delete (TodoApi)' with id 'f3476abe-4bd9-4ad3-9261-
3ead09607366' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
Executing action TodoApi.Controllers.TodoController.GetById (TodoApi)
Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) -
ModelState is Valid
Getting item 0
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
Executed action method TodoApi.Controllers.TodoController.GetById (TodoApi), returned result
Microsoft.AspNetCore.Mvc.NotFoundResult.
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
Executing HttpStatusCodeResult, setting HTTP status code 404
Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 0.8788ms
dbug: Microsoft.AspNetCore.Server.Kestrel[9]
Connection id "0HL6L7NEFF2QD" completed keep alive response.
Request finished in 2.7286ms 404
ID de evento de log
Cada log pode especificar uma ID do evento. O aplicativo de exemplo faz isso usando uma classe
LoggingEvents definida localmente:

{
if (item == null)
{
return NotFound();
}
}
public class LoggingEvents

{
public const int GenerateItems = 1000;
public const int ListItems = 1001;
public const int GetItem = 1002;
public const int InsertItem = 1003;
public const int UpdateItem = 1004;
public const int DeleteItem = 1005;
public const int GetItemNotFound = 4000;

public const int UpdateItemNotFound = 4001;
}

{
if (item == null)
{
return NotFound();
}
}
public class LoggingEvents

{
public const int GenerateItems = 1000;
public const int ListItems = 1001;
public const int GetItem = 1002;
public const int InsertItem = 1003;
public const int UpdateItem = 1004;
public const int DeleteItem = 1005;
public const int GetItemNotFound = 4000;

public const int UpdateItemNotFound = 4001;
}
Uma ID de evento associa um conjunto de eventos. Por exemplo, todos os logs relacionados à exibição de
uma lista de itens em uma página podem ser 1001.
O provedor de logs pode armazenar a ID do evento em um campo de ID na mensagem de log ou não
armazenar. O provedor de Depuração não mostra IDs de eventos. O provedor de console mostra IDs de
evento entre colchetes após a categoria:
Getting item invalidid
GetById(invalidid) NOT FOUND
Modelo de mensagem de log

Cada log especifica um modelo de mensagem. O modelo de mensagem pode conter espaços reservados para
os quais são fornecidos argumentos. Use nomes para os espaços reservados, não números.

{
if (item == null)
{
return NotFound();
}
}

{
if (item == null)
{
return NotFound();
}
}
A ordem dos espaços reservados e não de seus nomes, determina quais parâmetros serão usados para
fornecer seus valores. No código a seguir, observe que os nomes de parâmetro estão fora de sequência no
modelo de mensagem:
string p1 = "parm1";
string p2 = "parm2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);
Esse código cria uma mensagem de log com os valores de parâmetro na sequência:
Parameter values: parm1, parm2
A estrutura de registros funciona dessa maneira para que os provedores de logs possam implementar
registro em log semântico, também conhecido como registro em log estruturado. Os próprios argumentos
são passados para o sistema de registro em log, não apenas o modelo de mensagem formatado. Essas
informações permitem que os provedores de log armazenem os valores de parâmetro como campos. Por
exemplo, suponha que as chamadas de método do agente sejam assim:
_logger.LogInformation("Getting item {ID} at {RequestTime}", id, DateTime.Now);

Se você estiver enviando os logs para o Armazenamento de Tabelas do Azure, cada entidade da Tabela do
Azure poderá ter propriedades ID e RequestTime , o que simplificará as consultas nos dados de log. Uma
consulta pode encontrar todos os logs em determinado intervalo de RequestTime sem analisar o tempo limite
da mensagem de texto.
Exceções de registro em log

Os métodos de agente têm sobrecargas que permitem que você passe uma exceção, como no exemplo a
seguir:

{
_logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({ID}) NOT FOUND", id);
return NotFound();
}

{
_logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
Provedores diferentes manipulam as informações de exceção de maneiras diferentes. Aqui está um exemplo
da saída do provedor Depuração do código mostrado acima.
TodoApi.Controllers.TodoController:Warning: GetById(036dd898-fb01-47e8-9a65-f92eb73cf924) NOT FOUND
System.Exception: Item not found exception.

at TodoApi.Controllers.TodoController.GetById(String id) in
C:\logging\sample\src\TodoApi\Controllers\TodoController.cs:line 226
Filtragem de log
Você pode especificar um nível de log mínimo para um provedor e uma categoria específicos ou para todos
os provedores ou todas as categorias. Os logs abaixo do nível mínimo não serão passados para esse
provedor, para que não sejam exibidos ou armazenados.
Para suprimir todos os logs, especifique LogLevel.None como o nível de log mínimo. O valor inteiro de
LogLevel.None é 6, que é maior do que LogLevel.Critical (5 ).
Criar regras de filtro na configuração

O código do modelo de projeto chama CreateDefaultBuilder para configurar o registro em log para os
provedores Console e Depuração. O método CreateDefaultBuilder também configura o registro em log para
procurar a configuração em uma seção Logging , usando código semelhante ao seguinte:
{
var webHost = new WebHostBuilder()
.UseKestrel()
{
var env = hostingContext.HostingEnvironment;
.AddJsonFile($"appsettings.{env.EnvironmentName}.json",
optional: true, reloadOnChange: true);
config.AddEnvironmentVariables();
})
{
logging.AddDebug();
})
.Build();
webHost.Run();
}
Os dados de configuração especificam níveis de log mínimo por provedor e por categoria, como no exemplo
a seguir:
{
"Logging": {
"Debug": {
"LogLevel": {
"Default": "Information"
}
},
"Console": {
"IncludeScopes": false,
"LogLevel": {
"Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
"Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
"Microsoft.AspNetCore.Mvc.Razor": "Error",
"Default": "Information"
}
},
"LogLevel": {
"Default": "Debug"
}
}
}
Este JSON cria seis regras de filtro, uma para o provedor Depuração, quatro para o provedor Console e uma
para todos os provedores. Apenas uma regra é escolhida para cada provedor quando um objeto ILogger é
criado.
Regras de filtro no código
O exemplo a seguir mostra como registrar regras de filtro no código:
logging.AddFilter("System", LogLevel.Debug)
.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace))
.Build();
O segundo AddFilter especifica o provedor Depuração usando seu nome de tipo. O primeiro AddFilter se
aplica a todos os provedores porque ele não especifica um tipo de provedor.
Como as regras de filtragem são aplicadas
Os dados de configuração e o código AddFilter , mostrados nos exemplos anteriores, criam as regras
mostradas na tabela a seguir. As primeiras seis vêm do exemplo de configuração e as últimas duas vêm do
exemplo de código.
CATEGORIAS QUE COMEÇAM

NÚMERO PROVIDER COM... NÍVEL DE LOG MÍNIMO
1 Depurar Todas as categorias Informações
2 Console Microsoft.AspNetCore.Mvc. Aviso

Razor.Internal
3 Console Microsoft.AspNetCore.Mvc. Depurar

Razor.Razor
4 Console Microsoft.AspNetCore.Mvc. Erro

Razor
5 Console Todas as categorias Informações
6 Todos os provedores Todas as categorias Depurar
7 Todos os provedores Sistema Depurar
8 Depurar Microsoft Rastrear
Quando um objeto ILogger é criado, o objeto ILoggerFactory seleciona uma única regra por provedor para
aplicar a esse agente. Todas as mensagens gravadas pela instância ILogger são filtradas com base nas regras
selecionadas. A regra mais específica possível para cada par de categoria e provedor é selecionada dentre as
regras disponíveis.
O algoritmo a seguir é usado para cada provedor quando um ILogger é criado para uma determinada
categoria:
Selecione todas as regras que correspondem ao provedor ou seu alias. Se nenhuma correspondência for
encontrada, selecione todas as regras com um provedor vazio.
Do resultado da etapa anterior, selecione as regras com o prefixo de categoria de maior correspondência.
Se nenhuma correspondência for encontrada, selecione todas as regras que não especificam uma
categoria.
Se várias regras forem selecionadas, use a última.
Se nenhuma regra for selecionada, use MinimumLevel .
Com a lista anterior de regras, suponha que você crie um objeto ILogger para a categoria
"Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":
Para o provedor Depuração as regras 1, 6 e 8 se aplicam. A regra 8 é mais específica, portanto é a que será
selecionada.
Para o provedor Console as regras 3, 4, 5 e 6 se aplicam. A regra 3 é a mais específica.
A instância ILogger resultante envia logs de nível Trace e superior para o provedor Depuração. Logs de
nível Debug e superior são enviados para o provedor Console.
Aliases de provedor
Cada provedor define um alias que pode ser usado na configuração no lugar do nome de tipo totalmente
qualificado. Para os provedores internos, use os seguintes aliases:
Console
Depurar
EventLog
AzureAppServices
TraceSource
EventSource
Nível mínimo padrão
Há uma configuração de nível mínimo que entra em vigor somente se nenhuma regra de código ou de
configuração se aplicar a um provedor e uma categoria determinados. O exemplo a seguir mostra como
definir o nível mínimo:
.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
.Build();
Se você não definir explicitamente o nível mínimo, o valor padrão será Information , o que significa que logs
Trace e Debug serão ignorados.
Funções de filtro
Uma função de filtro é invocada para todos os provedores e categorias que não têm regras atribuídas a eles
por configuração ou código. O código na função tem acesso ao tipo de provedor, à categoria e ao nível de log.
Por exemplo:
.ConfigureLogging(logBuilder =>
{
logBuilder.AddFilter((provider, category, logLevel) =>
{
if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
category == "TodoApiSample.Controllers.TodoController")
{
return false;
}
return true;
});
})
.Build();
Alguns provedores de log permitem especificar quando os logs devem ser gravados em uma mídia de
armazenamento ou ignorados, com base no nível de log e na categoria.
Os métodos de extensão AddConsole e AddDebug fornecem sobrecargas que aceitam critérios de filtragem. O
código de exemplo a seguir faz com que o provedor de console ignore os logs abaixo do nível Warning ,
enquanto o provedor Depuração ignora os logs criados pela estrutura.

{
loggerFactory
.AddConsole(LogLevel.Warning)
.AddDebug((category, logLevel) => (category.Contains("TodoApi") && logLevel >= LogLevel.Trace));
O método AddEventLog tem uma sobrecarga que recebe uma instância EventLogSettings , que pode conter
uma função de filtragem em sua propriedade Filter . O provedor TraceSource não fornece nenhuma dessas
sobrecargas, porque seu nível de registro em log e outros parâmetros são baseados no SourceSwitch e no
TraceListener que ele usa.
Para definir regras de filtragem para todos os provedores registrados com uma instância ILoggerFactory , use
o método de extensão WithFilter . O exemplo abaixo limita os logs de estrutura (categoria começa com
"Microsoft" ou "Sistema") a avisos, enquanto registra em nível de depuração os logs criados por código de
aplicativo.

{
loggerFactory
.WithFilter(new FilterLoggerSettings
{
{ "Microsoft", LogLevel.Warning },
{ "System", LogLevel.Warning },
{ "ToDoApi", LogLevel.Debug }
})
.AddConsole()
.AddDebug();
Para impedir a gravação de logs, especifique LogLevel.None como o nível de log mínimo. O valor inteiro de
LogLevel.None é 6, que é maior do que LogLevel.Critical (5 ).
O método de extensão WithFilter é fornecido pelo pacote NuGet Microsoft.Extensions.Logging.Filter. O

método retorna um nova instância ILoggerFactory , que filtrará as mensagens de log passadas para todos os
provedores de agente registrados com ela. Isso não afeta nenhuma outra instância de ILoggerFactory ,
incluindo a instância de ILoggerFactory original.
Categorias e níveis de sistema

Veja algumas categorias usadas pelo ASP.NET Core e Entity Framework Core, com anotações sobre quais
logs esperar delas:
CATEGORIA OBSERVAÇÕES
Microsoft.AspNetCore Diagnóstico geral de ASP.NET Core.
Microsoft.AspNetCore.DataProtection Quais chaves foram consideradas, encontradas e usadas.
Microsoft.AspNetCore.HostFiltering Hosts permitidos.

CATEGORIA OBSERVAÇÕES
Microsoft.AspNetCore.Hosting Quanto tempo levou para que as solicitações de HTTP

fossem concluídas e em que horário foram iniciadas. Quais
assemblies de inicialização de hospedagem foram
carregados.
Microsoft.AspNetCore.Mvc Diagnóstico do MVC e Razor. Model binding, execução de

filtro, compilação de exibição, seleção de ação.
Microsoft.AspNetCore.Routing Informações de correspondência de rotas.
Microsoft.AspNetCore.Server Respostas de início, parada e atividade da conexão.

Informações sobre o certificado HTTPS.
Microsoft.AspNetCore.StaticFiles Arquivos atendidos.
Microsoft.EntityFrameworkCore Diagnóstico geral do Entity Framework Core. Atividade e

configuração do banco de dados, detecção de alterações,
migrações.
Escopos de log
Um escopo pode agrupar um conjunto de operações lógicas. Esse agrupamento pode ser usado para anexar
os mesmos dados para cada log criado como parte de um conjunto. Por exemplo, todo log criado como parte
do processamento de uma transação pode incluir a ID da transação.
Um escopo é um tipo IDisposable retornado pelo método BeginScope e que dura até que seja descartado.
Use um escopo por meio do encapsulamento de chamadas de agente em um bloco using :

{
TodoItem item;
using (_logger.BeginScope("Message attached to logs created in the using block"))
{
item = _todoRepository.Find(id);
if (item == null)
{
return NotFound();
}
}
}
O código a seguir habilita os escopos para o provedor de console:

Program.cs:

{
logging.AddConsole(options => options.IncludeScopes = true);
logging.AddDebug();
})
NOTE
A configuração da opção de agente de console IncludeScopes é necessária para habilitar o registro em log baseado
em escopo.
Saiba mais sobre como configurar na seção Configuração.
Program.cs:

{
logging.AddConsole(options => options.IncludeScopes = true);
logging.AddDebug();
})
NOTE
A configuração da opção de agente de console IncludeScopes é necessária para habilitar o registro em log baseado
em escopo.
Startup.cs:

{
loggerFactory
.AddConsole(includeScopes: true)
.AddDebug();
Cada mensagem de log inclui as informações com escopo definido:
=> RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApi.Controllers.TodoController.GetById
(TodoApi) => Message attached to logs created in the using block
Getting item 0
=> RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApi.Controllers.TodoController.GetById
(TodoApi) => Message attached to logs created in the using block
Provedores de log internos

O ASP.NET Core vem com os seguintes provedores:
Console
Depurar
EventSource
EventLog
TraceSource
As opções de Registro em log no Azure serão abordadas mais adiante, neste artigo.
Para saber mais sobre log de stdout, confira Solucionar problemas do ASP.NET Core no IIS e Solucionar
erros de inicialização do ASP.NET Core no Serviço de Aplicativo do Azure.
Provedor do console
O pacote de provedor Microsoft.Extensions.Logging.Console envia a saída de log para o console.
loggerFactory.AddConsole();
As sobrecargas do AddConsole permitem que você passe um nível de log mínimo, uma função de filtro e um
valor booliano que indica se escopos são compatíveis. Outra opção é passar um objeto IConfiguration , que
pode especificar suporte de escopos e níveis de log.
O provedor de console tem um impacto significativo no desempenho e geralmente não é adequado para uso
em produção.
Quando você cria um novo projeto no Visual Studio, o método AddConsole tem essa aparência:
loggerFactory.AddConsole(Configuration.GetSection("Logging"));
Esse código se refere à seção Logging do arquivo appSettings.json:
{
"Logging": {
"Console": {
"IncludeScopes": false
},
"LogLevel": {
"Default": "Debug",
}
}
}
As configurações mostradas limitam os logs de estrutura a avisos, permitindo que o aplicativo para faça
registros no nível de depuração, conforme explicado na Filtragem de log seção. Para obter mais informações,
consulte Configuração.
Para ver a saída de registro em log de console, abra um prompt de comando na pasta do projeto e execute o
seguinte comando:
dotnet run
Depurar provedor
O pacote de provedor Microsoft.Extensions.Logging.Debug grava a saída de log usando a classe
System.Diagnostics.Debug (chamadas de método Debug.WriteLine ).
No Linux, esse provedor grava logs em /var/log/message.
logging.AddDebug();
loggerFactory.AddDebug();
As sobrecargas de AddDebug permitem que você passe um nível de log mínimo ou uma função de filtro.
Provedor EventSource
Para aplicativos que se destinam ao ASP.NET Core 1.1.0 ou posterior, o pacote de provedor
Microsoft.Extensions.Logging.EventSource pode implementar o rastreamento de eventos. No Windows, ele
usa ETW. O provedor é multiplataforma, mas ainda não há ferramentas de coleta e exibição de eventos para
Linux ou macOS.
loggerFactory.AddEventSourceLogger();
Uma boa maneira de coletar e exibir logs é usar o utilitário PerfView. Há outras ferramentas para exibir os
logs do ETW, mas o PerfView proporciona a melhor experiência para trabalhar com os eventos de ETW
emitidos pelo ASP.NET.
Para configurar o PerfView para coletar eventos registrados por esse provedor, adicione a cadeia de
caracteres *Microsoft-Extensions-Logging à lista Provedores Adicionais. (Não se esqueça do asterisco no
início da cadeia de caracteres).
Provedor EventLog do Windows

O pacote de provedor Microsoft.Extensions.Logging.EventLog envia a saída de log para o Log de Eventos do
Windows.
logging.AddEventLog();
loggerFactory.AddEventLog();
As sobrecargas de AddEventLog permitem que você passe EventLogSettings ou um nível de log mínimo.
Provedor TraceSource
O pacote de provedor Microsoft.Extensions.Logging.TraceSource usa as bibliotecas e provedores de
TraceSource.
logging.AddTraceSource(sourceSwitchName);
loggerFactory.AddTraceSource(sourceSwitchName);
As sobrecargas de AddTraceSource permitem que você passe um comutador de fonte e um ouvinte de

rastreamento.
Para usar esse provedor, o aplicativo deve ser executado no .NET Framework (em vez do .NET Core). O
provedor pode rotear mensagens a uma variedade de ouvintes, como o TextWriterTraceListener usado no
aplicativo de exemplo.
O exemplo a seguir configura um provedor TraceSource que registra mensagens Warning e superiores na
janela de console.

{
loggerFactory
.AddDebug();
// add Trace Source logging

var testSwitch = new SourceSwitch("sourceSwitch", "Logging Sample");
testSwitch.Level = SourceLevels.Warning;
loggerFactory.AddTraceSource(testSwitch,
new TextWriterTraceListener(writer: Console.Out));
Registro em log no Azure

Para saber mais sobre registro em log no Azure, consulte as seguintes seções:
Provedor do Serviço de Aplicativo do Azure
Fluxo de log do Azure
Log de rastreamento do Azure Application Insights
Provedor do Serviço de Aplicativo do Azure
O pacote de provedor Microsoft.Extensions.Logging.AzureAppServices grava logs em arquivos de texto no
sistema de arquivos de um aplicativo do Serviço de Aplicativo do Azure e no armazenamento de blobs em
uma conta de Armazenamento do Azure. O pacote de provedor está disponível para aplicativos destinados ao
.NET Core 1.1 ou posterior.
Se você estiver direcionando para o .NET Core, observe os seguintes pontos:
O pacote de provedor está incluído no metapacote Microsoft.AspNetCore.All do ASP.NET Core.
O pacote de provedor não está incluído no metapacote Microsoft.AspNetCore.App. Para usar o provedor,
instale o pacote.
Não chame explicitamente AddAzureWebAppDiagnostics. Quando o aplicativo for implantado no Serviço
de Aplicativo do Azure, o provedor ficará automaticamente disponível para ele.
Se você estiver direcionando para o .NET Framework ou referenciando o metapacote
Microsoft.AspNetCore.App , adicione o pacote do provedor ao projeto. Invoque AddAzureWebAppDiagnostics em
uma instância ILoggerFactory:
logging.AddAzureWebAppDiagnostics();
loggerFactory.AddAzureWebAppDiagnostics();
Uma sobrecarga AddAzureWebAppDiagnostics permite passar AzureAppServicesDiagnosticsSettings. O

objeto settings pode substituir as configurações padrão, como o modelo de saída de registro em log, o nome
do blob e o limite do tamanho do arquivo. (O modelo Output é um modelo de mensagem aplicado a todos os
logs, além daquele fornecido com uma chamada ao método ILogger ).
Ao implantar um aplicativo do Serviço de Aplicativo, o aplicativo respeita as configurações na seção Logs de
Diagnóstico da página Serviço de Aplicativo do portal do Azure. Quando essas configurações são
atualizadas, as alterações entram em vigor imediatamente sem a necessidade de uma reinicialização ou
reimplantação do aplicativo.
O local padrão para arquivos de log é na pasta D:\home\LogFiles\Application e o nome de arquivo padrão é
diagnostics-aaaammdd.txt. O limite padrão de tamanho do arquivo é 10 MB e o número padrão máximo de
arquivos mantidos é 2. O nome de blob padrão é {app -name}{timestamp }/aaaa/mm/dd/hh/{guid }-
applicationLog.txt. Para saber mais sobre o comportamento padrão, confira
AzureAppServicesDiagnosticsSettings.
O provedor funciona somente quando o projeto é executado no ambiente do Azure. Ele não tem nenhum
efeito quando o projeto é executado localmente—ele não grava em arquivos locais ou no armazenamento de
desenvolvimento local para blobs.
Fluxo de log do Azure
O fluxo de log do Azure permite que você exiba a atividade de log em tempo real:
O servidor de aplicativos
Do servidor Web
De uma solicitação de rastreio com falha
Para configurar o fluxo de log do Azure:
Navegue até a página Logs de Diagnóstico da página do portal do seu aplicativo.
Defina o Log de aplicativo (Sistema de Arquivos) como Ativado.
Navegue até a página Fluxo de Log para exibir as mensagens de aplicativo. Elas são registradas pelo
aplicativo por meio da interface ILogger .
Log de rastreamento do Azure Application Insights
O SDK do Application Insights pode coletar e relatar logs gerados por meio da infraestrutura de log do
ASP.NET Core. Para obter mais informações, consulte os seguintes recursos:
Visão geral do Application Insights
Application Insights para ASP.NET Core
Wiki do Microsoft/ApplicationInsights-aspnetcore: Log.
Provedores de log de terceiros

Estruturas de log de terceiros que funcionam com o ASP.NET Core:
elmah.io (repositório GitHub)
Gelf (repositório do GitHub)
JSNLog (repositório GitHub)
KissLog.net (Repositório do GitHub)
Loggr (repositório GitHub)
NLog (repositório GitHub)
Sentry (repositório GitHub)
Serilog (repositório GitHub)
Stackdriver (repositório Github)
Algumas estruturas de terceiros podem fazer o log semântico, também conhecido como registro em log
estruturado.
Usar uma estrutura de terceiros é semelhante ao uso de um dos provedores internos:
1. Adicione um pacote NuGet ao projeto.
2. Chame um ILoggerFactory .
Para saber mais, consulte a documentação de cada provedor. Não há suporte para provedores de log de
terceiros na Microsoft.
Recursos adicionais
Registro em log de alto desempenho com o LoggerMessage no ASP.NET Core
Tratar erros no ASP.NET Core
Por Steve Smith e Tom Dykstra

Este artigo apresenta abordagens comuns para o tratamento de erros em aplicativos ASP.NET Core.
A página de exceção do desenvolvedor

Para configurar um aplicativo para exibir uma página que mostra informações detalhadas sobre exceções, use a
página de exceção do desenvolvedor. A página é disponibilizada pelo pacote Microsoft.AspNetCore.Diagnostics,
que está disponível no metapacote Microsoft.AspNetCore.App. Adicione uma linha ao método
Startup.Configure :
página de exceção do desenvolvedor. A página é disponibilizada pelo pacote Microsoft.AspNetCore.Diagnostics,
que está disponível no metapacote Microsoft.AspNetCore.All. Adicione uma linha ao método Startup.Configure :
página de exceção do desenvolvedor. A página é disponibilizada adicionando uma referência de pacote para o
pacote Microsoft.AspNetCore.Diagnostics no arquivo de projeto. Adicione uma linha ao método
Startup.Configure :

{
env.EnvironmentName = EnvironmentName.Production;
{
}
else
{
app.UseExceptionHandler("/error");
}
Coloque a chamada para UseDeveloperExceptionPage na frente de qualquer middleware no qual você deseja
capturar exceções, tais como app.UseMvc .
WARNING
Habilite a página de exceção do desenvolvedor somente quando o aplicativo estiver em execução no ambiente de
desenvolvimento. Não é recomendável compartilhar informações de exceção detalhadas publicamente quando o
aplicativo é executado em produção. Saiba mais sobre como configurar ambientes.
Para ver a página de exceção do desenvolvedor, execute o aplicativo de exemplo com o ambiente definido como
Development e adicione ?throw=true à URL base do aplicativo. A página inclui várias guias com informações
sobre a exceção e a solicitação. A primeira guia inclui um rastreamento de pilha:
A próxima guia mostra os parâmetros da cadeia de caracteres de consulta, se houver:
Se a solicitação tem cookies, eles serão exibidos na guia Cookies. Os cabeçalhos são vistos na última guia:
Configurar uma página de tratamento de exceção personalizada
Configure uma página do manipulador de exceção para usar quando o aplicativo não estiver em execução no
ambiente Development :

{
env.EnvironmentName = EnvironmentName.Production;
{
}
else
{
}
Em um aplicativo Razor Pages, o modelo dotnet new fornece uma página de erro e uma classe de erro
PageModel , na pasta Páginas do Razor Pages.
Em um aplicativo MVC, não decore o método de ação do manipulador de erro com atributos de método HTTP,
como HttpGet . Verbos explícitos impedem algumas solicitações de chegar ao método. Permita acesso anônimo
ao método para que os usuários não autenticados possam capazes receber a exibição de erro.
Por exemplo, o seguinte método de manipulador de erro é fornecido pelo modelo MVC dotnet novo e aparece
no controlador Home:
[AllowAnonymous]
public IActionResult Error()
{
return View(new ErrorViewModel
{ RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier });
}
Configurar páginas de código de status

Por padrão, o aplicativo não fornece uma página de código de status detalhada para códigos de status HTTP,
como 404 Não Encontrado. Para fornecer páginas de código de status, use o middleware das páginas de código
de status.
O middleware é disponibilizado pelo pacote Microsoft.AspNetCore.Diagnostics, que está disponível no
metapacote Microsoft.AspNetCore.App.
O middleware é disponibilizado pelo pacote Microsoft.AspNetCore.Diagnostics, que está disponível no
metapacote Microsoft.AspNetCore.All.
O middleware é disponibilizado adicionando uma referência de pacote para o pacote
Microsoft.AspNetCore.Diagnostics no arquivo de projeto.
Adicione uma linha ao método Startup.Configure :
app.UseStatusCodePages();
UseStatusCodePages deve ser chamado antes dos middlewares de tratamento da solicitação no pipeline (por
exemplo, o middleware de arquivos estáticos e o middleware MVC ).
Por padrão, o middleware de páginas de código de status adiciona manipuladores, somente de texto, para os
códigos de status comuns, como o 404:
O middleware permite vários métodos de extensão. Um método usa uma expressão lambda:
// Expose the members of the 'Microsoft.AspNetCore.Http' namespace

// at the top of the file:
// using Microsoft.AspNetCore.Http;
app.UseStatusCodePages(async context =>
{
context.HttpContext.Response.ContentType = "text/plain";
await context.HttpContext.Response.WriteAsync(
"Status code page, status code: " +
context.HttpContext.Response.StatusCode);
});
Outro método usa uma cadeia de caracteres de formato e de tipo de conteúdo:

app.UseStatusCodePages("text/plain", "Status code page, status code: {0}");
Há também métodos de extensão de redirecionamento e de nova execução. O método de redirecionamento

envia um código de status 302 encontrado para o cliente e o redireciona para o modelo de URL do local
fornecido. O modelo pode incluir um espaço reservado de {0} para o código de status. As URLs que começam
com ~ têm o caminho base anexado. Uma URL que não começa com ~ é usada como está.
app.UseStatusCodePagesWithRedirects("/error/{0}");
O método de nova execução retorna o código de status original ao cliente e especifica que o corpo da resposta
deve ser gerado executando novamente o pipeline de solicitação, utilizando um caminho alternativo. Esse
caminho pode conter um espaço reservado de {0} para o código de status:
app.UseStatusCodePagesWithReExecute("/error/{0}");
As páginas de código de status podem ser desabilitadas para solicitações específicas em um método de
manipulador de Páginas Razor ou em um controlador do MVC. Para desabilitar as páginas de código de status,
tente recuperar o IStatusCodePagesFeature da coleção HttpContext.Features da solicitação e desabilitar o
recurso se ele estiver disponível:
var statusCodePagesFeature = HttpContext.Features.Get<IStatusCodePagesFeature>();
if (statusCodePagesFeature != null)
{
statusCodePagesFeature.Enabled = false;
}
Se você está usando uma sobrecarga UseStatusCodePages* que aponta para um ponto de extremidade dentro do
aplicativo, crie um modo de exibição do MVC ou Razor Page para o ponto de extremidade. Por exemplo, o
modelo dotnet novo para um aplicativo Razor Pages produz a seguinte página e classe de modelo de página:
Error.cshtml:
@page
@model ErrorModel
@{
ViewData["Title"] = "Error";
}
<h1 class="text-danger">Error.</h1>
<h2 class="text-danger">An error occurred while processing your request.</h2>
@if (Model.ShowRequestId)
{
<p>
<strong>Request ID:</strong> <code>@Model.RequestId</code>
</p>
}
<h3>Development Mode</h3>
<p>
Swapping to <strong>Development</strong> environment will display more detailed
information about the error that occurred.
</p>
<p>
<strong>Development environment should not be enabled in deployed applications
</strong>, as it can result in sensitive information from exceptions being
displayed to end users. For local debugging, development environment can be
enabled by setting the <strong>ASPNETCORE_ENVIRONMENT</strong> environment
variable to <strong>Development</strong>, and restarting the application.
</p>
Error.cshtml.cs:
public class ErrorModel : PageModel

{
public string RequestId { get; set; }
public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);
[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None,

NoStore = true)]
public void OnGet()
{
RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;
}
}
Código de tratamento de exceção

Código em páginas de tratamento de exceção pode gerar exceções. Geralmente, é uma boa ideia que páginas de
erro de produção sejam compostas por conteúdo puramente estático.
Além disso, esteja ciente de que, depois que os cabeçalhos de uma resposta forem enviados, você não poderá
alterar o código de status da resposta e nenhuma página de exceção ou manipulador poderá ser executado. A
resposta deve ser concluída ou a conexão será anulada.
Tratamento de exceções do servidor

Além da lógica de tratamento de exceção no aplicativo, o servidor que hospeda o aplicativo executa uma parte
do tratamento de exceção. Se o servidor capturar uma exceção antes que os cabeçalhos sejam enviados, o
servidor enviará uma resposta 500 Erro Interno do Servidor sem corpo. Se o servidor capturar uma exceção
depois que os cabeçalhos forem enviados, o servidor fechará a conexão. As solicitações que não são
manipuladas pelo aplicativo são manipuladas pelo servidor. Qualquer exceção ocorrida é tratada pelo tratamento
de exceção do servidor. As páginas de erro personalizadas, o middleware de tratamento de exceção ou os filtros
configurados não afetam esse comportamento.
Tratamento de exceção na inicialização

Apenas a camada de hospedagem pode tratar exceções que ocorrem durante a inicialização do aplicativo.
Usando o Host da Web, você pode configurar como o host se comporta em resposta a erros durante a
inicialização usando as chaves captureStartupErrors e detailedErrors .
A hospedagem apenas poderá mostrar uma página de erro para um erro de inicialização capturado se o erro
ocorrer após a associação de endereço do host/porta. Se alguma associação falhar por algum motivo, a camada
de hospedagem registrará uma exceção crítica em log, o processo do dotnet falhará e nenhuma página de erro
será exibida quando o aplicativo estiver sendo executado no servidor Kestrel.
Quando executado no IIS ou no IIS Express, um 502.5 Falha no Processo será retornado pelo Módulo do
ASP.NET Core se o processo não puder ser iniciado. Para obter informações sobre como solucionar problemas
de inicialização ao hospedar com o IIS, consulte Solucionar problemas do ASP.NET Core no IIS. Para obter
informações sobre como solucionar problemas de inicialização com o Serviço de Aplicativo do Azure, consulte
Solucionar erros de inicialização do ASP.NET Core no Serviço de Aplicativo do Azure.
Tratamento de erro do ASP.NET Core MVC

Os aplicativos MVC contêm algumas opções adicionais para o tratamento de erros, como configurar filtros de
exceção e executar a validação do modelo.
Filtros de exceção
Os filtros de exceção podem ser configurados globalmente ou por controlador ou por ação em um aplicativo
MVC. Esses filtros tratam qualquer exceção sem tratamento ocorrida durante a execução de uma ação do
controlador ou de outro filtro. Esses filtros não são chamados de outra forma. Para saber mais, consulte Filtros.
TIP
Filtros de exceção são bons para interceptar exceções que ocorrem em ações do MVC, mas não são tão flexíveis quanto o
middleware de tratamento de erro. Dê preferência ao uso de middleware no geral e use filtros apenas quando precisar
fazer o tratamento de erro de modo diferente, dependendo da ação do MVC escolhida.
Tratando erros do estado do modelo

A validação do modelo ocorre antes da invocação de cada ação do controlador e é responsabilidade do método
de ação inspecionar ModelState.IsValid e responder de forma adequada.
Alguns aplicativos optam por seguir uma convenção padrão para lidar com erros de validação do modelo, caso
em que um filtro pode ser um local adequado para implementar uma política como essa. É necessário testar o
comportamento das ações com estados de modelo inválidos. Saiba mais em Testar a lógica do controlador.
Recursos adicionais
Referência de erros comuns para o Serviço de Aplicativo do Azure e o IIS com o ASP.NET Core
Solucionar problemas do ASP.NET Core no IIS
Solucionar erros de inicialização do ASP.NET Core no Serviço de Aplicativo do Azure
Por Rick Anderson e Steve Smith

O middleware é um software montado em um pipeline de aplicativo para manipular solicitações e
respostas. Cada componente:
Escolhe se deseja passar a solicitação para o próximo componente no pipeline.
Pode executar o trabalho antes e depois de o próximo componente no pipeline ser invocado.
Os delegados de solicitação são usados para criar o pipeline de solicitação. Os delegados de solicitação
manipulam cada solicitação HTTP.
Os delegados de solicitação são configurados usando os métodos de extensão Run, Map e Use. Um
delegado de solicitação individual pode ser especificado em linha como um método anônimo (chamado
do middleware em linha) ou pode ser definido em uma classe reutilizável. Essas classes reutilizáveis e
os métodos anônimos em linha são o middleware, também chamado de componentes do middleware.
Cada componente de middleware no pipeline de solicitação é responsável por invocar o próximo
componente no pipeline ou causar um curto-circuito do pipeline.
Migrar módulos e manipuladores HTTP para middleware do ASP.NET Core explica a diferença entre
pipelines de solicitação no ASP.NET Core e no ASP.NET 4.x e fornece mais exemplos do middleware.
Criar um pipeline do middleware com o IApplicationBuilder

O pipeline de solicitação do ASP.NET Core consiste em uma sequência de delegados de solicitação,
chamados um após o outro. O diagrama a seguir demonstra o conceito. O thread de execução segue as
setas pretas.
Cada delegado pode executar operações antes e depois do próximo delegado. Um delegado também
pode optar por não transmitir uma solicitação ao próximo delegado, o que também é chamado de
causar um curto -circuito do pipeline de solicitação. O curto-circuito geralmente é desejável porque ele
evita trabalho desnecessário. Por exemplo, o middleware de arquivos estáticos pode retornar uma
solicitação para um arquivo estático e ligar o restante do pipeline em curto-circuito. Os delegados de
tratamento de exceção são chamados no início do pipeline para que possam detectar exceções que
ocorrem em etapas posteriores do pipeline.
O aplicativo ASP.NET Core mais simples possível define um delegado de solicitação única que controla
todas as solicitações. Este caso não inclui um pipeline de solicitação real. Em vez disso, uma única
função anônima é chamada em resposta a cada solicitação HTTP.

{
{
app.Run(async context =>
{
await context.Response.WriteAsync("Hello, World!");
});
}
}
O primeiro delegado Run encerra o pipeline.

Encadeie vários delegados de solicitação junto com o Use. O parâmetro next representa o próximo
delegado no pipeline. Lembre-se de que você pode causar um curto-circuito no pipeline ao não chamar
o parâmetro next. Normalmente, você pode executar ações antes e depois do próximo delegado,
conforme o exemplo a seguir demonstra:

{
{
app.Use(async (context, next) =>
{
// Do work that doesn't write to the Response.
await next.Invoke();
// Do logging or other work that doesn't write to the Response.
});

{
await context.Response.WriteAsync("Hello from 2nd delegate.");
});
}
}
WARNING
Não chame next.Invoke depois que a resposta tiver sido enviada ao cliente. Altera para HttpResponse depois
de a resposta ser iniciada e lança uma exceção. Por exemplo, mudanças como a configuração de cabeçalhos e o
código de status lançam uma exceção. Gravar no corpo da resposta após a chamada next :
Pode causar uma violação do protocolo. Por exemplo, gravar mais do que o Content-Length indicado.
Pode corromper o formato do corpo. Por exemplo, gravar um rodapé HTML em um arquivo CSS.
HasStarted é uma dica útil para indicar se os cabeçalhos foram enviados ou o corpo foi gravado.
Pedido
A ordem em que os componentes do middleware são adicionados ao método Startup.Configure
define a ordem em que os componentes de middleware são invocados nas solicitações e a ordem
inversa para a resposta. A ordem é crítica para a segurança, o desempenho e a funcionalidade.
O método Startup.Configure a seguir adiciona componentes de middleware para cenários de
aplicativo comuns:
1. Exceção/tratamento de erro
2. Protocolo HTTP Strict Transport Security
3. Redirecionamento para HTTPS
4. Servidor de arquivos estático
5. Imposição de política de cookies
6. Autenticação
7. Session
8. MVC

{
{
// When the app runs in the Development environment:
// Use the Developer Exception Page to report app runtime errors.
// Use the Database Error Page to report database runtime errors.
app.UseDatabaseErrorPage();
}
else
{
// When the app doesn't run in the Development environment:
// Enable the Exception Handler Middleware to catch exceptions
// thrown in the following middlewares.
// Use the HTTP Strict Transport Security Protocol (HSTS)
// Middleware.
app.UseHsts();
}
// Use HTTPS Redirection Middleware to redirect HTTP requests to HTTPS.

// Return static files and end the pipeline.

// Use Cookie Policy Middleware to conform to EU General Data

// Protection Regulation (GDPR) regulations.
// Authenticate before the user accesses secure resources.

app.UseAuthentication();
// If the app uses session state, call Session Middleware after Cookie
// Policy Middleware and before MVC Middleware.
app.UseSession();
// Add MVC to the request pipeline.

app.UseMvc();
}
1. Exceção/tratamento de erro
2. Arquivos estáticos
3. Autenticação
4. Session
5. MVC
{
// Enable the Exception Handler Middleware to catch exceptions
// thrown in the following middlewares.
app.UseExceptionHandler("/Home/Error");
// Return static files and end the pipeline.

// Authenticate before you access secure resources.

app.UseIdentity();
// If the app uses session state, call UseSession before

// MVC Middleware.
app.UseSession();
// Add MVC to the request pipeline.

}
No código de exemplo anterior, cada método de extensão de middleware é exposto em

IApplicationBuilder por meio do namespace Microsoft.AspNetCore.Builder.
UseExceptionHandler é o primeiro componente de middleware adicionado ao pipeline. Portanto, o
middleware de manipulador de exceção captura todas as exceções que ocorrem em chamadas
posteriores.
O middleware de arquivos estáticos é chamado no início do pipeline para que possa controlar as
solicitações e causar o curto-circuito sem passar pelos componentes restantes. O middleware de
arquivos estáticos não fornece nenhuma verificação de autorização. Todos os arquivos atendidos,
incluindo aqueles em wwwroot, estão disponíveis publicamente. Para conhecer uma abordagem para
proteger arquivos estáticos, veja Arquivos estáticos no ASP.NET Core.
Se a solicitação não for controlada pelo middleware de arquivos estáticos, ela será transmitida para o
middleware de autenticação (UseAuthentication), que executa a autenticação. A autenticação causa
curto-circuito em solicitações não autenticadas. Embora o middleware de autenticação autentique as
solicitações, a autorização (e a rejeição) ocorre somente depois que o MVC seleciona uma Página Razor
específica ou um controlador MVC e uma ação.
Se a solicitação não for controlada pelo middleware de arquivos estáticos, ela será transmitida para o
middleware de identidade (UseIdentity), que executará a autenticação. A identidade não liga as
solicitações não autenticadas em curto-circuito. Embora a identidade autentique as solicitações, a
autorização (e a rejeição) ocorre somente depois que o MVC seleciona um controlador específico e uma
ação.
O exemplo a seguir demonstra uma solicitação de middleware na qual as solicitações de arquivos
estáticos são manipuladas pelo middleware de arquivo estático antes de o serem pelo middleware de
compactação de resposta. Arquivos estáticos não são compactados com este pedido de middleware. As
respostas do MVC de UseMvcWithDefaultRoute podem ser compactadas.

{
// Static files not compressed by Static Files Middleware.
app.UseResponseCompression();
}
Use, Run e Map

Configure o pipeline de HTTP usando Use , Run e Map . O método Use pode ligar o pipeline em
curto-circuito (ou seja, se ele não chamar um delegado de solicitação next ). Run é uma convenção e
alguns componentes de middleware podem expor os métodos Run[Middleware] que são executados no
final do pipeline.
As extensões Map são usadas como uma convenção de ramificação do pipeline. Map* ramifica o
pipeline de solicitação com base na correspondência do caminho da solicitação em questão. Se o
caminho da solicitação iniciar com o caminho especificado, o branch será executado.

{
private static void HandleMapTest1(IApplicationBuilder app)
{
{
await context.Response.WriteAsync("Map Test 1");
});
}
private static void HandleMapTest2(IApplicationBuilder app)

{
{
await context.Response.WriteAsync("Map Test 2");
});
}

{
app.Map("/map1", HandleMapTest1);
app.Map("/map2", HandleMapTest2);

{
await context.Response.WriteAsync("Hello from non-Map delegate. <p>");
});
}
}
A tabela a seguir mostra as solicitações e as respostas de http://localhost:1234 usando o código

anterior.
SOLICITAÇÃO RESPOSTA
localhost:1234 Saudação do delegado diferente de Map.
localhost:1234/map1 Teste de Map 1
localhost:1234/map2 Teste de Map 2
localhost:1234/map3 Saudação do delegado diferente de Map.
Quando Map é usado, os segmentos de caminho correspondentes são removidos do HttpRequest.Path

e anexados em HttpRequest.PathBase para cada solicitação.
MapWhen ramifica o pipeline de solicitação com base no resultado do predicado em questão. Qualquer
predicado do tipo Func<HttpContext, bool> pode ser usado para mapear as solicitações para um novo
branch do pipeline. No exemplo a seguir, um predicado é usado para detectar a presença de uma
variável de cadeia de caracteres de consulta branch :

{
private static void HandleBranch(IApplicationBuilder app)
{
{
var branchVer = context.Request.Query["branch"];
await context.Response.WriteAsync($"Branch used = {branchVer}");
});
}

{
app.MapWhen(context => context.Request.Query.ContainsKey("branch"),
HandleBranch);

{
await context.Response.WriteAsync("Hello from non-Map delegate. <p>");
});
}
}
A tabela a seguir mostra as solicitações e as respostas de http://localhost:1234 usando o código

anterior.
localhost:1234 Saudação do delegado diferente de Map.
localhost:1234/?branch=master Branch usado = mestre
Map é compatível com aninhamento, por exemplo:
app.Map("/level1", level1App => {

level1App.Map("/level2a", level2AApp => {
// "/level1/level2a" processing
});
level1App.Map("/level2b", level2BApp => {
// "/level1/level2b" processing
});
});
Map também pode ser correspondido com vários segmentos de uma vez:
{
private static void HandleMultiSeg(IApplicationBuilder app)
{
{
await context.Response.WriteAsync("Map multiple segments.");
});
}

{
app.Map("/map1/seg1", HandleMultiSeg);

{
await context.Response.WriteAsync("Hello from non-Map delegate.");
});
}
}
Middleware interno
O ASP.NET Core é fornecido com os seguintes componentes de middleware. A coluna Ordem fornece
observações sobre o posicionamento do middleware no pipeline de solicitação e sob quais condições o
middleware podem encerrar a solicitação e impedir que outro middleware processe uma solicitação.
MIDDLEWARE DESCRIÇÃO PEDIDO
Autenticação Fornece suporte à autenticação. Antes de HttpContext.User ser

necessário. Terminal para retornos
de chamada OAuth.
Política de cookies Acompanha o consentimento dos Antes do middleware que emite

usuários para o armazenamento de cookies. Exemplos: Autenticação,
informações pessoais e impõe Sessão e MVC (TempData).
padrões mínimos para campos de
cookie, tais como secure e
SameSite .
CORS Configura o Compartilhamento de Antes de componentes que usam o

Recursos entre Origens. CORS.
Diagnóstico Configura o diagnóstico. Antes dos componentes que geram

erros.
Cabeçalhos encaminhados Encaminha cabeçalhos como proxy Antes dos componentes que
para a solicitação atual. consomem os campos atualizados.
Exemplos: esquema, host, IP do
cliente e método.
Substituição do Método HTTP Permite que uma solicitação de Antes dos componentes que
entrada POST substitua o método. consomem o método atualizado.
Redirecionamento de HTTPS Redirecione todas as solicitações Antes dos componentes que

HTTP para HTTPS (ASP.NET Core consomem a URL.
2.1 ou posterior).
MIDDLEWARE DESCRIÇÃO PEDIDO
Segurança de Transporte Estrita de Middleware de aprimoramento de Antes das respostas serem enviadas
HTTP (HSTS) segurança que adiciona um e depois dos componentes que
cabeçalho de resposta especial modificam solicitações. Exemplos:
(ASP.NET Core 2.1 ou posterior). Cabeçalhos encaminhados,
regravação de URL.
MVC Processa as solicitações de Razor Terminal, se uma solicitação

Pages/MVC (ASP.NET Core 2.0 ou corresponder a uma rota.
posterior).
OWIN Interoperabilidade com aplicativos Terminal, se o middleware OWIN

baseados em OWIN, em servidores processa totalmente a solicitação.
e em middleware.
Cache de resposta Fornece suporte para as respostas Antes dos componentes que
em cache. exigem armazenamento em cache.
Compactação de resposta Fornece suporte para a Antes dos componentes que

compactação de respostas. exigem compactação.
Localização de Solicitação Fornece suporte à localização. Antes dos componentes de

localização importantes.
Roteamento Define e restringe as rotas de Terminal de rotas correspondentes.

solicitação.
Sessão Fornece suporte para gerenciar Antes de componentes que exigem

sessões de usuário. a sessão.
Arquivos estáticos Fornece suporte para servir Terminal, se uma solicitação

arquivos estáticos e pesquisa no corresponde a um arquivo.
diretório.
Regravação de URL Fornece suporte para regravar Antes dos componentes que
URLs e redirecionar solicitações. consomem a URL.
WebSockets Habilita o protocolo WebSockets. Antes dos componentes que são

necessários para aceitar solicitações
de WebSocket.
Gravar middleware
O middleware geralmente é encapsulado em uma classe e exposto com um método de extensão.
Considere o middleware a seguir, que define a cultura para a solicitação atual de uma cadeia de
caracteres de consulta:
{
{
app.Use((context, next) =>
{
var cultureQuery = context.Request.Query["culture"];
if (!string.IsNullOrWhiteSpace(cultureQuery))
{
var culture = new CultureInfo(cultureQuery);
CultureInfo.CurrentCulture = culture;
CultureInfo.CurrentUICulture = culture;
}
// Call the next delegate/middleware in the pipeline

return next();
});

{
$"Hello {CultureInfo.CurrentCulture.DisplayName}");
});
}
}
O código de exemplo anterior é usado para demonstrar a criação de um componente de middleware.

Para suporte de localização interna do ASP.NET Core, veja Globalização e localização no ASP.NET
Core.
Você pode testar o middleware ao transmitir a cultura, por exemplo http://localhost:7997/?culture=no .
O código a seguir move o delegado de middleware para uma classe:
using System.Globalization;
namespace Culture
{
public class RequestCultureMiddleware
{
public RequestCultureMiddleware(RequestDelegate next)

{
_next = next;
}
public async Task InvokeAsync(HttpContext context)

{
var cultureQuery = context.Request.Query["culture"];
if (!string.IsNullOrWhiteSpace(cultureQuery))
{
var culture = new CultureInfo(cultureQuery);
CultureInfo.CurrentCulture = culture;
CultureInfo.CurrentUICulture = culture;
// Call the next delegate/middleware in the pipeline

await _next(context);
}
}
}
O nome do método Task de middleware precisa ser Invoke . No ASP.NET Core 2.0 ou posterior, o
nome pode ser Invoke ou InvokeAsync .
O seguinte método de extensão expõe o middleware por meio do IApplicationBuilder:
namespace Culture
{
public static class RequestCultureMiddlewareExtensions
{
public static IApplicationBuilder UseRequestCulture(
this IApplicationBuilder builder)
{
return builder.UseMiddleware<RequestCultureMiddleware>();
}
}
}
O código a seguir chama o middleware de Startup.Configure :

{
{
app.UseRequestCulture();

{
$"Hello {CultureInfo.CurrentCulture.DisplayName}");
});
}
}
O middleware deve seguir o princípio de dependências explícitas ao expor suas dependências em seu
construtor. O middleware é construído uma vez por tempo de vida do aplicativo. Consulte a seção
Dependências por solicitação se você precisar compartilhar serviços com middleware dentro de uma
solicitação.
Os componentes de middleware podem resolver suas dependências, utilizando a DI (injeção de
dependência) por meio de parâmetros do construtor. UseMiddleware<T> também pode aceitar
parâmetros adicionais diretamente.
Dependências de pré -solicitação
Uma vez que o middleware é construído durante a inicialização do aplicativo, e não por solicitação, os
serviços de tempo de vida com escopo usados pelos construtores do middleware não são
compartilhados com outros tipos de dependência inseridos durante cada solicitação. Se você tiver que
compartilhar um serviço com escopo entre seu serviço de middleware e serviços de outros tipos,
adicione esses serviços à assinatura do método Invoke . O método Invoke pode aceitar parâmetros
adicionais que são preenchidos pela injeção de dependência:
public class CustomMiddleware

{
public CustomMiddleware(RequestDelegate next)

{
_next = next;
}
// IMyScopedService is injected into Invoke

public async Task Invoke(HttpContext httpContext, IMyScopedService svc)
{
svc.MyProperty = 1000;
}
}
Recursos adicionais
Migrar módulos e manipuladores HTTP para middleware do ASP.NET Core
Solicitar recursos no ASP.NET Core
Ativação de middleware baseada em alocador no ASP.NET Core
Ativação de middleware com um contêiner de terceiros no ASP.NET Core
Ativação de middleware baseada em alocador no
ASP.NET Core
Por Luke Latham

IMiddlewareFactory/IMiddleware é um ponto de extensibilidade para a ativação de middleware.
Os métodos de extensão UseMiddleware verificam se o tipo registrado de um middleware implementa
IMiddleware . Se isso acontecer, a instância IMiddlewareFactory registrada no contêiner será usada para resolver a
implementação IMiddleware em vez de usar a lógica de ativação de middleware baseada em convenção. O
middleware é registrado como um serviço com escopo ou transitório no contêiner de serviço do aplicativo.
Benefícios:
Ativação por solicitação (injeção de serviços com escopo)
Tipagem forte de middleware
IMiddleware é ativado por solicitação, de modo que os serviços com escopo possam ser injetados no construtor
do middleware.
O aplicativo de exemplo demonstra o middleware ativado por:
Convenção. Para obter mais informações sobre a ativação de middleware convencional, consulte o tópico
Middleware.
Uma implementação de IMiddleware. A classe MiddlewareFactory padrão ativa o middleware.
As implementações de middleware funcionam de forma idêntica e registram o valor fornecido por um parâmetro
de cadeia de caracteres de consulta ( key ). Os middlewares usam um contexto de banco de dados injetado (um
serviço com escopo) para registrar o valor de cadeia de caracteres de consulta em um banco de dados em
memória.
IMiddleware
IMiddleware define o middleware para o pipeline de solicitação do aplicativo. O método
InvokeAsync(HttpContext, RequestDelegate) manipula as solicitações e retorna uma Task que representa a
execução do middleware.
Middleware ativado por convenção:
public class ConventionalMiddleware
{
public ConventionalMiddleware(RequestDelegate next)

{
_next = next;
}
public async Task InvokeAsync(HttpContext context, AppDbContext db)

{
var keyValue = context.Request.Query["key"];
if (!string.IsNullOrWhiteSpace(keyValue))
{
db.Add(new Request()
{
DT = DateTime.UtcNow,
MiddlewareActivation = "ConventionalMiddleware",
Value = keyValue
});
await db.SaveChangesAsync();
}
await _next(context);
}
}
Middleware ativado por MiddlewareFactory :
public class FactoryActivatedMiddleware : IMiddleware

{
private readonly AppDbContext _db;
public FactoryActivatedMiddleware(AppDbContext db)

{
_db = db;
}
public async Task InvokeAsync(HttpContext context, RequestDelegate next)

{
{
_db.Add(new Request()
{
MiddlewareActivation = "FactoryActivatedMiddleware",
Value = keyValue
});
await _db.SaveChangesAsync();
}
await next(context);
}
}
As extensões são criadas para os middlewares:

public static class MiddlewareExtensions
{
public static IApplicationBuilder UseConventionalMiddleware(
{
return builder.UseMiddleware<ConventionalMiddleware>();
}
public static IApplicationBuilder UseFactoryActivatedMiddleware(

{
return builder.UseMiddleware<FactoryActivatedMiddleware>();
}
}
Não é possível passar objetos para o middleware ativado por alocador com UseMiddleware :
public static IApplicationBuilder UseFactoryActivatedMiddleware(

this IApplicationBuilder builder, bool option)
{
// Passing 'option' as an argument throws a NotSupportedException at runtime.
return builder.UseMiddleware<FactoryActivatedMiddleware>(option);
}
O middleware ativado por alocador é adicionado ao contêiner interno em Startup.cs:

{
{
});
services.AddDbContext<AppDbContext>(options =>
options.UseInMemoryDatabase("InMemoryDb"));
services.AddTransient<FactoryActivatedMiddleware>();
}
Ambos os middlewares estão registrados no pipeline de processamento de solicitação em Configure :

{
{
}
else
{
app.UseHsts();
}
app.UseConventionalMiddleware();
app.UseFactoryActivatedMiddleware();
app.UseMvc();
}
IMiddlewareFactory
IMiddlewareFactory fornece métodos para a criação do middleware. A implementação de alocador do middleware
é registrada no contêiner como um serviço com escopo.
A implementação IMiddlewareFactory padrão, MiddlewareFactory, foi encontrada no pacote
Microsoft.AspNetCore.Http.
Recursos adicionais
Ativação de middleware com um contêiner de terceiros no ASP.NET Core
Ativação de middleware com um contêiner de
terceiros no ASP.NET Core
Por Luke Latham

Este artigo demonstra como usar o IMiddlewareFactory e o IMiddleware como um ponto de extensibilidade para
a ativação do middleware com um contêiner de terceiros. Para obter informações introdutórias sobre o
IMiddlewareFactory e o IMiddleware , confira o tópico Ativação de middleware baseada em alocador no ASP.NET
Core.
O aplicativo de exemplo demonstra a ativação do middleware por uma implementação de IMiddlewareFactory ,
SimpleInjectorMiddlewareFactory . O exemplo usa o contêiner de DI (injeção de dependência) Simple Injector.
A implementação do middleware do exemplo registra o valor fornecido por um parâmetro de cadeia de consulta (
key ). O middleware usa um contexto de banco de dados injetado (um serviço com escopo) para registrar o valor
da cadeia de consulta em um banco de dados em memória.
NOTE
O aplicativo de exemplo usa o Simple Injector simplesmente para fins de demonstração. O uso do Simple Injector não é um
endosso. As abordagens de ativação do middleware descritas na documentação do Simple Injector e nos problemas do
GitHub são recomendadas pelos mantenedores do Simple Injector. Para obter mais informações, confira a Documentação do
Simple Injector e o repositório do GitHub do Simple Injector.
IMiddlewareFactory
IMiddlewareFactory fornece métodos para a criação do middleware.
No aplicativo de amostra, um alocador de middleware é implementado para criar uma instância de
SimpleInjectorActivatedMiddleware . O alocador de middleware usa o contêiner do Simple Injector para resolver o
middleware:
public class SimpleInjectorMiddlewareFactory : IMiddlewareFactory
{
private readonly Container _container;
public SimpleInjectorMiddlewareFactory(Container container)

{
_container = container;
}
public IMiddleware Create(Type middlewareType)

{
return _container.GetInstance(middlewareType) as IMiddleware;
}
public void Release(IMiddleware middleware)

{
// The container is responsible for releasing resources.
}
}
IMiddleware
IMiddleware define o middleware para o pipeline de solicitação do aplicativo.
Middleware ativado por uma implementação de IMiddlewareFactory
(Middleware/SimpleInjectorActivatedMiddleware.cs):
public class SimpleInjectorActivatedMiddleware : IMiddleware

{
public SimpleInjectorActivatedMiddleware(AppDbContext db)

{
_db = db;
}
public async Task InvokeAsync(HttpContext context, RequestDelegate next)

{
{
_db.Add(new Request()
{
MiddlewareActivation = "SimpleInjectorActivatedMiddleware",
Value = keyValue
});
}
await next(context);
}
}
Uma extensão é criada para o middleware (Middleware/MiddlewareExtensions.cs):

public static class MiddlewareExtensions
{
public static IApplicationBuilder UseSimpleInjectorActivatedMiddleware(
{
return builder.UseMiddleware<SimpleInjectorActivatedMiddleware>();
}
}
O Startup.ConfigureServices precisa executar várias tarefas:

Configure o contêiner do Simple Injector.
Registre o alocador e o middleware.
Disponibilize o contexto do banco de dados do aplicativo por meio do contêiner do Simple Injector para uma
página Razor.

{
{
});
// Replace the default middleware factory with the

// SimpleInjectorMiddlewareFactory.
services.AddTransient<IMiddlewareFactory>(_ =>
{
return new SimpleInjectorMiddlewareFactory(_container);
});
// Wrap ASP.NET Core requests in a Simple Injector execution

// context.
services.UseSimpleInjectorAspNetRequestScoping(_container);
// Provide the database context from the Simple

// Injector container whenever it's requested from
// the default service container.
services.AddScoped<AppDbContext>(provider =>
_container.GetInstance<AppDbContext>());
_container.Options.DefaultScopedLifestyle = new AsyncScopedLifestyle();
_container.Register<AppDbContext>(() =>
{
var optionsBuilder = new DbContextOptionsBuilder<DbContext>();
optionsBuilder.UseInMemoryDatabase("InMemoryDb");
return new AppDbContext(optionsBuilder.Options);
}, Lifestyle.Scoped);
_container.Register<SimpleInjectorActivatedMiddleware>();
_container.Verify();
}
O middleware é registrado no pipeline de processamento da solicitação em Startup.Configure :

{
{
}
else
{
app.UseHsts();
}
app.UseSimpleInjectorActivatedMiddleware();
app.UseMvc();
}
Recursos adicionais
Middleware
Ativação de middleware de fábrica
Repositório do GitHub do Simple Injector
Documentação do Simple Injector
Aplicativos ASP.NET Core configuram e inicializam um host. O host é responsável pelo gerenciamento de
tempo de vida e pela inicialização do aplicativo. Duas APIs de host estão disponíveis para uso:
Host da Web – Adequado para a hospedagem de aplicativos Web.
Host Genérico (ASP.NET Core 2.1 ou posteriores) – Adequado para a hospedagem de aplicativos não Web
(por exemplo, aplicativos que executam tarefas em segundo plano). Em uma versão futura, o Host
Genérico será adequado para hospedar qualquer tipo de aplicativo, incluindo aplicativos Web.
Eventualmente, o Host Genérico substituirá o Host da Web.
Para hospedar aplicativos Web do ASP.NET Core, os desenvolvedores devem usar o Web Host com base em
IWebHostBuilder. Para hospedar aplicativos que não sejam Web, os desenvolvedores devem usar o Host
Genérico com base em HostBuilder.
Tarefas em segundo plano com serviços hospedados no ASP.NET Core
Aprenda a implementar tarefas em segundo plano com serviços hospedados no ASP.NET Core.
Aprimorar um aplicativo por meio de um assembly externo no ASP.NET Core com IHostingStartup
Descubra como aprimorar um aplicativo ASP.NET Core por meio de um assembly referenciado ou não
referenciado usando uma implementação de IHostingStartup.
Host da Web do ASP.NET Core
Por Luke Latham

Aplicativos ASP.NET Core configuram e inicializam um host. O host é responsável pelo gerenciamento de
tempo de vida e pela inicialização do aplicativo. No mínimo, o host configura um servidor e um pipeline de
processamento de solicitações. Este tópico aborda o Host da Web ASP.NET Core (IWebHostBuilder), que é útil
para hospedagem de aplicativos Web. Para cobertura do Host Genérico .NET ( IHostBuilder), veja Host Genérico
.NET.
Configurar um host
Crie um host usando uma instância do IWebHostBuilder. Normalmente, isso é feito no ponto de entrada do
aplicativo, o método Main . Em modelos de projeto, Main está localizado em Program.cs. Um Program.cs típico
chama CreateDefaultBuilder para começar a configurar um host:

{
{
}

}
CreateDefaultBuilder executa as seguintes tarefas:

Configura o Kestrel como o servidor Web e configura o servidor usando provedores de configuração de
hospedagem do aplicativo. Para as opções padrão do Kestrel, veja Implementação do servidor Web Kestrel
no ASP.NET Core.
Define a raiz do conteúdo como o caminho retornado por Directory.GetCurrentDirectory.
Carrega a configuração do host de:
Variáveis de ambiente prefixadas com ASPNETCORE_ (por exemplo, ASPNETCORE_ENVIRONMENT ).
Carrega a configuração do aplicativo na seguinte ordem de:
appsettings.json.
appsettings.{Environment}.json.
Gerenciador de Segredo quando o aplicativo é executado no ambiente Development usando o
assembly de entrada.
Configura o registro em log para a saída do console e de depuração. O registro em log inclui regras de
filtragem de log especificadas em uma seção de configuração de registro em log de um arquivo
appsettings.json ou appsettings.{Environment}.json.
Quando executado por trás do IIS, permite a integração de IIS. Configura o caminho base e a porta que o
servidor escuta ao usar o Módulo do ASP.NET Core. O módulo cria um proxy reverso entre o IIS e o Kestrel.
Também configura o aplicativo para capturar erros de inicialização. Para as opções padrão do IIS, veja
Hospedar o ASP.NET Core no Windows com o IIS.
Definirá ServiceProviderOptions.ValidateScopes como true se o ambiente do aplicativo for de
desenvolvimento. Para obter mais informações, confira Validação de escopo.
A configuração definida por CreateDefaultBuilder pode ser substituída e aumentada por
ConfigureAppConfiguration, ConfigureLogging e outros métodos, bem como os métodos de extensão de
IWebHostBuilder. Veja a seguir alguns exemplos:
ConfigureAppConfiguration é usado para especificar IConfiguration adicionais para o aplicativo. A
seguinte chamada de ConfigureAppConfiguration adiciona um delegado para incluir a configuração do
aplicativo no arquivo appsettings.xml. ConfigureAppConfiguration pode ser chamado várias vezes.
Observe que essa configuração não se aplica ao host (por exemplo, URLs de servidor ou de ambiente).
Consulte a seção Valores de configuração de Host.
{
config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
})
...
A seguinte chamada de ConfigureLogging adiciona um delegado para configurar o nível de log mínimo
(SetMinimumLevel) como LogLevel.Warning. Essa configuração substitui as configurações em
appsettings.Development.json ( LogLevel.Debug ) e appsettings.Production.json ( LogLevel.Error )
configuradas por CreateDefaultBuilder . ConfigureLogging pode ser chamado várias vezes.
{
logging.SetMinimumLevel(LogLevel.Warning);
})
...
A seguinte chamada para ConfigureKestrel substitui o padrão Limits.MaxRequestBodySize de 30

milhões de bytes, estabelecido quando o Kestrel foi configurado pelo CreateDefaultBuilder :
.ConfigureKestrel((context, options) =>
{
options.Limits.MaxRequestBodySize = 20000000;
});
...
A seguinte chamada a UseKestrel substitui o padrão Limits.MaxRequestBodySize de 30.000.000 bytes

estabelecido quando Kestrel foi configurado por CreateDefaultBuilder :
.UseKestrel(options =>
{
options.Limits.MaxRequestBodySize = 20000000;
});
...
A raiz do conteúdo determina onde o host procura por arquivos de conteúdo, como arquivos de exibição do
MVC. Quando o aplicativo é iniciado na pasta raiz do projeto, essa pasta é usada como a raiz do conteúdo. Esse
é o padrão usado no Visual Studio e nos novos modelos dotnet.
Para obter mais informações sobre a configuração de aplicativo, veja Configuração no ASP.NET Core.
NOTE
Como uma alternativa ao uso do método CreateDefaultBuilder estático, criar um host de WebHostBuilder é uma
abordagem compatível com o ASP.NET Core 2. x. Para obter mais informações, consulte a guia do ASP.NET Core 1.x.
Crie um host usando uma instância de WebHostBuilder. A criação de um host normalmente é feita no ponto de
entrada do aplicativo, o método Main . Em modelos de projeto, Main está localizado em Program.cs:

{
{
}

.Build();
}
WebHostBuilder requer um servidor que implementa IServer. Os servidores internos são Kestrel e HTTP.sys
(antes do lançamento do ASP.NET Core 2.0, HTTP.sys era chamado de WebListener). Neste exemplo, o método
de extensão UseKestrel especifica o servidor Kestrel.
A raiz do conteúdo determina onde o host procura por arquivos de conteúdo, como arquivos de exibição do
MVC. A raiz de conteúdo padrão é obtida para UseContentRoot por Directory.GetCurrentDirectory. Quando o
aplicativo é iniciado na pasta raiz do projeto, essa pasta é usada como a raiz do conteúdo. Esse é o padrão usado
no Visual Studio e nos novos modelos dotnet.
Para usar o IIS como um proxy reverso, chame UseIISIntegration como parte da compilação do host.
UseIISIntegration não configura um servidor como UseKestrel o faz. UseIISIntegration configura o caminho
base e a porta que o servidor escuta ao usar o Módulo do ASP.NET Core para criar um proxy reverso entre o
Kestrel e o IIS. Para usar o IIS com o ASP.NET Core, tanto UseKestrel quanto UseIISIntegration precisam ser
especificados. UseIISIntegration é ativado somente quando é executado por trás do IIS ou do IIS Express. Para
obter mais informações, consulte Módulo do ASP.NET Core e Referência de configuração do Módulo do
ASP.NET Core.
Uma implementação mínima que configura um host (e um aplicativo ASP.NET Core) inclui a especificação de
um servidor e a configuração do pipeline de solicitações do aplicativo:

.UseKestrel()
.Configure(app =>
{
app.Run(context => context.Response.WriteAsync("Hello World!"));
})
.Build();
host.Run();
Ao configurar um host, os métodos Configure e ConfigureServices podem ser fornecidos. Se uma classe
Startup for especificada, ela deverá definir um método Configure . Para obter mais informações, consulte
Inicialização de aplicativo no ASP.NET Core. Diversas chamadas para ConfigureServices são acrescentadas
umas às outras. Diversas chamadas para Configure ou UseStartup no WebHostBuilder substituem
configurações anteriores.
Valores de configuração do host

WebHostBuilder conta com as seguintes abordagens para definir os valores de configuração do host:
Configuração do construtor do host, que inclui variáveis de ambiente com o formato
ASPNETCORE_{configurationKey} . Por exemplo, ASPNETCORE_ENVIRONMENT .
Extensões como UseContentRoot e UseConfiguration (consulte a seção Configuração de substituição).
UseSetting e a chave associada. Ao definir um valor com UseSetting , o valor é definido como uma cadeia de
caracteres, independentemente do tipo.
O host usa a opção que define um valor por último. Para obter mais informações, veja Substituir configuração
na próxima seção.
Chave do Aplicativo (Nome )
A propriedade IHostingEnvironment.ApplicationName é definida automaticamente quando UseStartup ou
Configure é chamado durante a construção do host. O valor é definido para o nome do assembly que contém o
ponto de entrada do aplicativo. Para definir o valor explicitamente, use o WebHostDefaults.ApplicationKey:
Chave: applicationName
Tipo: string
Padrão: o nome do assembly que contém o ponto de entrada do aplicativo.
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_APPLICATIONNAME
.UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

.UseSetting("applicationName", "CustomApplicationName")
Capturar erros de inicialização

Esta configuração controla a captura de erros de inicialização.
Chave: captureStartupErrors
Tipo: bool ( true ou 1 )
Padrão: o padrão é false , a menos que o aplicativo seja executado com o Kestrel por trás do IIS, em que o
padrão é true .
Definido usando: CaptureStartupErrors
Variável de ambiente: ASPNETCORE_CAPTURESTARTUPERRORS
Quando false , erros durante a inicialização resultam no encerramento do host. Quando true , o host captura
exceções durante a inicialização e tenta iniciar o servidor.
.CaptureStartupErrors(true)
.CaptureStartupErrors(true)
Raiz do conteúdo
Essa configuração determina onde o ASP.NET Core começa a procurar por arquivos de conteúdo, como
exibições do MVC.
Chave: contentRoot
Tipo: string
Padrão: o padrão é a pasta em que o assembly do aplicativo reside.
Definido usando: UseContentRoot
Variável de ambiente: ASPNETCORE_CONTENTROOT
A raiz do conteúdo também é usada como o caminho base para a Configuração da raiz da Web. Se o caminho
não existir, o host não será iniciado.
.UseContentRoot("c:\\<content-root>")

Erros detalhados
Determina se erros detalhados devem ser capturados.
Chave: detailedErrors
Padrão: falso
Variável de ambiente: ASPNETCORE_DETAILEDERRORS
Quando habilitado (ou quando o Ambiente é definido como Development ), o aplicativo captura exceções
detalhadas.
.UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

.UseSetting(WebHostDefaults.DetailedErrorsKey, "true")
Ambiente
Define o ambiente do aplicativo.
Chave: ambiente
Tipo: string
Padrão: Production
Definido usando: UseEnvironment
Variável de ambiente: ASPNETCORE_ENVIRONMENT
O ambiente pode ser definido como qualquer valor. Os valores definidos pela estrutura incluem Development ,
Staging e Production . Os valores não diferenciam maiúsculas de minúsculas. Por padrão, o Ambiente é lido da
variável de ambiente ASPNETCORE_ENVIRONMENT . Ao usar o Visual Studio, variáveis de ambiente podem ser
definidas no arquivo launchSettings.json. Para obter mais informações, consulte Usar vários ambientes no
ASP.NET Core.
.UseEnvironment(EnvironmentName.Development)

Hospedando assemblies de inicialização

Define os assemblies de inicialização de hospedagem do aplicativo.
Chave: hostingStartupAssemblies
Tipo: string
Padrão: cadeia de caracteres vazia
Variável de ambiente: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES
Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para
carregamento na inicialização.
Embora o valor padrão da configuração seja uma cadeia de caracteres vazia, os assemblies de inicialização de
hospedagem sempre incluem o assembly do aplicativo. Quando assemblies de inicialização de hospedagem são
fornecidos, eles são adicionados ao assembly do aplicativo para carregamento quando o aplicativo compilar
seus serviços comuns durante a inicialização.
.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")
Porta HTTPS
Defina a porta de redirecionamento HTTPS. Uso em aplicação de HTTPS.
Chave: https_port Tipo: string Padrão: Um valor padrão não está definido. Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_HTTPS_PORT
.UseSetting("https_port", "8080")
Hospedando assemblies de exclusão de inicialização

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para
exclusão na inicialização.
Chave: hostingStartupExcludeAssemblies
Tipo: string
Padrão: cadeia de caracteres vazia
Variável de ambiente: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES
.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")
Preferir URLs de hospedagem
Indica se o host deve escutar as URLs configuradas com o WebHostBuilder em vez daquelas configuradas com a
implementação IServer .
Chave: preferHostingUrls
Padrão: true
Definido usando: PreferHostingUrls
Variável de ambiente: ASPNETCORE_PREFERHOSTINGURLS
.PreferHostingUrls(false)
Impedir inicialização de hospedagem

Impede o carregamento automático de assemblies de inicialização de hospedagem, incluindo assemblies de
inicialização de hospedagem configurados pelo assembly do aplicativo. Para obter mais informações, consulte
Aprimorar um aplicativo por meio de um assembly externo no ASP.NET Core com IHostingStartup.
Chave: preventHostingStartup
Padrão: falso
Variável de ambiente: ASPNETCORE_PREVENTHOSTINGSTARTUP
.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")
URLs de servidor
Indica os endereços IP ou endereços de host com portas e protocolos que o servidor deve escutar para
solicitações.
Chave: urls
Tipo: string
Padrão: http://localhost:5000
Definido usando: UseUrls
Variável de ambiente: ASPNETCORE_URLS
Defina como uma lista separada por ponto e vírgula (;) de prefixos de URL aos quais o servidor deve responder.
Por exemplo, http://localhost:123 . Use "*" para indicar que o servidor deve escutar solicitações em qualquer
endereço IP ou nome do host usando a porta e o protocolo especificados (por exemplo, http://*:5000 ). O
protocolo ( http:// ou https:// ) deve ser incluído com cada URL. Os formatos compatíveis variam
dependendo dos servidores.
.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002")
O Kestrel tem sua própria API de configuração de ponto de extremidade. Para obter mais informações, consulte
Implementação do servidor Web Kestrel no ASP.NET Core.

.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002")
Tempo limite de desligamento
Especifica o tempo de espera para o desligamento do host da Web.
Chave: shutdownTimeoutSeconds
Tipo: int
Padrão: 5
Definido usando: UseShutdownTimeout
Variável de ambiente: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS
Embora a chave aceite um int com UseSetting(por exemplo,
.UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10") ), o método de extensão UseShutdownTimeout usa um
TimeSpan.
Durante o período de tempo limite, a hospedagem:
Dispara IApplicationLifetime.ApplicationStopping.
Tenta parar os serviços hospedados, registrando em log os erros dos serviços que falham ao parar.
Se o período de tempo limite expirar antes que todos os serviços hospedados parem, os serviços ativos
restantes serão parados quando o aplicativo for desligado. Os serviços serão parados mesmo se ainda não
tiverem concluído o processamento. Se os serviços exigirem mais tempo para parar, aumente o tempo limite.
.UseShutdownTimeout(TimeSpan.FromSeconds(10))
Assembly de inicialização
Determina o assembly para pesquisar pela classe Startup .
Chave: startupAssembly
Tipo: string
Padrão: o assembly do aplicativo
Definido usando: UseStartup
Variável de ambiente: ASPNETCORE_STARTUPASSEMBLY
O assembly por nome ( string ) ou por tipo ( TStartup ) pode ser referenciado. Se vários métodos UseStartup
forem chamados, o último terá precedência.
.UseStartup("StartupAssemblyName")
.UseStartup<TStartup>()

.UseStartup("StartupAssemblyName")

.UseStartup<TStartup>()
Raiz da Web
Define o caminho relativo para os ativos estáticos do aplicativo.
Chave: webroot
Tipo: string
Padrão: se não for especificado, o padrão será "(Raiz do conteúdo)/wwwroot", se o caminho existir. Se o
caminho não existir, um provedor de arquivo não operacional será usado.
Definido usando: UseWebRoot
Variável de ambiente: ASPNETCORE_WEBROOT
.UseWebRoot("public")

.UseWebRoot("public")
Substituir configuração
Use Configuração para configurar o host Web. No exemplo a seguir, a configuração do host é especificada,
opcionalmente, em um arquivo hostsettings.json. Qualquer configuração carregada do arquivo hostsettings.json
pode ser substituída por argumentos de linha de comando. A configuração de build (no config ) é usada para
configurar o host com UseConfiguration. A configuração IWebHostBuilder é adicionada à configuração do
aplicativo, mas o contrário não é verdade— ConfigureAppConfiguration não afeta a configuração
IWebHostBuilder .
Substituição da configuração fornecida por UseUrls pela configuração de hostsettings.json primeiro, e pela
configuração de argumento da linha de comando depois:

{
{
}

{
.AddJsonFile("hostsettings.json", optional: true)
.Build();
.Configure(app =>
{
app.Run(context =>
context.Response.WriteAsync("Hello, World!"));
})
.Build();
}
}
hostsettings.json:
{
urls: "http://*:5005"
}
Substituição da configuração fornecida por UseUrls pela configuração de hostsettings.json primeiro, e pela
configuração de argumento da linha de comando depois:

{
{
.AddJsonFile("hostsettings.json", optional: true)
.Build();

.UseKestrel()
.Configure(app =>
{
app.Run(context =>
context.Response.WriteAsync("Hello, World!"));
})
.Build();
host.Run();
}
}
hostsettings.json:
{
urls: "http://*:5005"
}
NOTE
Atualmente, o método de extensão UseConfiguration não é capaz de analisar uma seção de configuração retornada por
GetSection (por exemplo, .UseConfiguration(Configuration.GetSection("section")) ). O método GetSection
filtra as chaves de configuração da seção solicitada, mas deixa o nome da seção nas chaves (por exemplo, section:urls ,
section:environment ). O método UseConfiguration espera que as chaves correspondam às chaves
WebHostBuilder (por exemplo, urls , environment ). A presença do nome da seção nas chaves impede que os valores
da seção configurem o host. Esse problema será corrigido em uma próxima versão. Para obter mais informações e
soluções alternativas, consulte Passar a seção de configuração para WebHostBuilder.UseConfiguration usa chaves
completas.
UseConfiguration somente copia as chaves do IConfiguration fornecido para a configuração do construtor de host.
Portanto, definir reloadOnChange: true para arquivos de configuração JSON, INI e XML não tem nenhum efeito.
Para especificar o host executado em uma URL específica, o valor desejado pode ser passado em um prompt de
comando ao executar dotnet run. O argumento de linha de comando substitui o valor urls do arquivo
hostsettings.json e o servidor escuta na porta 8080:
dotnet run --urls "http://*:8080"
Gerenciar o host
Executar
O método Run inicia o aplicativo Web e bloqueia o thread de chamada até que o host seja desligado:
host.Run();
Iniciar
Execute o host sem bloqueio, chamando seu método Start :
using (host)
{
host.Start();
Console.ReadLine();
}
Se uma lista de URLs for passada para o método Start , ele escutará nas URLs especificadas:
var urls = new List<string>()

{
"http://*:5000",
"http://localhost:5001"
};

.UseKestrel()
.Start(urls.ToArray());
using (host)
{
Console.ReadLine();
}
O aplicativo pode inicializar e iniciar um novo host usando os padrões pré-configurados de

CreateDefaultBuilder , usando um método estático conveniente. Esses métodos iniciam o servidor sem uma
saída do console e com WaitForShutdown e aguardam uma quebra (Ctrl-C/SIGINT ou SIGTERM ):
Start(RequestDelegate app)
Inicie com um RequestDelegate :
using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))

{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}
Faça uma solicitação no navegador para http://localhost:5000 para receber a resposta "Olá, Mundo!"
WaitForShutdown bloqueia até que uma quebra ( Ctrl-C/SIGINT ou SIGTERM ) seja emitida. O aplicativo exibe a
mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.
Start(string url, RequestDelegate app)
Inicie com uma URL e RequestDelegate :
using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))

{
}
Produz o mesmo resultado que Start(RequestDelegate app), mas o aplicativo responde em

Start(Action<IRouteBuilder> routeBuilder)
Use uma instância de IRouteBuilder (Microsoft.AspNetCore.Routing) para usar o middleware de roteamento:
using (var host = WebHost.Start(router => router

.MapGet("hello/{name}", (req, res, data) =>
res.WriteAsync($"Hello, {data.Values["name"]}!"))
.MapGet("buenosdias/{name}", (req, res, data) =>
res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
.MapGet("throw/{message?}", (req, res, data) =>
throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
.MapGet("{greeting}/{name}", (req, res, data) =>
res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
.MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
}
Use as seguintes solicitações de navegador com o exemplo:
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Gera uma exceção com a cadeia de caracteres "ooops!"
http://localhost:5000/throw Gera uma exceção com a cadeia de caracteres "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Olá, Mundo!
bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM ) seja emitida. O aplicativo exibe a
WaitForShutdown
Start(string url, Action<IRouteBuilder> routeBuilder)
Use uma URL e uma instância de IRouteBuilder :
using (var host = WebHost.Start("http://localhost:8080", router => router
.MapGet("hello/{name}", (req, res, data) =>
res.WriteAsync($"Hello, {data.Values["name"]}!"))
.MapGet("buenosdias/{name}", (req, res, data) =>
res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
.MapGet("throw/{message?}", (req, res, data) =>
throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
.MapGet("{greeting}/{name}", (req, res, data) =>
res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
.MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
Console.WriteLine("Use Ctrl-C to shut down the host...");
}
Produz o mesmo resultado que Start(Action<IRouteBuilder> routeBuilder), mas o aplicativo responde em

StartWith(Action<IApplicationBuilder> app)
Forneça um delegado para configurar um IApplicationBuilder :
using (var host = WebHost.StartWith(app =>

app.Use(next =>
{
return async context =>
{
await context.Response.WriteAsync("Hello World!");
};
})))
{
}
Faça uma solicitação no navegador para http://localhost:5000 para receber a resposta "Olá, Mundo!"
WaitForShutdown bloqueia até que uma quebra ( Ctrl-C/SIGINT ou SIGTERM ) seja emitida. O aplicativo exibe a
StartWith(string url, Action<IApplicationBuilder> app)
Forneça um delegado e uma URL para configurar um IApplicationBuilder :
using (var host = WebHost.StartWith("http://localhost:8080", app =>

app.Use(next =>
{
return async context =>
{
};
})))
{
}
Produz o mesmo resultado que StartWith(Action<IApplicationBuilder> app), mas o aplicativo responde

em http://localhost:8080 .
Executar
O método Run inicia o aplicativo Web e bloqueia o thread de chamada até que o host seja desligado:
host.Run();
Iniciar
Execute o host sem bloqueio, chamando seu método Start :
using (host)
{
host.Start();
Console.ReadLine();
}
Se uma lista de URLs for passada para o método Start , ele escutará nas URLs especificadas:
var urls = new List<string>()

{
"http://*:5000",
"http://localhost:5001"
};

.UseKestrel()
.Start(urls.ToArray());
using (host)
{
Console.ReadLine();
}
Interface IHostingEnvironment
A interface IHostingEnvironment fornece informações sobre o ambiente de hospedagem na Web do aplicativo.
Use a injeção de construtor para obter o IHostingEnvironment para usar suas propriedades e métodos de
extensão:
public class CustomFileReader

{
public CustomFileReader(IHostingEnvironment env)

{
_env = env;
}
public string ReadFile(string filePath)

{
var fileProvider = _env.WebRootFileProvider;
// Process the file here
}
}
Uma abordagem baseada em convenção pode ser usada para configurar o aplicativo na inicialização com base
no ambiente. Como alternativa, injete o IHostingEnvironment no construtor Startup para uso em
ConfigureServices :
{
{
HostingEnvironment = env;
}
public IHostingEnvironment HostingEnvironment { get; }

{
if (HostingEnvironment.IsDevelopment())
{
// Development configuration
}
else
{
// Staging/Production configuration
}
var contentRootPath = HostingEnvironment.ContentRootPath;

}
}
NOTE
Além do método de extensão IsDevelopment , IHostingEnvironment oferece os métodos IsStaging , IsProduction
e IsEnvironment(string environmentName) . Para obter mais informações, consulte Usar vários ambientes no ASP.NET
Core.
O serviço IHostingEnvironment também pode ser injetado diretamente no método Configure para configurar o
pipeline de processamento:

{
{
// In Development, use the developer exception page
}
else
{
// In Staging/Production, route exceptions to /error
}
var contentRootPath = env.ContentRootPath;

}
IHostingEnvironment pode ser injetado no método Invoke ao criar um middleware personalizado:

public async Task Invoke(HttpContext context, IHostingEnvironment env)
{
{
// Configure middleware for Development
}
else
{
// Configure middleware for Staging/Production
}
var contentRootPath = env.ContentRootPath;

}
Interface IApplicationLifetime
IApplicationLifetime permite atividades pós-inicialização e desligamento. Três propriedades na interface são
tokens de cancelamento usados para registrar métodos Action que definem eventos de inicialização e
desligamento.
TOKEN DE CANCELAMENTO ACIONADO QUANDO…
ApplicationStarted O host foi iniciado totalmente.
ApplicationStopped O host está concluindo um desligamento normal. Todas as

solicitações devem ser processadas. O desligamento é
bloqueado até que esse evento seja concluído.
ApplicationStopping O host está executando um desligamento normal.

Solicitações ainda podem estar sendo processadas. O
desligamento é bloqueado até que esse evento seja
concluído.
{
public void Configure(IApplicationBuilder app, IApplicationLifetime appLifetime)
{
appLifetime.ApplicationStarted.Register(OnStarted);
appLifetime.ApplicationStopping.Register(OnStopping);
appLifetime.ApplicationStopped.Register(OnStopped);
Console.CancelKeyPress += (sender, eventArgs) =>

{
appLifetime.StopApplication();
// Don't terminate the process immediately, wait for the Main thread to exit gracefully.
eventArgs.Cancel = true;
};
}
private void OnStarted()

{
// Perform post-startup activities here
}
private void OnStopping()

{
// Perform on-stopping activities here
}
private void OnStopped()

{
// Perform post-stopped activities here
}
}
StopApplication solicita o término do aplicativo. A classe a seguir usa StopApplication para desligar
normalmente um aplicativo quando o método Shutdown da classe é chamado:
public class MyClass

{
private readonly IApplicationLifetime _appLifetime;
public MyClass(IApplicationLifetime appLifetime)

{
_appLifetime = appLifetime;
}
public void Shutdown()

{
_appLifetime.StopApplication();
}
}
Validação de escopo
CreateDefaultBuilder define ServiceProviderOptions.ValidateScopes como true quando o ambiente do
aplicativo é de desenvolvimento.
Quando ValidateScopes está definido como true , o provedor de serviço padrão executa verificações para
saber se:
Os serviços com escopo não são resolvidos direta ou indiretamente pelo provedor de serviço raiz.
Os serviços com escopo não são injetados direta ou indiretamente em singletons.
O provedor de serviços raiz é criado quando BuildServiceProvider é chamado. O tempo de vida do provedor de
serviço raiz corresponde ao tempo de vida do aplicativo/servidor quando o provedor começa com o aplicativo e
é descartado quando o aplicativo é desligado.
Os serviços com escopo são descartados pelo contêiner que os criou. Se um serviço com escopo é criado no
contêiner raiz, o tempo de vida do serviço é promovido efetivamente para singleton, porque ele só é descartado
pelo contêiner raiz quando o aplicativo/servidor é desligado. A validação dos escopos de serviço detecta essas
situações quando BuildServiceProvider é chamado.
Para que os escopos sempre sejam validados, incluindo no ambiente de produção, configure
ServiceProviderOptions com UseDefaultServiceProvider no construtor do host:
.UseDefaultServiceProvider((context, options) => {
options.ValidateScopes = true;
})
Solução de problemas de System.ArgumentException

O seguinte se aplica somente aos aplicativos do ASP.NET Core 2.0 quando o aplicativo não chama
UseStartup ou Configure .
Um host pode ser compilado injetando IStartup diretamente no contêiner de injeção de dependência em vez
de chamar UseStartup ou Configure :
services.AddSingleton<IStartup, Startup>();
Se o host for compilado dessa maneira, o seguinte erro poderá ocorrer:
Unhandled Exception: System.ArgumentException: A valid non-empty application name must be provided.
Isso ocorre porque o nome do aplicativo (o nome do assembly atual) é necessário para verificar se há
HostingStartupAttributes . Se o aplicativo injetar manualmente IStartup no contêiner de injeção de
dependência, adicione a seguinte chamada para WebHostBuilder com o nome do assembly especificado:
.UseSetting("applicationName", "AssemblyName")
Como alternativa, adicione um Configure fictício ao WebHostBuilder , que define o nome do aplicativo
automaticamente:
.Configure(_ => { })
Para obter mais informações, consulte Comunicado: Microsoft.Extensions.PlatformAbstractions foi removido

(comentário) e o Exemplo de StartupInjection.
Recursos adicionais
Hospedar o ASP.NET Core no Windows com o IIS
Host ASP.NET Core no Linux com Nginx
Hospedar o ASP.NET Core no Linux com o Apache
Hospedar o ASP.NET Core em um serviço Windows
Host Genérico .NET
Por Luke Latham

Os aplicativos .NET Core configuram e iniciam um host. O host é responsável pelo gerenciamento de tempo de
vida e pela inicialização do aplicativo. Este tópico aborda o Host Genérico do ASP.NET Core (HostBuilder), que é
útil para a hospedagem de aplicativos que não processam solicitações HTTP. Para cobertura do host da Web
(WebHostBuilder), veja Host da Web do ASP.NET Core.
O objetivo do Host Genérico é separar o pipeline HTTP da API de host da Web para permitir maior gama de
cenários de host. Sistema de mensagens, tarefas em segundo plano e outras cargas de trabalho não HTTP com
base no benefício do Host Genérico de recursos abrangentes, como configuração, DI (injeção de dependência) e
log.
O Host Genérico é novo no ASP.NET Core 2.1 e não é adequado para cenários de hospedagem na Web. Para
cenários de hospedagem na Web, use o host da Web. O Host Genérico está em desenvolvimento para substituir
o host da Web em uma versão futura e atuar como API do host principal em cenários HTTP e não HTTP.
Ao executar o aplicativo de exemplo no Visual Studio Code, use um terminal externo ou integrado. Não execute
o exemplo em um internalConsole .
Para definir o console no Visual Studio Code:
1. Abra o arquivo .vscode/launch.json.
2. Na configuração Inicialização do .NET Core (console), localize a entrada console. Defina o valor como
externalTerminal ou integratedTerminal .
Introdução
A biblioteca do Host Genérico está disponível no namespace Microsoft.Extensions.Hosting e é fornecida pelo
pacote Microsoft.Extensions.Hosting. O pacote Microsoft.Extensions.Hosting está incluído no metapacote
Microsoft.AspNetCore.App (ASP.NET Core 2.1 ou posterior).
IHostedService é o ponto de entrada para a execução de código. Cada implementação do IHostedService é
executada na ordem do registro de serviço em ConfigureServices. StartAsync é chamado em cada
IHostedService quando o host é iniciado, e StopAsync é chamado na ordem inversa de registro quando o host é
desligado normalmente.
Configurar um host
IHostBuilder é o principal componente usado por aplicativos e bibliotecas para inicializar, compilar e executar o
host:
public static async Task Main(string[] args)
{
var host = new HostBuilder()
.Build();
await host.RunAsync();
}
Serviços padrão
Os seguintes serviços são registrados durante a inicialização do host:
Ambiente (IHostingEnvironment)
HostBuilderContext
Configuração (IConfiguration)
IApplicationLifetime (ApplicationLifetime)
IHostLifetime (ConsoleLifetime)
IHost
Opções (AddOptions)
Registro em log (AddLogging)
Configuração do host
HostBuilder conta com as seguintes abordagens para definir os valores de configuração do host:
Construtor de configuração
Configuração do método de extensão
Construtor de configuração
A configuração do construtor de host é criada chamando ConfigureHostConfiguration na implementação
IHostBuilder. ConfigureHostConfiguration usa um IConfigurationBuilder para criar um IConfiguration para o
host. O construtor de configuração inicializa o IHostingEnvironment para uso no processo de compilação do
aplicativo.
A configuração de variável de ambiente não é adicionada por padrão. Chame AddEnvironmentVariables no
construtor de host para configurar o host com base em variáveis de ambiente. AddEnvironmentVariables aceita
um prefixo opcional definido pelo usuário. O aplicativo de exemplo usa um prefixo igual a PREFIX_ . O prefixo é
removido quando as variáveis de ambiente são lidas. Quando o host do aplicativo de exemplo é configurado, o
valor da variável de ambiente de PREFIX_ENVIRONMENT torna-se o valor de configuração de host para a chave
environment .
Durante o desenvolvimento, ao usar o Visual Studio ou executar um aplicativo com dotnet run , as variáveis de
ambiente poderão ser definidas no arquivo Properties/launchSettings.json. No Visual Studio Code, as variáveis
de ambiente podem ser definidas no arquivo .vscode/launch.json durante o desenvolvimento. Para obter mais
informações, consulte Usar vários ambientes no ASP.NET Core.
ConfigureHostConfiguration pode ser chamado várias vezes com resultados aditivos. O host usa a opção que
define um valor por último.
hostsettings.json:
{
"environment": "Development"
}
Exemplo da configuração HostBuilder usando ConfigureHostConfiguration :

.ConfigureHostConfiguration(configHost =>
{
configHost.SetBasePath(Directory.GetCurrentDirectory());
configHost.AddJsonFile("hostsettings.json", optional: true);
configHost.AddEnvironmentVariables(prefix: "PREFIX_");
configHost.AddCommandLine(args);
})
NOTE
Atualmente, o método de extensão AddConfiguration não é capaz de analisar uma seção de configuração retornada por
GetSection (por exemplo, .AddConfiguration(Configuration.GetSection("section")) ). O método GetSection filtra
as chaves de configuração da seção solicitada, mas deixa o nome da seção nas chaves (por exemplo,
section:environment ). O método AddConfiguration espera que as chaves correspondam às chaves HostBuilder
(por exemplo, environment ). A presença do nome da seção nas chaves impede que os valores da seção configurem o
host. Esse problema será corrigido em uma próxima versão. Para obter mais informações e soluções alternativas, consulte
Passar a seção de configuração para WebHostBuilder.UseConfiguration usa chaves completas.
Configuração do método de extensão

Métodos de extensão são chamados na implementação IHostBuilder para configurar a raiz do conteúdo e o
ambiente.
Chave do Aplicativo (Nome)
A propriedade IHostingEnvironment.ApplicationName é definida na configuração do host durante a construção
do host. Para definir o valor explicitamente, use o HostDefaults.ApplicationKey:
Chave: applicationName
Tipo: string
Padrão: o nome do assembly que contém o ponto de entrada do aplicativo.
Definido usando: HostBuilderContext.HostingEnvironment.ApplicationName
Variável de ambiente: <PREFIX_>APPLICATIONNAME ( <PREFIX_> é opcional e definida pelo usuário)

.ConfigureAppConfiguration((hostContext, configApp) =>
{
hostContext.HostingEnvironment.ApplicationName = "CustomApplicationName";
})
Raiz do conteúdo
Essa configuração determina onde o host começa a procurar por arquivos de conteúdo.
Chave: contentRoot
Tipo: string
Padrão: o padrão é a pasta em que o assembly do aplicativo reside.
Definido usando: UseContentRoot
Variável de ambiente: <PREFIX_>CONTENTROOT ( <PREFIX_> é opcional e definida pelo usuário)
Se o caminho não existir, o host não será iniciado.

Ambiente
Define o ambiente do aplicativo.
Chave: ambiente
Tipo: string
Padrão: Production
Definido usando: UseEnvironment
Variável de ambiente: <PREFIX_>ENVIRONMENT ( <PREFIX_> é opcional e definida pelo usuário)
O ambiente pode ser definido como qualquer valor. Os valores definidos pela estrutura incluem Development ,
Staging e Production . Os valores não diferenciam maiúsculas de minúsculas.

ConfigureAppConfiguration
A configuração do construtor de aplicativos é criada chamando ConfigureAppConfiguration na implementação
IHostBuilder. ConfigureAppConfiguration usa um IConfigurationBuilder para criar um IConfiguration para o
aplicativo. ConfigureAppConfiguration pode ser chamado várias vezes com resultados aditivos. O aplicativo usa a
opção que define um valor por último. A configuração criada pelo ConfigureAppConfiguration está disponível em
HostBuilderContext.Configuration para operações seguintes e em Serviços.
Exemplo da configuração de aplicativo usando ConfigureAppConfiguration :

.ConfigureAppConfiguration((hostContext, configApp) =>
{
configApp.SetBasePath(Directory.GetCurrentDirectory());
configApp.AddJsonFile("appsettings.json", optional: true);
configApp.AddJsonFile(
$"appsettings.{hostContext.HostingEnvironment.EnvironmentName}.json",
optional: true);
configApp.AddEnvironmentVariables(prefix: "PREFIX_");
configApp.AddCommandLine(args);
})
appsettings.json:
{
"Logging": {
"LogLevel": {
}
},
"AllowedHosts": "*"
}
appsettings.Development.json:
{
"Logging": {
"LogLevel": {
"Default": "Debug",
}
}
}
appsettings.Production.json:
{
"Logging": {
"LogLevel": {
"Default": "Error",
}
}
}
NOTE
Atualmente, o método de extensão AddConfiguration não é capaz de analisar uma seção de configuração retornada por
GetSection (por exemplo, .AddConfiguration(Configuration.GetSection("section")) ). O método GetSection filtra
as chaves de configuração da seção solicitada, mas deixa o nome da seção nas chaves (por exemplo,
section:Logging:LogLevel:Default ). O método AddConfiguration espera uma correspondência exata para chaves de
configuração (por exemplo, Logging:LogLevel:Default ). A presença do nome da seção nas chaves impede que os
valores da seção configurem o aplicativo. Esse problema será corrigido em uma próxima versão. Para obter mais
informações e soluções alternativas, consulte Passar a seção de configuração para WebHostBuilder.UseConfiguration usa
chaves completas.
Para mover arquivos de configurações para o diretório de saída, especifique os arquivos de configurações como
itens de projeto do MSBuild no arquivo de projeto. O aplicativo de exemplo move seus arquivos de
configurações do aplicativo JSON e hostsettings.json com o seguinte <conteúdo:> item:
<ItemGroup>
<Content Include="**\*.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
ConfigureServices
ConfigureServices adiciona serviços ao contêiner injeção de dependência do aplicativo. ConfigureServices pode
ser chamado várias vezes com resultados aditivos.
Um serviço hospedado é uma classe com lógica de tarefa em segundo plano que implementa a interface
IHostedService. Para obter mais informações, consulte Tarefas em segundo plano com serviços hospedados no
ASP.NET Core.
O aplicativo de exemplo usa o método de extensão AddHostedService para adicionar um serviço para eventos de
tempo de vida, LifetimeEventsHostedService , e uma tarefa em segundo plano programada, TimedHostedService ,
para o aplicativo:
.ConfigureServices((hostContext, services) =>
{
if (hostContext.HostingEnvironment.IsDevelopment())
{
// Development service configuration
}
else
{
// Non-development service configuration
}
services.AddHostedService<LifetimeEventsHostedService>();
services.AddHostedService<TimedHostedService>();
})
ConfigureLogging
ConfigureLogging adiciona um delegado para configurar o ILoggingBuilder fornecido. ConfigureLogging pode
ser chamado várias vezes com resultados aditivos.

.ConfigureLogging((hostContext, configLogging) =>
{
configLogging.AddConsole();
configLogging.AddDebug();
})
UseConsoleLifetime
UseConsoleLifetime escuta Ctrl+C /SIGINT ou SIGTERM e chama StopApplication para iniciar o processo de
desligamento. UseConsoleLifetime desbloqueia extensões como RunAsync e WaitForShutdownAsync.
ConsoleLifetime é previamente registrado como a implementação de tempo de vida padrão. O último tempo de
vida registrado é usado.

.UseConsoleLifetime()
Configuração do contêiner
Para dar suporte à conexão de outros contêineres, o host pode aceitar um IServiceProviderFactory. O
fornecimento de um alocador não faz parte do registro de contêiner de injeção de dependência, mas, em vez
disso, um host intrínseco é usado para criar o contêiner de DI concreto.
UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) substitui o alocador padrão usado
para criar o provedor de serviços do aplicativo.
A configuração de contêiner personalizado é gerenciada pelo método ConfigureContainer. ConfigureContainer
fornece uma experiência fortemente tipada para configurar o contêiner sobre a API do host subjacente.
ConfigureContainer pode ser chamado várias vezes com resultados aditivos.
Crie um contêiner de serviço para o aplicativo:

namespace GenericHostSample
{
internal class ServiceContainer
{
}
}
Forneça um alocador de contêiner de serviço:
using System;
namespace GenericHostSample
{
internal class ServiceContainerFactory : IServiceProviderFactory<ServiceContainer>
{
public ServiceContainer CreateBuilder(IServiceCollection services)
{
return new ServiceContainer();
}
public IServiceProvider CreateServiceProvider(ServiceContainer containerBuilder)

{
throw new NotImplementedException();
}
}
}
Use o alocador e configure o contêiner de serviço personalizado para o aplicativo:

.UseServiceProviderFactory<ServiceContainer>(new ServiceContainerFactory())
.ConfigureContainer<ServiceContainer>((hostContext, container) =>
{
})
Extensibilidade
Extensibilidade de host é executada com métodos de extensão em IHostBuilder . O exemplo a seguir mostra
como um método de extensão estende uma implementação do IHostBuilder com o exemplo do
TimedHostedService, demonstrado no Tarefas em segundo plano com serviços hospedados no ASP.NET Core.

.UseHostedService<TimedHostedService>()
.Build();
await host.StartAsync();
Um aplicativo estabelece o método de extensão UseHostedService para registrar o serviço hospedado passado
no T :
using System;
using Microsoft.Extensions.Hosting;
public static class Extensions

{
public static IHostBuilder UseHostedService<T>(this IHostBuilder hostBuilder)
where T : class, IHostedService, IDisposable
{
return hostBuilder.ConfigureServices(services =>
services.AddHostedService<T>());
}
}
Gerenciar o host
A implementação IHost é responsável por iniciar e parar as implementações IHostedService que estão
registradas no contêiner de serviço.
Executar
Run executa o aplicativo e bloqueia o thread de chamada até que o host seja desligado:

{
public void Main(string[] args)
{
.Build();
host.Run();
}
}
RunAsync
RunAsync executa o aplicativo e retorna um Task que é concluído quando o token de cancelamento ou o
desligamento é disparado:

{
{
.Build();
await host.RunAsync();
}
}
RunConsoleAsync
RunConsoleAsync habilita o suporte do console, compila e inicia o host e aguarda Ctrl+C /SIGINT ou
SIGTERM desligar.
{
{
var hostBuilder = new HostBuilder();
await hostBuilder.RunConsoleAsync();
}
}
Start e StopAsync
Start inicia o host de forma síncrona.
StopAsync(TimeSpan) tenta parar o host dentro do tempo limite oferecido.

{
{
.Build();
using (host)
{
host.Start();
await host.StopAsync(TimeSpan.FromSeconds(5));
}
}
}
StartAsync e StopAsync
StartAsync inicia o aplicativo.
StopAsync para o aplicativo.

{
{
.Build();
using (host)
{
await host.StopAsync();
}
}
}
WaitForShutdown
WaitForShutdown é disparado por meio de IHostLifetime, como ConsoleLifetime (escuta Ctrl+C /SIGINT ou
SIGTERM ). WaitForShutdown chama StopAsync.
{
public void Main(string[] args)
{
.Build();
using (host)
{
host.Start();
}
}
}
WaitForShutdownAsync
WaitForShutdownAsync retorna um Task que é concluído quando o desligamento é disparado por meio do
token fornecido e chama StopAsync.

{
{
.Build();
using (host)
{
await host.WaitForShutdownAsync();
}
}
}
Controle externo
O controle externo do host pode ser obtido usando os métodos que podem ser chamados externamente:
{
private IHost _host;
public Program()
{
_host = new HostBuilder()
.Build();
}
public async Task StartAsync()

{
_host.StartAsync();
}
public async Task StopAsync()

{
using (_host)
{
await _host.StopAsync(TimeSpan.FromSeconds(5));
}
}
}
IHostLifetime.WaitForStartAsync é chamado no início de StartAsync, que aguarda até que ele seja concluído
antes de continuar. Isso pode ser usado para atrasar a inicialização até que seja sinalizado por um evento
externo.
Interface IHostingEnvironment
IHostingEnvironment fornece informações sobre o ambiente de hospedagem do aplicativo. Use a injeção de
construtor para obter o IHostingEnvironment para usar suas propriedades e métodos de extensão:

{
public MyClass(IHostingEnvironment env)

{
_env = env;
}
public void DoSomething()

{
var environmentName = _env.EnvironmentName;
}
}
Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core.
Interface IApplicationLifetime
IApplicationLifetime permite atividades pós-inicialização e desligamento, inclusive solicitações de desligamento
normal. Três propriedades na interface são tokens de cancelamento usados para registrar métodos Action que
definem eventos de inicialização e desligamento.
ApplicationStarted O host foi iniciado totalmente.

ApplicationStopped O host está concluindo um desligamento normal. Todas as

solicitações devem ser processadas. O desligamento é
bloqueado até que esse evento seja concluído.
ApplicationStopping O host está executando um desligamento normal.

Solicitações ainda podem estar sendo processadas. O
desligamento é bloqueado até que esse evento seja
concluído.
O construtor injeta o serviço IApplicationLifetime em qualquer classe. O aplicativo de exemplo usa injeção de
construtor em uma classe LifetimeEventsHostedService (uma implementação IHostedService ) para registrar os
eventos.
LifetimeEventsHostedService.cs:
internal class LifetimeEventsHostedService : IHostedService
{
public LifetimeEventsHostedService(
ILogger<LifetimeEventsHostedService> logger, IApplicationLifetime appLifetime)
{
_logger = logger;
}
public Task StartAsync(CancellationToken cancellationToken)

{
_appLifetime.ApplicationStarted.Register(OnStarted);
_appLifetime.ApplicationStopping.Register(OnStopping);
_appLifetime.ApplicationStopped.Register(OnStopped);
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken)

{
}
private void OnStarted()

{
_logger.LogInformation("OnStarted has been called.");
// Perform post-startup activities here

}
private void OnStopping()

{
_logger.LogInformation("OnStopping has been called.");
// Perform on-stopping activities here

}
private void OnStopped()

{
_logger.LogInformation("OnStopped has been called.");
// Perform post-stopped activities here

}
}
StopApplication solicita o término do aplicativo. A classe a seguir usa StopApplication para desligar
normalmente um aplicativo quando o método Shutdown da classe é chamado:
{
public MyClass(IApplicationLifetime appLifetime)

{
}
public void Shutdown()

{
_appLifetime.StopApplication();
}
}
Recursos adicionais
Tarefas em segundo plano com serviços hospedados no ASP.NET Core
Hospedagem de exemplos do repositório no GitHub
Implementações de servidor Web em ASP.NET Core
Por Tom Dykstra, Steve Smith, Stephen Halter e Chris Ross

Um aplicativo ASP.NET Core é executado com uma implementação do servidor HTTP em processo. A
implementação do servidor escuta solicitações HTTP e as coloca na superfície para o aplicativo como conjuntos
de recursos de solicitação compostos em um HttpContext.
O ASP.NET Core é fornecido com as seguintes implementações de servidor:
O Kestrel é o servidor HTTP de plataforma cruzada padrão para o ASP.NET Core.
IISHttpServer é usado com o modelo de hospedagem em processo e o Módulo do ASP.NET Core no
Windows.
O HTTP.sys é um servidor HTTP somente do Windows com base no driver do kernel HTTP.sys e na API do
servidor HTTP. (O HTTP.sys é chamado WebListener no ASP.NET Core 1.x.)
O Kestrel é o servidor HTTP de plataforma cruzada padrão para o ASP.NET Core.
O HTTP.sys é um servidor HTTP somente do Windows com base no driver do kernel HTTP.sys e na API do
servidor HTTP. (O HTTP.sys é chamado WebListener no ASP.NET Core 1.x.)
Kestrel
O Kestrel é o servidor Web padrão incluído nos modelos de projeto do ASP.NET Core.
O Kestrel pode ser usado sozinho ou com um servidor proxy reverso como IIS, Nginx ou Apache. Um servidor
proxy reverso recebe solicitações HTTP da Internet e as encaminha para o Kestrel após algum tratamento
preliminar.
Qualquer configuração —com ou sem um servidor proxy reverso— é uma configuração de hospedagem válida
e compatível com o ASP.NET Core 2.0 ou aplicativos posteriores. Para obter mais informações, consulte
Quando usar Kestrel com um proxy reverso.
Se o aplicativo aceita somente solicitações de uma rede interna, o Kestrel pode ser usado sozinho.
Se o aplicativo for exposto à Internet, o Kestrel deverá usar o IIS, o Nginx ou o Apache como um servidor proxy
reverso. Um servidor proxy reverso recebe solicitações HTTP da Internet e as encaminha para o Kestrel após
algum tratamento preliminar, conforme mostrado no diagrama a seguir:
O motivo mais importante para usar um proxy reverso para implantações de servidores de borda voltados para
o público que são expostas diretamente na Internet é a segurança. As versões 1.x do Kestrel não têm recursos de
segurança importantes para proteção contra ataques da Internet. Isso inclui, mas não se limita aos tempos
limite, limites de tamanho da solicitação e limites de conexões simultâneas apropriados.
Para obter mais informações, consulte Quando usar Kestrel com um proxy reverso.
O IIS, o Nginx ou o Apache não podem ser usados sem o Kestrel ou uma implementação de servidor
personalizado. O ASP.NET Core foi projetado para ser executado em seu próprio processo, de modo que ele
pode se comportar de forma consistente entre plataformas. O IIS, o Nginx e o Apache determinam seu próprio
procedimento de inicialização e o ambiente. Para usar essas tecnologias de servidor diretamente, o ASP.NET
Core precisaria adaptar-se aos requisitos de cada servidor. Usando uma implementação do servidor Web, tal
como Kestrel, o ASP.NET Core tem controle sobre o processo de inicialização e o ambiente quando hospedado
em tecnologias de servidor diferentes.
IIS com Kestrel
Ao usar o IIS ou o IIS Express, o aplicativo do ASP.NET Core é executado no mesmo processo que o processo
de trabalho do IIS (o modelo de hospedagem em processo) ou em um processo de trabalho separado do IIS (o
modelo de hospedagem fora do processo).
O Módulo do ASP.NET Core é um módulo nativo do IIS que manipula solicitações nativas do IIS entre o
servidor HTTP em processo do IIS ou o servidor Kestrel fora do processo. Para obter mais informações, consulte
Módulo do ASP.NET Core.
Ao usas o IIS ou IIS Express como um proxy reverso para o ASP.NET Core, o aplicativo ASP.NET Core é
executado em um processo separado do processo de trabalho do IIS. No processo do IIS, o Módulo do
ASP.NET Core coordena a relação do proxy reverso. As funções primárias do módulo do ASP.NET Core são
iniciar o aplicativo do ASP.NET Core, reiniciá-lo quando ele falhar e encaminhar o tráfego HTTP para o
aplicativo. Para obter mais informações, consulte Módulo do ASP.NET Core.
Nginx com Kestrel
Para obter informações sobre como usar Nginx no Linux como um servidor proxy reverso para Kestrel, veja
Hospedar em Linux com o Nginx.
Apache com Kestrel
Para obter informações sobre como usar Apache no Linux como um servidor proxy reverso para Kestrel, veja
Hospedar em Linux com o Apache.
HTTP.sys
Se os aplicativos ASP.NET Core forem executados no Windows, o HTTP.sys será uma alternativa ao Kestrel. O
Kestrel geralmente é recomendado para melhor desempenho. O HTTP.sys pode ser usado em cenários em que
o aplicativo é exposto à Internet e as funcionalidades necessárias são compatíveis com HTTP.sys, mas não com
Kestrel. Para obter informações sobre HTTP.sys, veja HTTP.sys.
O HTTP.sys também pode ser usado para aplicativos que são expostos somente a uma rede interna.
O HTTP.sys é chamado WebListener no ASP.NET Core 1.x. Se os aplicativos ASP.NET Core forem executados
no Windows, o WebListener será uma alternativa para cenários em que o IIS não está disponível para hospedar
aplicativos.
O WebListener também poderá ser usado no lugar do Kestrel para aplicativos expostos somente a uma rede
interna se as funcionalidades necessárias forem compatíveis com o WebListener, mas não com o Kestrel. Para
obter mais informações sobre o WebListener, consulte WebListener.
Infraestrutura de servidor do ASP.NET Core

O IApplicationBuilder disponível no método Startup.Configure expõe a propriedade ServerFeatures do tipo
IFeatureCollection. Kestrel e HTTP.sys (WebListener no ASP.NET Core 1.x) expõem apenas um único recurso
cada, IServerAddressesFeature, mas as implementações de servidor diferentes podem expor funcionalidade
adicional.
IServerAddressesFeature pode ser usado para descobrir a qual porta a implementação do servidor se acoplou
durante o tempo de execução.
Servidores personalizados
Se os servidores internos não atenderem aos requisitos do aplicativo, um servidor personalizado poderá ser
criado. O Guia de OWIN (Open Web Interface para .NET) demonstra como gravar uma implementação de
IServer com base em Nowin. Somente as interfaces de recurso que o aplicativo usa exigem implementação.
Porém, no mínimo IHttpRequestFeature e IHttpResponseFeature devem ter suporte.
Inicialização do servidor
Ao usar o Visual Studio, o Visual Studio para Mac ou o Visual Studio Code, o servidor é iniciado quando o
aplicativo é iniciado pelo IDE (ambiente de desenvolvimento integrado). No Visual Studio no Windows, os perfis
de inicialização podem ser usados para iniciar o aplicativo e o servidor com o IIS Express/Módulo do ASP.NET
Core ou o console. No Visual Studio Code, o aplicativo e o servidor são iniciados por Omnisharp, que ativa o
depurador CoreCLR. Usando o Visual Studio para Mac, o aplicativo e o servidor são iniciados pelo depurador de
modo reversível Mono.
Ao iniciar um aplicativo com um prompt de comando na pasta do projeto, a execução dotnet inicia o aplicativo e
o servidor (somente no Kestrel e no HTTP.sys). A configuração é especificada pela opção -c|--configuration ,
que é definida como Debug (padrão) ou Release . Se os perfis de inicialização estiverem presentes em um
arquivo launchSettings.json, use a opção --launch-profile <NAME> para definir o perfil de inicialização (por
exemplo, Development ou Production ). Para obter mais informações, veja os tópicos execução dotnet e
Empacotamento de distribuição do .NET Core.
Compatibilidade com HTTP/2
O HTTP/2 é compatível com ASP.NET Core nos seguintes cenários de implantação:
Kestrel
Sistema operacional
Windows Server 2012 R2/Windows 8.1 ou posterior
Linux com OpenSSL 1.0.2 ou posterior (por exemplo, Ubuntu 16.04 ou posterior)
O HTTP/2 será compatível com macOS em uma versão futura.
Estrutura de destino: .NET Core 2.2 ou posterior
HTTP.sys
Windows Server 2016/Windows 10 ou posterior
Estrutura de destino: não aplicável a implantações de HTTP.sys.
IIS (em processo)
Windows Server 2016/Windows 10 ou posterior; IIS 10 ou posterior
IIS (fora do processo)
Conexões de servidor de borda voltadas para o público usam HTTP/2, mas a conexão de proxy
reverso para o Kestrel usa HTTP/1.1.
Estrutura de destino: não aplicável a implantações IIS fora de processo.
HTTP.sys
Estrutura de destino: não aplicável a implantações de HTTP.sys.
IIS (fora do processo)
reverso para o Kestrel usa HTTP/1.1.
Estrutura de destino: não aplicável a implantações IIS fora de processo.
Uma conexão HTTP/2 precisa usar ALPN (Application-Layer Protocol Negotiation) e TLS 1.2 ou posterior. Para
obter mais informações, consulte os tópicos referentes aos seus cenários de implantação do servidor.
Recursos adicionais
Implementação do servidor Web Kestrel no ASP.NET Core
Implementação do servidor Web HTTP.sys no ASP.NET Core (para ASP.NET Core 1.x, consulte
Implementação do servidor Web WebListener no ASP.NET Core )
Implementação do servidor Web Kestrel no
ASP.NET Core
Por Tom Dykstra, Chris Ross e Stephen Halter

O Kestrel é um servidor Web multiplataforma para o ASP.NET Core. O Kestrel é o servidor Web que está
incluído por padrão em modelos de projeto do ASP.NET Core.
O Kestrel dá suporte aos seguintes recursos:
HTTPS
Atualização do Opaque usado para habilitar o WebSockets
Soquetes do UNIX para alto desempenho protegidos pelo Nginx
HTTP/2 (exceto em macOS†)
†O HTTP/2 será compatível com macOS em uma versão futura.
HTTPS
Atualização do Opaque usado para habilitar o WebSockets
Soquetes do UNIX para alto desempenho protegidos pelo Nginx
Há suporte para o Kestrel em todas as plataformas e versões compatíveis com o .NET Core.

O HTTP/2 estará disponível para aplicativos ASP.NET Core se os seguintes requisitos básicos forem
atendidos:
Sistema operacional†
Windows Server 2012 R2/Windows 8.1 ou posterior
Linux com OpenSSL 1.0.2 ou posterior (por exemplo, Ubuntu 16.04 ou posterior)
Conexão ALPN (Negociação de protocolo de camada de aplicativo)
Conexão TLS 1.2 ou posterior
†O HTTP/2 será compatível com macOS em uma versão futura.
Se uma conexão HTTP/2 for estabelecida, HttpRequest.Protocol relatará HTTP/2 .
HTTP/2 está desabilitado por padrão. Para obter mais informações sobre a configuração, consulte as
seções Opções do Kestrel e Configuração de ponto de extremidade.
Quando usar o Kestrel com um proxy reverso

Você pode usar o Kestrel sozinho ou com um servidor proxy reverso como IIS, Nginx ou Apache. Um
servidor proxy reverso recebe solicitações HTTP da Internet e as encaminha para o Kestrel após algum
tratamento preliminar.
Qualquer configuração —com ou sem um servidor proxy reverso— é uma configuração de hospedagem
válida e compatível com o ASP.NET Core 2.0 ou aplicativos posteriores.
Se um aplicativo aceitar solicitações somente de uma rede interna, o Kestrel poderá ser usado
diretamente como o servidor do aplicativo.
Se você expõe o aplicativo à Internet, use o IIS, o Nginx ou o Apache como um servidor proxy reverso.
Um servidor proxy reverso recebe solicitações HTTP da Internet e as encaminha para o Kestrel após
algum tratamento preliminar.
Um proxy reverso é necessário para implantações de servidor de borda voltado para o público (expostas
ao tráfego da Internet) por motivos de segurança. As versões 1.x do Kestrel não têm um conjunto
completo de defesas contra ataques, como tempos limite, limites de tamanho e limites de conexões
simultâneas apropriados.
Um cenário de proxy reverso existe quando há vários aplicativos que compartilham o mesmo IP e a
mesma porta em execução em um único servidor. O Kestrel não é compatível com esse cenário porque
ele não permite compartilhar o mesmo IP e a mesma porta entre vários processos. Quando o Kestrel é
configurado para escutar em uma porta, ele lida com todo o tráfego dessa porta, independentemente do
cabeçalho do host das solicitações. Um proxy reverso que pode compartilhar portas tem a capacidade de
encaminhar solicitações ao Kestrel em um IP e em uma porta exclusivos.
Mesmo se um servidor proxy reverso não for necessário, usar um servidor proxy reverso poderá ser uma
boa opção:
Ele pode limitar a área da superfície pública exposta dos aplicativos que hospeda.
Ele fornece uma camada adicional de defesa e de configuração.
Pode ser integrado melhor à infraestrutura existente.
Ele simplifica a configuração de SSL e o balanceamento de carga. Somente o servidor proxy reverso
exige um certificado SSL e esse servidor pode se comunicar com os servidores de aplicativos na rede
interna usando HTTP simples.
WARNING
Se você não estiver usando um proxy reverso com a filtragem de host habilitada, a filtragem de host deverá ser
habilitada.
Como usar o Kestrel em aplicativos ASP.NET Core
O pacote Microsoft.AspNetCore.Server.Kestrel está incluído no metapacote Microsoft.AspNetCore.App
(ASP.NET Core 2.1 ou posterior).
Os modelos de projeto do ASP.NET Core usam o Kestrel por padrão. Em Program.cs, o código do
modelo chama CreateDefaultBuilder, que chama UseKestrel em segundo plano.

{
}

Para fornecer configuração adicional após chamar CreateDefaultBuilder , use ConfigureKestrel :

{
// Set properties and call methods on options
});
Para fornecer configuração adicional após chamar CreateDefaultBuilder , chame UseKestrel:

{
// Set properties and call methods on options
})
.Build();
Instale o pacote NuGet Microsoft.AspNetCore.Server.Kestrel.

Chame o método de extensão UseKestrel no WebHostBuilder no método Main , especificando as opções
do Kestrel necessárias, conforme é mostrado na próxima seção.
{
Console.WriteLine("Running demo with Kestrel.");

.Build();
var builder = new WebHostBuilder()

{
if (config["threadCount"] != null)
{
options.ThreadCount = int.Parse(config["threadCount"]);
}
})
.UseUrls("http://localhost:5000");
var host = builder.Build();

host.Run();
}
Opções do Kestrel
O servidor Web do Kestrel tem opções de configuração de restrição especialmente úteis em implantações
para a Internet. Alguns limites importantes que podem ser personalizados:
Número máximo de conexões de cliente
Tamanho máximo do corpo da solicitação
Taxa de dados mínima do corpo da solicitação
Defina essas e outras restrições na propriedade Limites da classe KestrelServerOptions. A propriedade
Limits contém uma instância da classe KestrelServerLimits.

MaxConcurrentConnections
MaxConcurrentUpgradedConnections
O número máximo de conexões TCP abertas simultâneas pode ser definido para o aplicativo inteiro com
o código a seguir:

{
options.Limits.MaxConcurrentConnections = 100;
options.Limits.MaxConcurrentUpgradedConnections = 100;
options.Limits.MaxRequestBodySize = 10 * 1024;
options.Limits.MinRequestBodyDataRate =
new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
options.Limits.MinResponseDataRate =
options.Listen(IPAddress.Loopback, 5000);
options.Listen(IPAddress.Loopback, 5001, listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testPassword");
});
});
{
});
Há um limite separado para conexões que foram atualizadas do HTTP ou HTTPS para outro protocolo
(por exemplo, em uma solicitação do WebSockets). Depois que uma conexão é atualizada, ela não é
contada em relação ao limite de MaxConcurrentConnections .

{
{
});
});

{
});
O número máximo de conexões é ilimitado (nulo) por padrão.

MaxRequestBodySize
O tamanho máximo do corpo da solicitação padrão é de 30.000.000 bytes, que equivale
aproximadamente a 28,6 MB.
A abordagem recomendada para substituir o limite em um aplicativo ASP.NET Core MVC é usar o
atributo RequestSizeLimit em um método de ação:
[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()
Aqui está um exemplo que mostra como configurar a restrição para o aplicativo em cada solicitação:
{
{
});
});

{
});
Substitua a configuração em uma solicitação específica no middleware:

{
context.Features.Get<IHttpMaxRequestBodySizeFeature>()
.MaxRequestBodySize = 10 * 1024;
context.Features.Get<IHttpMinRequestBodyDataRateFeature>()
.MinDataRate = new MinDataRate(bytesPerSecond: 100,
gracePeriod: TimeSpan.FromSeconds(10));
context.Features.Get<IHttpMinResponseDataRateFeature>()
Uma exceção será gerada se você tentar configurar o limite em uma solicitação depois que o aplicativo
começar a ler a solicitação. Há uma propriedade IsReadOnly que indica se a propriedade
MaxRequestBodySize está no estado somente leitura, o que significa que é tarde demais para configurar o
limite.
MinRequestBodyDataRate
MinResponseDataRate
O Kestrel verifica a cada segundo se os dados estão sendo recebidos na taxa especificada em
bytes/segundo. Se a taxa cair abaixo do mínimo, a conexão atingirá o tempo limite. O período de cortesia
é o tempo que o Kestrel fornece ao cliente para aumentar sua taxa de envio até o mínimo; a taxa não é
verificada durante esse período. O período de cortesia ajuda a evitar a remoção de conexões que
inicialmente enviam dados em uma taxa baixa devido ao início lento do TCP.
A taxa mínima de padrão é de 240 bytes/segundo com um período de cortesia de 5 segundos.
Uma taxa mínima também se aplica à resposta. O código para definir o limite de solicitação e o limite de
resposta é o mesmo, exceto por ter RequestBody ou Response nos nomes da propriedade e da interface.
Este é um exemplo que mostra como configurar as taxas mínima de dados em Program.cs:
{
{
});
});

{
});
Configure as taxas por solicitação no middleware:

{
context.Features.Get<IHttpMinRequestBodyDataRateFeature>()
context.Features.Get<IHttpMinResponseDataRateFeature>()
Fluxos máximos por conexão

O Http2.MaxStreamsPerConnection limita o número de fluxos de solicitações simultâneas por conexão
HTTP/2. Os fluxos em excesso são recusados.

{
options.Limits.Http2.MaxStreamsPerConnection = 100;
});
O valor padrão é 100.

Tamanho da tabela de cabeçalho
O decodificador HPACK descompacta os cabeçalhos HTTP para conexões HTTP/2. O
Http2.HeaderTableSize limita o tamanho da tabela de compactação de cabeçalho usada pelo
decodificador HPACK. O valor é fornecido em octetos e deve ser maior do que zero (0).
{
options.Limits.Http2.HeaderTableSize = 4096;
});
O valor padrão é 4096.

Tamanho máximo do quadro
O Http2.MaxFrameSize indica o tamanho máximo do payload do quadro da conexão HTTP/2 a ser
recebido. O valor é fornecido em octetos e deve estar entre 2^14 (16.384) e 2^24-1 (16.777.215).

{
options.Limits.Http2.MaxFrameSize = 16384;
});
O valor padrão é 2^14 (16.384).

Para obter informações sobre outras opções e limites do Kestrel, confira:
KestrelServerOptions
KestrelServerLimits
ListenOptions
Para obter informações sobre as opções e os limites do Kestrel, confira:
Classe KestrelServerOptions
KestrelServerLimits
Configuração do ponto de extremidade

Por padrão, o ASP.NET Core é associado a http://localhost:5000 . Chame os métodos Listen ou
ListenUnixSocket em KestrelServerOptions para configurar portas e prefixos de URL para o Kestrel.
UseUrls , o argumento de linha de comando --urls , a chave de configuração de host urls e a variável
de ambiente ASPNETCORE_URLS também funcionam mas têm limitações que serão indicadas mais adiante
nesta seção.
A chave de configuração de host urls precisa vir da configuração do host, não da configuração do
aplicativo. Adicionar uma chave e um valor de urls para appsettings.json não afeta a configuração do
host porque o host está completamente inicializado quando a configuração é lida no arquivo de
configuração. No entanto, uma chave urls em appsettings.json pode ser usada com UseConfiguration
no construtor de host para configurar o host:
.AddJsonFile("appSettings.json", optional: true, reloadOnChange: true)
.Build();

.UseKestrel()
.Build();
Por padrão, o ASP.NET Core associa a:

http://localhost:5000
https://localhost:5001 (quando um certificado de desenvolvimento local está presente)
Um certificado de desenvolvimento é criado:

Quando o SDK do .NET Core está instalado.
A ferramenta dev-certs é usada para criar um certificado.
Alguns navegadores exigem que você conceda permissão explícita para o navegador para confiar no
certificado de desenvolvimento local.
Os modelos de projeto do ASP.NET Core 2.1 e posteriores configuram os aplicativos para serem
executados em HTTPS, por padrão, e incluem o Redirecionamento de HTTPS e o suporte a HSTS .
Chame os métodos Listen ou ListenUnixSocket em KestrelServerOptions para configurar portas e
prefixos de URL para o Kestrel.
UseUrls , o argumento de linha de comando --urls , a chave de configuração de host urls e a variável
de ambiente ASPNETCORE_URLS também funcionam mas têm limitações que serão indicadas mais adiante
nesta seção (um certificado padrão precisa estar disponível para a configuração do ponto de extremidade
HTTPS ).
Configuração do ASP.NET Core 2.1 KestrelServerOptions :
ConfigureEndpointDefaults(Action<ListenOptions>)
Especifica uma Action de configuração a ser executada para cada ponto de extremidade especificado.
Chamar ConfigureEndpointDefaults várias vezes substitui as Action s pela última Action especificada.
ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)
Especifica uma Action de configuração a ser executada para cada ponto de extremidade HTTPS. Chamar
ConfigureHttpsDefaults várias vezes substitui as Action s pela última Action especificada.
Configure (IConfiguration)
Cria um carregador de configuração para configurar o Kestrel que usa uma IConfiguration como entrada.
A configuração precisa estar no escopo da seção de configuração do Kestrel.
ListenOptions.UseHttps
Configure o Kestrel para usar HTTPS.
Extensões ListenOptions.UseHttps :
UseHttps – Configure o Kestrel para usar HTTPS com o certificado padrão. Gera uma exceção
quando não há nenhum certificado padrão configurado.
UseHttps(string fileName)
UseHttps(string fileName, string password)
UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(StoreName storeName, string subject)
UseHttps(StoreName storeName, string subject, bool allowInvalid)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location,
Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(X509Certificate2 serverCertificate)
UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions>
configureOptions)
UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)
Parâmetros de ListenOptions.UseHttps :
filename é o caminho e o nome do arquivo de um arquivo de certificado, relativo ao diretório que
contém os arquivos de conteúdo do aplicativo.
password é a senha necessária para acessar os dados do certificado X.509 .
configureOptions é uma Action para configurar as HttpsConnectionAdapterOptions . Retorna o
ListenOptions .
storeName é o repositório de certificados do qual o certificado deve ser carregado.
subject é o nome da entidade do certificado.
allowInvalid indica se certificados inválidos devem ser considerados, como os certificados
autoassinados.
location é o local do repositório do qual o certificado deve ser carregado.
serverCertificate é o certificado X.509.
Em produção, HTTPS precisa ser configurado explicitamente. No mínimo, um certificado padrão precisa
ser fornecido.
Configurações com suporte descritas a seguir:
Nenhuma configuração
Substituir o certificado padrão da configuração
Alterar os padrões no código
Nenhuma configuração
O Kestrel escuta em http://localhost:5000 e em https://localhost:5001 (se houver um certificado
padrão disponível).
Especificar URLs usando:
A variável de ambiente ASPNETCORE_URLS .
O argumento de linha de comando --urls .
A chave de configuração do host urls .
O método de extensão UseUrls .
Para obter mais informações, confira URLs de servidor e Substituir configuração.

O valor fornecido usando essas abordagens pode ser um ou mais pontos de extremidade HTTP e HTTPS
(HTTPS se houver um certificado padrão). Configure o valor como uma lista separada por ponto e
vírgula (por exemplo, "Urls": "http://localhost:8000; http://localhost:8001" ).
Substituir o certificado padrão da configuração
WebHost.CreateDefaultBuilder chama
serverOptions.Configure(context.Configuration.GetSection("Kestrel")) por padrão ao carregar a
configuração do Kestrel. Há um esquema de definições de configurações de aplicativo HTTPS padrão
disponível para o Kestrel. Configure vários pontos de extremidade, incluindo URLs e os certificados a
serem usados, por meio de um arquivo no disco ou de um repositório de certificados.
No exemplo de appsettings.json a seguir:
Defina AllowInvalid como true para permitir o uso de certificados inválidos (por exemplo, os
certificados autoassinados).
Todo ponto de extremidade HTTPS que não especificar um certificado ( HttpsDefaultCert no
exemplo a seguir) será revertido para o certificado definido em Certificados > Padrão ou para o
certificado de desenvolvimento.
{
"Kestrel": {
"EndPoints": {
"Http": {
"Url": "http://localhost:5000"
},
"HttpsInlineCertFile": {
"Url": "https://localhost:5001",
"Certificate": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
},
"HttpsInlineCertStore": {
"Certificate": {
"Subject": "<subject; required>",
"Store": "<certificate store; defaults to My>",
"Location": "<location; defaults to CurrentUser>",
"AllowInvalid": "<true or false; defaults to false>"
}
},
"HttpsDefaultCert": {
"Url": "https://localhost:5003"
},
"Https": {
"Url": "https://*:5004",
"Certificate": {
}
}
},
"Certificates": {
"Default": {
}
}
}
}
Uma alternativa ao uso de Caminho e Senha para qualquer nó de certificado é especificar o certificado
usando campos de repositório de certificados. Por exemplo, o certificado Certificados > Padrão pode
ser especificado como:
"Default": {
"Subject": "<subject; required>",
"Store": "<cert store; defaults to My>",
"Location": "<location; defaults to CurrentUser>",
"AllowInvalid": "<true or false; defaults to false>"
}
Observações do esquema:
Os nomes de pontos de extremidade diferenciam maiúsculas de minúsculas. Por exemplo, HTTPS
e Https são válidos.
O parâmetro Url é necessário para cada ponto de extremidade. O formato desse parâmetro é o
mesmo que o do parâmetro de configuração de Urls de nível superior, exceto que ele é limitado a
um único valor.
Esses pontos de extremidade substituem aqueles definidos na configuração de Urls de nível
superior em vez de serem adicionados a eles. Os pontos de extremidade definidos no código por
meio de Listen são acumulados com os pontos de extremidade definidos na seção de
configuração.
A seção Certificate é opcional. Se a seção Certificate não for especificada, os padrões
definidos nos cenários anteriores serão usados. Se não houver nenhum padrão disponível, o
servidor gerará uma exceção e não poderá ser iniciado.
A seção Certificate é compatível com os certificados de Caminho–Senha e
Entidade–Repositório.
Qualquer número de pontos de extremidade pode ser definido dessa forma, contanto que eles não
causem conflitos de porta.
options.Configure(context.Configuration.GetSection("Kestrel")) retorna um
com um método .Endpoint(string name, options => { }) que pode
KestrelConfigurationLoader
ser usado para complementar as definições de um ponto de extremidade configurado:
options.Configure(context.Configuration.GetSection("Kestrel"))
.Endpoint("HTTPS", opt =>
{
opt.HttpsOptions.SslProtocols = SslProtocols.Tls12;
});
Você também pode acessar o KestrelServerOptions.ConfigurationLoader diretamente para

continuar a iteração no carregador existente, como aquele fornecido pelo
WebHost.CreateDefaultBuilder.
A seção de configuração de cada ponto de extremidade está disponível nas opções no método
Endpoint para que as configurações personalizadas possam ser lidas.
Várias configurações podem ser carregadas chamando

options.Configure(context.Configuration.GetSection("Kestrel")) novamente com outra seção.
Somente a última configuração será usada, a menos que Load seja chamado explicitamente nas
instâncias anteriores. O metapacote não chama Load , portanto, sua seção de configuração padrão
pode ser substituída.
O KestrelConfigurationLoader espelha a família de APIs Listen de KestrelServerOptions como
sobrecargas de Endpoint , portanto, os pontos de extremidade de código e de configuração podem
ser configurados no mesmo local. Essas sobrecargas não usam nomes e consomem somente as
definições padrão da configuração.
Alterar os padrões no código
ConfigureEndpointDefaults e podem ser usados para alterar as configurações
ConfigureHttpsDefaults
padrão de ListenOptions e HttpsConnectionAdapterOptions , incluindo a substituição do certificado padrão
especificado no cenário anterior. ConfigureEndpointDefaults e ConfigureHttpsDefaults devem ser
chamados antes que qualquer ponto de extremidade seja configurado.
options.ConfigureEndpointDefaults(opt =>
{
opt.NoDelay = true;
});
options.ConfigureHttpsDefaults(httpsOptions =>
{
httpsOptions.SslProtocols = SslProtocols.Tls12;
});
Suporte do Kestrel para SNI

A SNI (Indicação de Nome de Servidor) pode ser usada para hospedar vários domínios no mesmo
endereço IP e na mesma porta. Para que a SNI funcione, o cliente envia o nome do host da sessão segura
para o servidor durante o handshake TLS para que o servidor possa fornecer o certificado correto. O
cliente usa o certificado fornecido para a comunicação criptografada com o servidor durante a sessão
segura que segue o handshake TLS.
O Kestrel permite a SNI por meio do retorno de chamada do ServerCertificateSelector . O retorno de
chamada é invocado uma vez por conexão para permitir que o aplicativo inspecione o nome do host e
selecione o certificado apropriado.
O suporte para SNI requer:
Execução na estrutura de destino netcoreapp2.1 . No netcoreapp2.0 e no net461 , o retorno de
chamada é invocado, mas o name é sempre null . O name também será null se o cliente não
fornecer o parâmetro de nome do host no handshake TLS.
Todos os sites executados na mesma instância do Kestrel. Kestrel não é compatível com o
compartilhamento de endereço IP e porta entre várias instâncias sem um proxy reverso.
{
options.ListenAnyIP(5005, listenOptions =>
{
listenOptions.UseHttps(httpsOptions =>
{
var localhostCert = CertificateLoader.LoadFromStoreCert(
"localhost", "My", StoreLocation.CurrentUser,
allowInvalid: true);
var exampleCert = CertificateLoader.LoadFromStoreCert(
"example.com", "My", StoreLocation.CurrentUser,
var subExampleCert = CertificateLoader.LoadFromStoreCert(
"sub.example.com", "My", StoreLocation.CurrentUser,
var certs = new Dictionary<string, X509Certificate2>(
StringComparer.OrdinalIgnoreCase);
certs["localhost"] = localhostCert;
certs["example.com"] = exampleCert;
certs["sub.example.com"] = subExampleCert;
httpsOptions.ServerCertificateSelector = (connectionContext, name) =>

{
if (name != null && certs.TryGetValue(name, out var cert))
{
return cert;
}
return exampleCert;
};
});
});
});
.UseKestrel((context, options) =>
{
options.ListenAnyIP(5005, listenOptions =>
{
listenOptions.UseHttps(httpsOptions =>
{
var localhostCert = CertificateLoader.LoadFromStoreCert(
"localhost", "My", StoreLocation.CurrentUser,
var exampleCert = CertificateLoader.LoadFromStoreCert(
"example.com", "My", StoreLocation.CurrentUser,
var subExampleCert = CertificateLoader.LoadFromStoreCert(
"sub.example.com", "My", StoreLocation.CurrentUser,
var certs = new Dictionary<string, X509Certificate2>(
StringComparer.OrdinalIgnoreCase);
certs["localhost"] = localhostCert;
certs["example.com"] = exampleCert;
certs["sub.example.com"] = subExampleCert;
httpsOptions.ServerCertificateSelector = (connectionContext, name) =>

{
if (name != null && certs.TryGetValue(name, out var cert))
{
return cert;
}
return exampleCert;
};
});
});
})
.Build();
Associar a um soquete TCP

O método Listen é associado a um soquete TCP e um lambda de opções permite a configuração do
certificado SSL:

{
}

{
{
});
});
{
}

{
{
});
});
O exemplo configura o SSL para um ponto de extremidade com ListenOptions. Use a mesma API para
definir outras configurações do Kestrel para pontos de extremidade específicos.
No Windows, é possível criar certificados autoassinados usando o cmdlet New -SelfSignedCertificate do
PowerShell. Para ver um exemplo sem suporte, confira UpdateIISExpressSSLForChrome.ps1.
Nas plataformas macOS, Linux e Windows, é possível criar certificados usando o OpenSSL.
Associar a um soquete do UNIX
Escute em um soquete Unix com ListenUnixSocket para melhorar o desempenho com o Nginx, como é
mostrado neste exemplo:

{
options.ListenUnixSocket("/tmp/kestrel-test.sock");
options.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testpassword");
});
});

{
options.ListenUnixSocket("/tmp/kestrel-test.sock");
options.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testpassword");
});
});
Porta 0
Quando o número da porta 0 for especificado, o Kestrel se associará dinamicamente a uma porta
disponível. O exemplo a seguir mostra como determinar a qual porta o Kestrel realmente se associou no
tempo de execução:
{
var serverAddressesFeature =
app.ServerFeatures.Get<IServerAddressesFeature>();

{
await context.Response
.WriteAsync("<!DOCTYPE html><html lang=\"en\"><head>" +
"<title></title></head><body><p>Hosted by Kestrel</p>");
if (serverAddressesFeature != null)
{
.WriteAsync("<p>Listening on the following addresses: " +
string.Join(", ", serverAddressesFeature.Addresses) +
"</p>");
}
await context.Response.WriteAsync("<p>Request URL: " +

$"{context.Request.GetDisplayUrl()}<p>");
});
}
Quando o aplicativo é executado, a saída da janela do console indica a porta dinâmica na qual o aplicativo
pode ser acessado:
Listening on the following addresses: http://127.0.0.1:48508
Limitações
Configure pontos de extremidade com as seguintes abordagens:
UseUrls
O argumento de linha de comando --urls
A chave de configuração do host urls
A variável de ambiente ASPNETCORE_URLS
Esses métodos são úteis para fazer com que o código funcione com servidores que não sejam o Kestrel.
No entanto, esteja ciente das seguintes limitações:
O protocolo SSL não pode ser usado com essas abordagens, a menos que um certificado padrão seja
fornecido na configuração do ponto de extremidade HTTPS (por exemplo, usando a configuração
KestrelServerOptions ou um arquivo de configuração, como já foi mostrado neste tópico).
Quando ambas as abordagens, Listen e UseUrls , são usadas ao mesmo tempo, os pontos de
extremidade de Listen substituem os pontos de extremidade de UseUrls .
Configuração de ponto de extremidade do IIS
Ao usar o IIS, as associações de URL para IIS substituem as associações definidas por Listen ou
UseUrls . Para obter mais informações, confira o tópico Módulo do ASP.NET Core.
Por padrão, o ASP.NET Core é associado a http://localhost:5000 . Configure prefixos de URL e portas
para o Kestrel usando:
O método de extensão UseUrls
O argumento de linha de comando --urls
A chave de configuração do host urls
O sistema de configuração do ASP.NET Core, incluindo a variável de ambiente ASPNETCORE_URLS
Para obter mais informações sobre esses métodos, confira Hospedagem.

Configuração de ponto de extremidade do IIS
Ao usar o IIS, as associações de URL para o IIS substituam as associações definidas por UseUrls . Para
obter mais informações, confira o tópico Módulo do ASP.NET Core.
ListenOptions.Protocols
A propriedade Protocols estabelece os protocolos HTTP ( HttpProtocols ) habilitados em um ponto de
extremidade de conexão ou para o servidor. Atribua um valor à propriedade Protocols com base na
enumeração HttpProtocols .
VALOR DE ENUMERAÇÃO HTTPPROTOCOLS PROTOCOLO DE CONEXÃO PERMITIDO
Http1 HTTP/1.1 apenas. Pode ser usado com ou sem TLS.
Http2 HTTP/2 apenas. Usado principalmente com TLS. Poderá

ser usado sem TLS apenas se o cliente for compatível
com um Modo de conhecimento prévio.
Http1AndHttp2 HTTP/1.1 e HTTP/2. Requer uma conexão TLS e ALPN

(Negociação de protocolo de camada de aplicativo) para
negociar o HTTP/2; caso contrário, o padrão da conexão
será HTTP/1.1.
O protocolo padrão é HTTP/1.1.

Restrições TLS para HTTP/2:
Versão TLS 1.2 ou posterior
Renegociação desabilitada
Compactação desabilitada
Tamanhos mínimos de troca de chaves efêmera:
ECDHE (Diffie-Hellman de curva elíptica) [ RFC4492] – mínimo de 224 bits
DHE (Diffie-Hellman de campo finito) [ TLS12 ] – mínimo de 2048 bits
Pacote de criptografia não autorizado
Há suporte para TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [ TLS-ECDHE ] com a curva elíptica P -256 [
FIPS186 ] por padrão.
O exemplo a seguir permite conexões HTTP/1.1 e HTTP/2 na porta 8000. As conexões são protegidas
pela TLS com um certificado fornecido:

{
options.Listen(IPAddress.Any, 8000, listenOptions =>
{
listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
});
}
Crie opcionalmente uma implementação do IConnectionAdapter para filtrar os handshakes TLS por
conexão para codificações específicas:

{
options.Listen(IPAddress.Any, 8000, listenOptions =>
{
listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
listenOptions.ConnectionAdapters.Add(new TlsFilterAdapter());
});
}
private class TlsFilterAdapter : IConnectionAdapter

{
public bool IsHttps => false;
public Task<IAdaptedConnection> OnConnectionAsync(ConnectionAdapterContext context)

{
var tlsFeature = context.Features.Get<ITlsHandshakeFeature>();
// Throw NotSupportedException for any cipher algorithm that you don't

// wish to support. Alternatively, define and compare
// ITlsHandshakeFeature.CipherAlgorithm to a list of acceptable cipher
// suites.
//
// A ITlsHandshakeFeature.CipherAlgorithm of CipherAlgorithmType.Null
// indicates that no cipher algorithm supported by Kestrel matches the
// requested algorithm(s).
if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
{
throw new NotSupportedException("Prohibited cipher: " + tlsFeature.CipherAlgorithm);
}
return Task.FromResult<IAdaptedConnection>(new AdaptedConnection(context.ConnectionStream));

}
private class AdaptedConnection : IAdaptedConnection

{
public AdaptedConnection(Stream adaptedStream)
{
ConnectionStream = adaptedStream;
}
public Stream ConnectionStream { get; }
public void Dispose()

{
}
}
}
Definir o protocolo com base na configuração

WebHost.CreateDefaultBuilder chama
serverOptions.Configure(context.Configuration.GetSection("Kestrel")) por padrão ao carregar a
configuração do Kestrel.
No exemplo appsettings.json a seguir, um protocolo de conexão padrão (HTTP/1.1 e HTTP/2) é
estabelecido para todos os pontos de extremidade do Kestrel:
{
"Kestrel": {
"EndPointDefaults": {
"Protocols": "Http1AndHttp2"
}
}
}
O arquivo de configuração de exemplo a seguir estabelece um protocolo de conexão para um ponto de

extremidade específico:
{
"Kestrel": {
"EndPoints": {
"HttpsDefaultCert": {
"Protocols": "Http1AndHttp2"
}
}
}
}
Os protocolos especificados no código substituem os valores definidos pela configuração.
Configuração de transporte
Com a liberação do ASP.NET Core 2.1, o transporte padrão do Kestrel deixa de ser baseado no Libuv,
baseando-se agora em soquetes gerenciados. Essa é uma alteração da falha para aplicativos ASP.NET
Core 2.0 que atualizam para o 2.1 que chamam WebHostBuilderLibuvExtensions.UseLibuv e dependem
de um dos seguintes pacotes:
Microsoft.AspNetCore.Server.Kestrel (referência direta de pacote)
Microsoft.AspNetCore.App
Para projetos do ASP.NET Core 2.1 ou posteriores que usam o metapacote Microsoft.AspNetCore.App e
exigem o uso de Libuv:
Adicione uma dependência para o pacote Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv ao
arquivo de projeto do aplicativo:
<PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
Version="<LATEST_VERSION>" />
Chame WebHostBuilderLibuvExtensions.UseLibuv:

{
{
}

.UseLibuv()
}
Prefixos de URL
Ao usar UseUrls , o argumento de linha de comando --urls , a chave de configuração de host urls ou a
variável de ambiente ASPNETCORE_URLS , os prefixos de URL podem estar em um dos formatos a seguir.
Somente os prefixos de URL HTTP são válidos. O Kestrel não é compatível com SSL ao configurar
associações de URL usando UseUrls .
Endereço IPv4 com o número da porta
http://65.55.39.10:80/
0.0.0.0 é um caso especial que associa a todos os endereços IPv4.

Endereço IPv6 com número da porta
http://[0:0:0:0:0:ffff:4137:270a]:80/
[::] é o equivalente do IPv6 ao IPv4 0.0.0.0 .

Nome do host com o número da porta
http://contoso.com:80/
http://*:80/
Os nomes de host * e + não são especiais. Tudo o que não é reconhecido como um endereço IP
ou um localhost válido é associado a todos os IPs IPv6 e IPv4. Para associar nomes de host
diferentes a diferentes aplicativos ASP.NET Core na mesma porta, use o HTTP.sys ou um servidor
proxy reverso, como o IIS, o Nginx ou o Apache.
WARNING
Se você não está usando um proxy reverso com a filtragem de host habilitada, habilite a filtragem de host.
Nome do localhost do host com o número da porta ou o IP de loopback com o número da porta
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
Quando o localhost for especificado, o Kestrel tentará se associar às interfaces de loopback IPv4
e IPv6. Se a porta solicitada está sendo usada por outro serviço em uma das interfaces de
loopback, o Kestrel falha ao ser iniciado. Se uma das interfaces de loopback não estiver disponível
por qualquer outro motivo (geralmente porque não há suporte para o IPv6), o Kestrel registra um
aviso em log.
Endereço IPv4 com o número da porta
http://65.55.39.10:80/
https://65.55.39.10:443/
0.0.0.0 é um caso especial que associa a todos os endereços IPv4.

Endereço IPv6 com número da porta
http://[0:0:0:0:0:ffff:4137:270a]:80/
https://[0:0:0:0:0:ffff:4137:270a]:443/
[::] é o equivalente do IPv6 ao IPv4 0.0.0.0 .

Nome do host com o número da porta
http://contoso.com:80/
http://*:80/
https://contoso.com:443/
https://*:443/
Nomes de host, * e + não são especiais. Tudo o que não é um endereço IP ou um localhost
reconhecido é associado a todos os IPs IPv6 e IPv4. Para associar nomes de host diferentes a
diferentes aplicativos ASP.NET Core na mesma porta, use WebListener ou um servidor proxy
reverso, como o IIS, o Nginx ou o Apache.
Nome do localhost do host com o número da porta ou o IP de loopback com o número da porta
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
Quando o localhost for especificado, o Kestrel tentará se associar às interfaces de loopback IPv4
e IPv6. Se a porta solicitada está sendo usada por outro serviço em uma das interfaces de
loopback, o Kestrel falha ao ser iniciado. Se uma das interfaces de loopback não estiver disponível
por qualquer outro motivo (geralmente porque não há suporte para o IPv6), o Kestrel registra um
aviso em log.
Soquete do UNIX
http://unix:/run/dan-live.sock
Porta 0
Quando o número da porta 0 for especificado, o Kestrel se associará dinamicamente a uma porta
disponível. A associação à porta 0 é permitida para qualquer nome do host ou IP, exceto localhost .
Quando o aplicativo é executado, a saída da janela do console indica a porta dinâmica na qual o aplicativo
pode ser acessado:
Now listening on: http://127.0.0.1:48508
Prefixos de URL para o SSL

Se você estiver chamando o método de extensão UseHttps , lembre-se de incluir os prefixos de URL com
https: :
{
options.UseHttps("testCert.pfx", "testPassword");
})
.UseUrls("http://localhost:5000", "https://localhost:5001")
.Build();
NOTE
HTTPS e HTTP não podem ser hospedados na mesma porta.
No Windows, é possível criar certificados autoassinados usando o cmdlet New -SelfSignedCertificate do

PowerShell. Para ver um exemplo sem suporte, confira UpdateIISExpressSSLForChrome.ps1.
Filtragem de host
Embora o Kestrel permita a configuração com base em prefixos como http://example.com:5000 , ele
geralmente ignora o nome do host. O host localhost é um caso especial usado para a associação a
endereços de loopback. Todo host que não for um endereço IP explícito será associado a todos os
endereços IP públicos. Nenhuma dessas informações é usada para validar os cabeçalhos do Host da
solicitação.
Como uma solução alternativa, o host por trás de um proxy reverso com filtragem de cabeçalho do host.
Esse é o único cenário compatível com Kestrel no ASP.NET Core 1.x.
Como uma solução alternativa, use middleware para filtrar as solicitações pelo cabeçalho Host :
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Primitives;
using Microsoft.Net.Http.Headers;
using System;
// A normal middleware would provide an options type, config binding, extension methods, etc..
// This intentionally does all of the work inside of the middleware so it can be
// easily copy-pasted into docs and other projects.
public class HostFilteringMiddleware
{
private readonly IList<string> _hosts;
private readonly ILogger<HostFilteringMiddleware> _logger;
public HostFilteringMiddleware(RequestDelegate next, IConfiguration config,

ILogger<HostFilteringMiddleware> logger)
{
if (config == null)
{
throw new ArgumentNullException(nameof(config));
}
_next = next ?? throw new ArgumentNullException(nameof(next));

_logger = logger ?? throw new ArgumentNullException(nameof(logger));
// A semicolon separated list of host names without the port numbers.
// IPv6 addresses must use the bounding brackets and be in their normalized form.
_hosts = config["AllowedHosts"]?.Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
if (_hosts == null || _hosts.Count == 0)
{
throw new InvalidOperationException("No configuration entry found for AllowedHosts.");
}
}
public Task Invoke(HttpContext context)

{
if (!ValidateHost(context))
{
context.Response.StatusCode = 400;
_logger.LogDebug("Request rejected due to incorrect Host header.");
}
return _next(context);
}
// This does not duplicate format validations that are expected to be performed by the host.
private bool ValidateHost(HttpContext context)
{
StringSegment host = context.Request.Headers[HeaderNames.Host].ToString().Trim();
if (StringSegment.IsNullOrEmpty(host))
{
// Http/1.0 does not require the Host header.
// Http/1.1 requires the header but the value may be empty.
return true;
}
// Drop the port
var colonIndex = host.LastIndexOf(':');
// IPv6 special case

if (host.StartsWith("[", StringComparison.Ordinal))
{
var endBracketIndex = host.IndexOf(']');
if (endBracketIndex < 0)
{
// Invalid format
return false;
}
if (colonIndex < endBracketIndex)
{
// No port, just the IPv6 Host
colonIndex = -1;
}
}
if (colonIndex > 0)
{
host = host.Subsegment(0, colonIndex);
}
foreach (var allowedHost in _hosts)

{
if (StringSegment.Equals(allowedHost, host, StringComparison.OrdinalIgnoreCase))
{
return true;
}
// Sub-domain wildcards: *.example.com

if (allowedHost.StartsWith("*.", StringComparison.Ordinal) && host.Length >=
allowedHost.Length)
{
{
// .example.com
var allowedRoot = new StringSegment(allowedHost, 1, allowedHost.Length - 1);
var hostRoot = host.Subsegment(host.Length - allowedRoot.Length, allowedRoot.Length);

if (hostRoot.Equals(allowedRoot, StringComparison.OrdinalIgnoreCase))
{
return true;
}
}
}
return false;
}
}
Registre o HostFilteringMiddleware anterior em Startup.Configure . Observe que a ordem do registro de

middleware é importante. O registro deve ocorrer imediatamente após o registro do middleware de
diagnóstico (por exemplo, app.UseExceptionHandler ).

{
{
}
else
{
}
app.UseMiddleware<HostFilteringMiddleware>();
}
O middleware espera uma chave AllowedHosts em appsettings.json/appsettings.

<EnvironmentName>.json. O valor dessa chave é uma lista separada por ponto e vírgula de nomes de
host sem números de porta:
Como uma solução alternativa, use o Middleware de Filtragem de Host. Middleware de Filtragem de
Host é fornecido pelo pacote Microsoft.AspNetCore.HostFiltering, que está incluído no metapacote
Microsoft.AspNetCore.App (ASP.NET Core 2.1 ou posterior). O middleware é adicionado por
CreateDefaultBuilder, que chama AddHostFiltering:

{
{
}

}
Middleware de Filtragem de Host está desabilitado por padrão. Para habilitar o middleware, defina uma
chave AllowedHosts em appSettings. JSON/appsettings.<EnvironmentName>.json. O valor dessa chave
é uma lista separada por ponto e vírgula de nomes de host sem números de porta:
appsettings.json:
{
"AllowedHosts": "example.com;localhost"
}
NOTE
Middleware de Cabeçalhos Encaminhados também tem uma opção ForwardedHeadersOptions.AllowedHosts.
Middleware de Cabeçalhos Encaminhados e Middleware de filtragem de Host têm funcionalidades semelhantes
para cenários diferentes. Definir AllowedHosts com Middleware de Cabeçalhos Encaminhados é apropriado
quando o cabeçalho do Host não é preservado ao encaminhar solicitações com um servidor proxy reverso ou
balanceador de carga. Definir AllowedHosts com Middleware de Filtragem de Host é apropriado quando Kestrel
é usado como um servidor de borda voltado para o público ou quando o cabeçalho de Host é encaminhado
diretamente.
Para obter mais informações sobre Middleware de Cabeçalhos Encaminhados, veja Configurar o ASP.NET Core
para funcionar com servidores proxy e balanceadores de carga.
Recursos adicionais
Impor o HTTPS
Código-fonte do kestrel
RFC 7230: Sintaxe e roteamento da mensagem (Seção 5.4: Host)
Configurar o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga
Por Tom Dykstra, Rick Strahl e Chris Ross

O módulo do ASP.NET Core permite que os aplicativos ASP.NET Core sejam executados em um
processo de trabalho do IIS (em processo) por trás do IIS em uma configuração de proxy reverso (fora
do processo). O IIS fornece recursos avançados de segurança e capacidade de gerenciamento de
aplicativo Web.
O Módulo do ASP.NET Core permite que os aplicativos ASP.NET Core sejam executados por trás do
IIS em uma configuração de proxy reverso. O IIS fornece recursos avançados de segurança e
capacidade de gerenciamento de aplicativo Web.
Versões do Windows compatíveis:
Windows 7 ou posterior
Windows Server 2008 R2 ou posterior
Ao hospedar em processo, o módulo tem sua própria implementação de servidor, IISHttpServer .
Ao hospedar de fora do processo, o módulo só funciona com o Kestrel. O módulo é incompatível com o
HTTP.sys (chamado anteriormente de WebListener).
O módulo só funciona com o Kestrel. O módulo é incompatível com o HTTP.sys (chamado
anteriormente de WebListener).
Descrição de Módulo do ASP.NET Core

O módulo do ASP.NET Core é um módulo nativo do IIS que se conecta ao pipeline do IIS para:
Hospedar um aplicativo ASP.NET Core dentro do processo de trabalho do IIS ( w3wp.exe ),
chamado o modelo de hospedagem no processo.
Encaminhar solicitações da Web a um aplicativo ASP.NET Core de back-end que executa o
servidor Kestrel, chamado o modelo de hospedagem de fora do processo.
Modelo de hospedagem em processo
Usando uma hospedagem em processo, um aplicativo ASP.NET Core é executado no mesmo processo
que seu processo de trabalho do IIS. Isso remove a penalidade de desempenho de solicitações de
criação de proxies pelo adaptador de loopback ao usar o modelo de hospedagem de fora do processo.
O IIS manipula o gerenciamento de processos com o WAS (Serviço de Ativação de Processos do
Windows).
O Módulo do ASP.NET Core:
Executa a inicialização do aplicativo.
Carrega o CoreCLR.
Chama Program.Main .
Manipula o tempo de vida da solicitação nativa do IIS.
O diagrama a seguir ilustra a relação entre o IIS, o Módulo do ASP.NET Core e um aplicativo
hospedado em processo:
A solicitação chega da Web para o driver do HTTP.sys no modo kernel. O driver roteia as solicitações
nativas ao IIS na porta configurada do site, normalmente, a 80 (HTTP ) ou a 443 (HTTPS ). O módulo
recebe a solicitação nativa e passa o controle para o IISHttpServer , que é o que converte a solicitação
de nativa em gerenciada.
Depois que o IISHttpServer coleta a solicitação, a solicitação é enviada por push ao pipeline do
middleware do ASP.NET Core. O pipeline do middleware manipula a solicitação e a passa como uma
instância de HttpContext para a lógica do aplicativo. A resposta do aplicativo é retornada ao IIS, que a
retorna por push para o cliente HTTP que iniciou a solicitação.
Modelo de hospedagem de fora do processo
Como os aplicativos ASP.NET Core são executados em um processo separado do processo de trabalho
do IIS, o módulo realiza o gerenciamento de processos. O módulo inicia o processo para o aplicativo
ASP.NET Core quando a primeira solicitação chega e reinicia o aplicativo se ele é desligado ou falha.
Isso é basicamente o mesmo comportamento que o dos aplicativos que são executados dentro do
processo e são gerenciados pelo WAS (Serviço de Ativação de Processos do Windows).
O diagrama a seguir ilustra a relação entre o IIS, o Módulo do ASP.NET Core e um aplicativo
hospedado de fora d processo:
As solicitações chegam da Web para o driver do HTTP.sys no modo kernel. O driver roteia as
solicitações ao IIS na porta configurada do site, normalmente, a 80 (HTTP ) ou a 443 (HTTPS ). O
módulo encaminha as solicitações ao Kestrel em uma porta aleatória para o aplicativo, que não seja a
porta 80/443.
O módulo especifica a porta por meio de uma variável de ambiente na inicialização e o middleware de
integração do IIS configura o servidor para escutar em http://localhost:{port} . Outras verificações
são executadas e as solicitações que não se originam do módulo são rejeitadas. O módulo não é
compatível com encaminhamento de HTTPS, portanto, as solicitações são encaminhadas por HTTP,
mesmo se recebidas pelo IIS por HTTPS.
Depois que o Kestrel coleta a solicitação do módulo, a solicitação é enviada por push ao pipeline do
instância de HttpContext para a lógica do aplicativo. O middleware adicionado pela integração do IIS
atualiza o esquema, o IP remoto e pathbase para encaminhar a solicitação para o Kestrel. A resposta do
aplicativo é retornada ao IIS, que a retorna por push para o cliente HTTP que iniciou a solicitação.
O Módulo do ASP.NET Core é um módulo nativo do IIS que se conecta ao pipeline do IIS para
encaminhar solicitações da Web para aplicativos ASP.NET Core de back-end.
Como os aplicativos ASP.NET Core são executados em um processo separado do processo de trabalho
do IIS, o módulo também realiza o gerenciamento de processos. O módulo inicia o processo para o
aplicativo ASP.NET Core quando a primeira solicitação chega e reinicia o aplicativo quando ele falha.
Isso é basicamente o mesmo comportamento que o dos aplicativos ASP.NET 4.x que são executados
dentro do processo do IIS e são gerenciados pelo WAS (Serviço de Ativação de Processos do
Windows).
O diagrama a seguir ilustra a relação entre o IIS, o Módulo do ASP.NET Core e um aplicativo:
As solicitações chegam da Web para o driver do HTTP.sys no modo kernel. O driver roteia as
solicitações ao IIS na porta configurada do site, normalmente, a 80 (HTTP ) ou a 443 (HTTPS ). O
módulo encaminha as solicitações ao Kestrel em uma porta aleatória para o aplicativo, que não seja a
porta 80/443.
O módulo especifica a porta por meio de uma variável de ambiente na inicialização e o middleware de
integração do IIS configura o servidor para escutar em http://localhost:{port} . Outras verificações
são executadas e as solicitações que não se originam do módulo são rejeitadas. O módulo não é
compatível com encaminhamento de HTTPS, portanto, as solicitações são encaminhadas por HTTP,
mesmo se recebidas pelo IIS por HTTPS.
Depois que o Kestrel coleta a solicitação do módulo, a solicitação é enviada por push ao pipeline do
instância de HttpContext para a lógica do aplicativo. O middleware adicionado pela integração do IIS
atualiza o esquema, o IP remoto e pathbase para encaminhar a solicitação para o Kestrel. A resposta do
aplicativo é retornada ao IIS, que a retorna por push para o cliente HTTP que iniciou a solicitação.
Muitos módulos nativos, como a Autenticação do Windows, permanecem ativos. Para saber mais sobre
módulos do IIS ativos com o módulo, confira Módulos do IIS com o ASP.NET Core.
O Módulo do ASP.NET Core tem algumas outras funções. O módulo pode:
Definir variáveis de ambiente para o processo de trabalho.
Registrar a saída StdOut no armazenamento de arquivo para a solução de problemas de
inicialização.
Encaminhar tokens de autenticação do Windows.
Como instalar e usar o Módulo do ASP.NET Core

Para obter instruções detalhadas sobre como instalar e usar o Módulo do ASP.NET Core, confira
Hospedar o ASP.NET Core no Windows com o IIS. Para obter informações sobre como configurar o
módulo, confira o Referência de configuração do Módulo do ASP.NET Core.
Recursos adicionais
Referência de configuração do Módulo do ASP.NET Core
Repositório do GitHub do Módulo do ASP.NET Core (código-fonte)
Módulos do IIS com o ASP.NET Core
Implementação do servidor Web HTTP.sys no
ASP.NET Core
Por Tom Dykstra, Chris Ross e Luke Latham
NOTE
Este tópico se aplica ao ASP.NET Core 2.0 ou versão superior. Em versões anteriores do ASP.NET Core, o HTTP.sys é
chamado WebListener.
O HTTP.sys é um servidor Web para ASP.NET Core executado apenas no Windows. O HTTP.sys é uma
alternativa ao Kestrel e oferece alguns recursos que não são disponibilizados por esse servidor Web.
IMPORTANT
Não é possível usar o HTTP.sys com o IIS ou o IIS Express, pois ele é incompatível com o Módulo do ASP.NET Core.
O HTTP.sys dá suporte aos seguintes recursos:

Autenticação do Windows
Compartilhamento de porta
HTTPS com SNI
HTTP/2 sobre TLS (Windows 10 ou posterior)
Transmissão direta de arquivo
Cache de resposta
WebSockets (Windows 8 ou posterior)
Versões do Windows compatíveis:
Quando usar o HTTP.sys

O HTTP.sys é útil nas implantações em que:
É necessário expor o servidor diretamente à Internet sem usar o IIS.
As implantações internas exigem um recurso que não está disponível no Kestrel, como a
Autenticação do Windows.
O HTTP.sys é uma tecnologia madura que protege contra vários tipos de ataques e proporciona as
propriedades de robustez, segurança e escalabilidade de um servidor Web completo. O próprio IIS é
executado como um ouvinte HTTP sobre o HTTP.sys.

O HTTP/2 estará habilitado para aplicativos ASP.NET Core se os seguintes requisitos básicos forem
atendidos:
Conexão ALPN (Negociação de protocolo de camada de aplicativo)
Se uma conexão HTTP/2 for estabelecida, HttpRequest.Protocol relatará HTTP/2 .
Se uma conexão HTTP/2 for estabelecida, HttpRequest.Protocol relatará HTTP/1.1 .
O HTTP/2 está habilitado por padrão. Se uma conexão HTTP/2 não tiver sido estabelecida, a conexão
retornará para HTTP/1.1. Em uma versão futura do Windows, os sinalizadores de configuração de HTTP/2
estarão disponíveis e contarão com a capacidade de desabilitar o HTTP/2 com HTTP.sys.
Autenticação de modo kernel com Kerberos

O HTTP.sys delega à autenticação de modo kernel com o protocolo de autenticação Kerberos. Não há
suporte para autenticação de modo de usuário com o Kerberos e o HTTP.sys. A conta do computador
precisa ser usada para descriptografar o token/tíquete do Kerberos que é obtido do Active Directory e
encaminhado pelo cliente ao servidor para autenticar o usuário. Registre o SPN (nome da entidade de
serviço) do host, não do usuário do aplicativo.
Como usar o HTTP.sys

Configurar o aplicativo ASP.NET Core para usar o HTTP.sys
1. Não é necessário usar uma referência do pacote no arquivo de projeto ao usar o metapacote
Microsoft.AspNetCore.App (nuget.org) (ASP.NET Core 2.1 ou posterior). Se não estiver usando o
metapacote Microsoft.AspNetCore.App , adicione uma referência do pacote a
Microsoft.AspNetCore.Server.HttpSys.
2. Chame o método de extensão UseHttpSys quando criar o Host Web, especificando todas as opções
do HTTP.sys necessárias:
.UseHttpSys(options =>
{
// The following options are set to default values.
options.Authentication.Schemes = AuthenticationSchemes.None;
options.Authentication.AllowAnonymous = true;
options.MaxConnections = null;
options.MaxRequestBodySize = 30000000;
options.UrlPrefixes.Add("http://localhost:5000");
});
A configuração adicional do HTTP.sys é tratada por meio das configurações do registro.

Opções do HTTP.sys
PROPRIEDADE DESCRIÇÃO PADRÃO
AllowSynchronousIO Controlar quando a Entrada/Saída true

síncrona deve ser permitida para
HttpContext.Request.Body e
HttpContext.Response.Body .
Authentication.AllowAnonymous Permitir solicitações anônimas. true
Authentication.Schemes Especificar os esquemas de None

autenticação permitidos. É possível
modificar a qualquer momento
antes de descartar o ouvinte. Os
valores são fornecidos pela
enumeração
AuthenticationSchemes: Basic ,
Kerberos , Negotiate , None e
NTLM .
EnableResponseCaching Tentativa de cache do modo kernel true

para obtenção de respostas com
cabeçalhos qualificados. A resposta
pode não incluir Set-Cookie ,
Vary ou cabeçalhos Pragma . Ela
deve incluir um cabeçalho
Cache-Control que seja
public e um valor
shared-max-age ou max-age ,
ou um cabeçalho Expires .
MaxAccepts O número máximo de aceitações 5 × Ambiente.

simultâneas. ProcessorCount
MaxConnections O número máximo de conexões null

simultâneas a serem aceitas. Usar (ilimitado)
-1 como infinito. Usar null a
fim de usar a configuração que
abranja toda máquina do registro.
MaxRequestBodySize Confira a seção 30.000.000 de bytes

MaxRequestBodySize. (28,6 MB)
RequestQueueLimit O número máximo de solicitações 1000

que podem ser colocadas na fila.
ThrowWriteExceptions Indica se as gravações do corpo da false

resposta que falham quando o (concluir normalmente)
cliente se desconecta devem gerar
exceções ou serem concluídas
normalmente.
Timeouts Expor a configuração

TimeoutManager do HTTP.sys,
que também pode ser definida no
registro. Siga os links de API para
saber mais sobre cada
configuração, inclusive os valores
padrão:
TimeoutManager.DrainEnti
tyBody – O tempo
permitido para que a API
do servidor HTTP esvazie o
corpo da entidade em uma
conexão Keep-Alive.
TimeoutManager.EntityBod
y – O tempo permitido
para a chegada do corpo
da entidade de solicitação.
TimeoutManager.HeaderW
ait – O tempo permitido
para que a API do servidor
HTTP analise o cabeçalho
da solicitação.
TimeoutManager.IdleConn
ection – O tempo
permitido para uma
conexão ociosa.
TimeoutManager.MinSend
BytesPerSecond – A taxa
de envio mínima para a
resposta.
TimeoutManager.RequestQ
ueue – O tempo permitido
para que a solicitação
permaneça na fila de
solicitações até o aplicativo
coletá-la.
UrlPrefixes Especifique a UrlPrefixCollection

para registrar com o HTTP.sys. A
mais útil é UrlPrefixCollection.Add,
que é usada para adicionar um
prefixo à coleção. É possível
modificá-las a qualquer momento
antes de descartar o ouvinte.
MaxRequestBodySize
O tamanho máximo permitido em bytes para todos os corpos de solicitação. Quando é definido
como null , o tamanho máximo do corpo da solicitação é ilimitado. Esse limite não afeta as
conexões atualizadas que são sempre ilimitadas.
O método recomendado para substituir o limite em um aplicativo ASP.NET Core MVC para um
único IActionResult é usar o atributo RequestSizeLimitAttribute em um método de ação:
[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()
Uma exceção é gerada quando o aplicativo tenta configurar o limite de uma solicitação, depois que o
aplicativo inicia a leitura da solicitação. É possível usar uma propriedade IsReadOnly para indicar se
a propriedade MaxRequestBodySize está no estado somente leitura, o que significa que é tarde demais
para configurar o limite.
Se o aplicativo tiver que substituir MaxRequestBodySize por solicitação, use
IHttpMaxRequestBodySizeFeature:
public void Configure(IApplicationBuilder app, IHostingEnvironment env,

ILogger<Startup> logger)
{
{
var serverAddressesFeature = app.ServerFeatures.Get<IServerAddressesFeature>();

var addresses = string.Join(", ", serverAddressesFeature?.Addresses);
logger.LogInformation($"Addresses: {addresses}");
});
{
}
else
{
app.UseHsts();
}
// Enable HTTPS Redirection Middleware when hosting the app securely.

//app.UseHttpsRedirection();
app.UseMvc();
}
3. Quando usar o Visual Studio, verifique se que o aplicativo está configurado para executar o IIS ou
IIS Express.
No Visual Studio, o perfil de inicialização padrão destina-se ao IIS Express. Para executar o projeto
como um aplicativo de console, altere manualmente o perfil selecionado, conforme mostrado na
captura de tela a seguir:
Configurar o Windows Server
1. Se o aplicativo for uma implantação dependente de estrutura, instale o .NET Core, o .NET
Framework ou ambos (caso o aplicativo .NET Core seja direcionado ao .NET Framework).
.NET Core – Se o aplicativo requer o .NET Core, obtenha e execute o instalador do .NET Core em
Todos os downloads do .NET.
.NET Framework – Se o aplicativo exigir o .NET Framework, confira Guia de instalação do .NET
Framework para obter instruções de instalação. Instale o .NET Framework necessário. O
instalador do .NET Framework mais recente pode ser encontrado em Todos os downloads do
.NET.
2. Configurar URLs e portas para o aplicativo.
Por padrão, o ASP.NET Core é associado a http://localhost:5000 . Para configurar portas e prefixos
de URL, as opções incluem usar:
UseUrls
O argumento de linha de comando urls
A variável de ambiente ASPNETCORE_URLS
UrlPrefixes
O exemplo de código a seguir mostra como usar UrlPrefixes:

{
// The following options are set to default values.
options.Authentication.Schemes = AuthenticationSchemes.None;
options.Authentication.AllowAnonymous = true;
options.MaxConnections = null;
options.MaxRequestBodySize = 30000000;
options.UrlPrefixes.Add("http://localhost:5000");
});
Uma vantagem de usar UrlPrefixes é que uma mensagem de erro é gerada imediatamente no caso
de prefixos formatados de forma incorreta.
As configurações de UrlPrefixes substituem as configurações UseUrls / urls / ASPNETCORE_URLS .
Portanto, uma vantagem de usar UseUrls , urls e a variável de ambiente ASPNETCORE_URLS é que
fica mais fácil alternar entre o Kestrel e o HTTP.sys. Para saber mais sobre UseUrls , urls e
ASPNETCORE_URLS , confira o tópico Host no ASP.NET Core.
O HTTP.sys usa os formatos de cadeia de caracteres UrlPrefix da API do Servidor HTTP.

WARNING
Associações de curinga de nível superior ( http://*:80/ e http://+:80 ) não devem ser usadas.
Associações de curinga de nível superior podem abrir o aplicativo para vulnerabilidades de segurança. Isso se
aplica a curingas fortes e fracos. Use nomes de host explícitos em vez de curingas. Associações de curinga de
subdomínio (por exemplo, *.mysub.com ) não têm esse risco de segurança se você controlar o domínio pai
completo (em vez de *.com , o qual é vulnerável). Veja rfc7230 section-5.4 para obter mais informações.
3. Faça o pré-registro dos prefixos de URL para associá-los ao HTTP.sys e configurar certificados
X.509.
Se os prefixos de URL não estiverem pré-registrados no Windows, execute o aplicativo com
privilégios de administrador. A única exceção ocorre durante a associação ao localhost usando HTTP
(não HTTPS ) com um número de porta superior a 1024. Nesse caso, não é necessário usar
privilégios de administrador.
a. O netsh.exe é a ferramenta interna destinada a configurar o HTTP.sys. Com o netsh.exe, é
possível reservar prefixos de URL e atribuir certificados X.509. A ferramenta exige privilégios
de administrador.
O exemplo a seguir mostra os comandos necessários para reservar prefixos de URL para as
portas 80 e 443:
netsh http add urlacl url=http://+:80/ user=Users

netsh http add urlacl url=https://+:443/ user=Users
O exemplo a seguir mostra como atribuir um certificado X.509:
netsh http add sslcert ipport=0.0.0.0:443 certhash=MyCertHash_Here appid="{00000000-0000-

0000-0000-000000000000}"
Documentação de referência do netsh.exe:

Comandos do Netsh para o protocolo HTTP
Cadeias de caracteres de UrlPrefix
b. Crie certificados X.509 autoassinados, quando necessário.
No Windows, é possível criar certificados autoassinados usando o cmdlet New -
SelfSignedCertificate do PowerShell. Para ver um exemplo sem suporte, confira
UpdateIISExpressSSLForChrome.ps1.
4. Abra as portas do firewall para permitir que o tráfego chegue ao HTTP.sys. Use o netsh.exe ou os
cmdlets do PowerShell.
Servidor proxy e cenários de balanceador de carga

Para aplicativos hospedados pelo HTTP.sys que interagem com solicitações da Internet ou de uma rede
corporativa, podem ser necessárias configurações adicionais ao hospedar atrás de balanceadores de carga e
de servidores proxy. Para obter mais informações, veja Configurar o ASP.NET Core para trabalhar com
servidores proxy e balanceadores de carga.
Recursos adicionais
API do servidor HTTP
Repositório aspnet/HttpSysServer do GitHub (código-fonte)
Por Glenn Condron, Ryan Nowak e Steve Gordon

Um IHttpClientFactory pode ser registrado e usado para configurar e criar instâncias de HttpClient em um
aplicativo. Ele oferece os seguintes benefícios:
Fornece um local central para nomear e configurar instâncias lógicas de HttpClient . Por exemplo, um cliente
github pode ser registrado e configurado para acessar o GitHub. Um cliente padrão pode ser registrado para
outras finalidades.
Codifica o conceito de middleware de saída por meio da delegação de manipuladores no HttpClient e fornece
extensões para que o middleware baseado no Polly possa aproveitar esse recurso.
Gerencia o pooling e o tempo de vida das instâncias de HttpClientMessageHandler subjacentes para evitar
problemas de DNS comuns que ocorrem no gerenciamento manual de tempos de vida de HttpClient .
Adiciona uma experiência de registro em log configurável (via ILogger ) para todas as solicitações enviadas
por meio de clientes criados pelo alocador.
Pré-requisitos
Os projetos direcionados ao .NET Framework exigem a instalação do pacote do NuGet Microsoft.Extensions.Http.
Os projetos destinados ao .Net Core e a referência ao metapacote Microsoft.AspNetCore.App já incluem o pacote
Microsoft.Extensions.Http .
Padrões de consumo
Há várias maneiras de usar o IHttpClientFactory em um aplicativo:
Uso básico
Clientes nomeados
Clientes com tipo
Clientes gerados
Nenhum deles é estritamente superiores ao outro. A melhor abordagem depende das restrições do aplicativo.
Uso básico
O IHttpClientFactory pode ser registrado chamando o método de extensão AddHttpClient em
IServiceCollection , dentro do método Startup.ConfigureServices .
services.AddHttpClient();
Depois de registrado, o código pode aceitar um IHttpClientFactory em qualquer lugar em que os serviços
possam ser injetados com DI (injeção de dependência). O IHttpClientFactory pode ser usado para criar uma
instância de HttpClient :
public class BasicUsageModel : PageModel
{
private readonly IHttpClientFactory _clientFactory;
public IEnumerable<GitHubBranch> Branches { get; private set; }
public bool GetBranchesError { get; private set; }
public BasicUsageModel(IHttpClientFactory clientFactory)

{
_clientFactory = clientFactory;
}
public async Task OnGet()

{
var request = new HttpRequestMessage(HttpMethod.Get,
"https://api.github.com/repos/aspnet/docs/branches");
request.Headers.Add("Accept", "application/vnd.github.v3+json");
request.Headers.Add("User-Agent", "HttpClientFactory-Sample");
var client = _clientFactory.CreateClient();
var response = await client.SendAsync(request);
if (response.IsSuccessStatusCode)
{
Branches = await response.Content
.ReadAsAsync<IEnumerable<GitHubBranch>>();
}
else
{
GetBranchesError = true;
Branches = Array.Empty<GitHubBranch>();
}
}
}
Usar o IHttpClientFactory dessa forma é uma ótima maneira de refatorar um aplicativo existente. Não há
nenhum impacto na maneira em que o HttpClient é usado. Nos locais em que as instâncias HttpClient são
criadas no momento, substitua essas ocorrências por uma chamada a CreateClient.
Clientes nomeados
Quando um aplicativo exige vários usos distintos do HttpClient , cada um com uma configuração diferente, uma
opção é usar clientes nomeados. A configuração de um HttpClient nomeado pode ser especificada durante o
registro em Startup.ConfigureServices .
services.AddHttpClient("github", c =>
{
c.BaseAddress = new Uri("https://api.github.com/");
// Github API versioning
c.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json");
// Github requires a user-agent
c.DefaultRequestHeaders.Add("User-Agent", "HttpClientFactory-Sample");
});
No código anterior, AddHttpClient é chamado, fornecendo o nome github. Esse cliente tem algumas
configurações padrão aplicadas, ou seja, o endereço básico e dois cabeçalhos necessários para trabalhar com a
API do GitHub.
Toda vez que o CreateClient é chamado, uma nova instância de HttpClient é criada e a ação de configuração é
chamada.
Para consumir um cliente nomeado, um parâmetro de cadeia de caracteres pode ser passado para CreateClient .
Especifique o nome do cliente a ser criado:
public class NamedClientModel : PageModel

{
private readonly IHttpClientFactory _clientFactory;
public IEnumerable<GitHubPullRequest> PullRequests { get; private set; }
public bool GetPullRequestsError { get; private set; }
public bool HasPullRequests => PullRequests.Any();
public NamedClientModel(IHttpClientFactory clientFactory)

{
_clientFactory = clientFactory;
}

{
var request = new HttpRequestMessage(HttpMethod.Get,
"repos/aspnet/docs/pulls");
var client = _clientFactory.CreateClient("github");
var response = await client.SendAsync(request);
if (response.IsSuccessStatusCode)
{
PullRequests = await response.Content
.ReadAsAsync<IEnumerable<GitHubPullRequest>>();
}
else
{
GetPullRequestsError = true;
PullRequests = Array.Empty<GitHubPullRequest>();
}
}
}
No código anterior, a solicitação não precisa especificar um nome do host. Ela pode passar apenas o caminho, pois
o endereço básico configurado para o cliente é usado.
Clientes com tipo
Os clientes com tipo fornecem as mesmas funcionalidade que os clientes nomeados sem a necessidade de usar
cadeias de caracteres como chaves. A abordagem de cliente com tipo fornece a ajuda do IntelliSense e do
compilador durante o consumo de clientes. Eles fornecem um único local para configurar e interagir com um
determinado HttpClient . Por exemplo, um único cliente com tipo pode ser usado para um único ponto de
extremidade de back-end e encapsular toda a lógica que lida com esse ponto de extremidade. Outra vantagem é
que eles funcionam com a DI e podem ser injetados no local necessário no aplicativo.
Um cliente com tipo aceita um parâmetro HttpClient em seu construtor:
public class GitHubService
{
public HttpClient Client { get; }
public GitHubService(HttpClient client)

{
client.BaseAddress = new Uri("https://api.github.com/");
// GitHub API versioning
client.DefaultRequestHeaders.Add("Accept",
"application/vnd.github.v3+json");
// GitHub requires a user-agent
client.DefaultRequestHeaders.Add("User-Agent",
"HttpClientFactory-Sample");
Client = client;
}
public async Task<IEnumerable<GitHubIssue>> GetAspNetDocsIssues()

{
var response = await Client.GetAsync(
"/repos/aspnet/docs/issues?state=open&sort=created&direction=desc");
response.EnsureSuccessStatusCode();
var result = await response.Content

.ReadAsAsync<IEnumerable<GitHubIssue>>();
return result;
}
}
No código anterior, a configuração é movida para o cliente com tipo. O objeto HttpClient é exposto como uma
propriedade pública. É possível definir métodos específicos da API que expõem a funcionalidade HttpClient . O
método GetAspNetDocsIssues encapsula o código necessário para consultar e analisar os últimos problemas em
aberto de um repositório GitHub.
Para registrar um cliente com tipo, o método de extensão AddHttpClient genérico pode ser usado em
Startup.ConfigureServices , especificando a classe do cliente com tipo:
services.AddHttpClient<GitHubService>();
O cliente com tipo é registrado como transitório com a DI. O cliente com tipo pode ser injetado e consumido
diretamente:
public class TypedClientModel : PageModel
{
private readonly GitHubService _gitHubService;
public IEnumerable<GitHubIssue> LatestIssues { get; private set; }
public bool HasIssue => LatestIssues.Any();
public bool GetIssuesError { get; private set; }
public TypedClientModel(GitHubService gitHubService)

{
_gitHubService = gitHubService;
}

{
try
{
LatestIssues = await _gitHubService.GetAspNetDocsIssues();
}
catch(HttpRequestException)
{
GetIssuesError = true;
LatestIssues = Array.Empty<GitHubIssue>();
}
}
}
Se preferir, a configuração de um cliente com tipo poderá ser especificada durante o registro em
Startup.ConfigureServices e não no construtor do cliente com tipo:
services.AddHttpClient<RepoService>(c =>
{
c.BaseAddress = new Uri("https://api.github.com/");
c.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json");
c.DefaultRequestHeaders.Add("User-Agent", "HttpClientFactory-Sample");
});
É possível encapsular totalmente o HttpClient dentro de um cliente com tipo. Em vez de o expor como uma
propriedade, é possível fornecer métodos públicos que chamam a instância de HttpClient internamente.
public class RepoService
{
// _httpClient isn't exposed publicly
private readonly HttpClient _httpClient;
public RepoService(HttpClient client)

{
_httpClient = client;
}
public async Task<IEnumerable<string>> GetRepos()

{
var response = await _httpClient.GetAsync("aspnet/repos");
response.EnsureSuccessStatusCode();
var result = await response.Content

.ReadAsAsync<IEnumerable<string>>();
return result;
}
}
No código anterior, o HttpClient é armazenado como um campo privado. Todo o acesso para fazer chamadas
externas passa pelo método GetRepos .
Clientes gerados
O IHttpClientFactory pode ser usado em combinação com outras bibliotecas de terceiros, como a Refit. Refit é
uma biblioteca REST para .NET. Ela converte APIs REST em interfaces dinâmicas. Uma implementação da
interface é gerada dinamicamente pelo RestService usando HttpClient para fazer as chamadas de HTTP
externas.
Uma interface e uma resposta são definidas para representar a API externa e sua resposta:
public interface IHelloClient

{
[Get("/helloworld")]
Task<Reply> GetMessageAsync();
}
public class Reply

{
public string Message { get; set; }
}
Um cliente com tipo pode ser adicionado usando a Refit para gerar a implementação:

{
services.AddHttpClient("hello", c =>
{
c.BaseAddress = new Uri("http://localhost:5000");
})
.AddTypedClient(c => Refit.RestService.For<IHelloClient>(c));
services.AddMvc();
}
A interface definida pode ser consumida, quando necessário, com a implementação fornecida pela DI e pela Refit:
[ApiController]
public class ValuesController : ControllerBase
{
private readonly IHelloClient _client;
public ValuesController(IHelloClient client)

{
_client = client;
}
[HttpGet("/")]
public async Task<ActionResult<Reply>> Index()
{
return await _client.GetMessageAsync();
}
}
Middleware de solicitação de saída

O HttpClient já tem o conceito de delegar manipuladores que podem ser vinculados para solicitações HTTP de
saída. O IHttpClientFactory facilita a definição dos manipuladores a serem aplicados a cada cliente nomeado. Ele
permite o registro e o encadeamento de vários manipuladores para criar um pipeline do middleware de
solicitação saída. Cada um desses manipuladores é capaz de executar o trabalho antes e após a solicitação de
saída. Esse padrão é semelhante ao pipeline do middleware de entrada no ASP.NET Core. O padrão fornece um
mecanismo para gerenciar interesses paralelos em relação às solicitações HTTP, incluindo o armazenamento em
cache, o tratamento de erro, a serialização e o registro em log.
Para criar um manipulador, defina uma classe derivando-a de DelegatingHandler . Substitua o método SendAsync
para executar o código antes de passar a solicitação para o próximo manipulador no pipeline:
public class ValidateHeaderHandler : DelegatingHandler

{
protected override async Task<HttpResponseMessage> SendAsync(
HttpRequestMessage request,
CancellationToken cancellationToken)
{
if (!request.Headers.Contains("X-API-KEY"))
{
return new HttpResponseMessage(HttpStatusCode.BadRequest)
{
Content = new StringContent(
"You must supply an API key header called X-API-KEY")
};
}
return await base.SendAsync(request, cancellationToken);

}
}
O código anterior define um manipulador básico. Ele verifica se um cabeçalho X-API-KEY foi incluído na
solicitação. Se o cabeçalho estiver ausente, isso poderá evitar a chamada de HTTP e retornar uma resposta
adequada.
Durante o registro, um ou mais manipuladores podem ser adicionados à configuração de um HttpClient . Essa
tarefa é realizada por meio de métodos de extensão no IHttpClientBuilder.
services.AddTransient<ValidateHeaderHandler>();
services.AddHttpClient("externalservice", c =>
{
// Assume this is an "external" service which requires an API KEY
c.BaseAddress = new Uri("https://localhost:5000/");
})
.AddHttpMessageHandler<ValidateHeaderHandler>();
No código anterior, o ValidateHeaderHandler é registrado com a DI. O manipulador precisa ser registrado na DI
como transitório. Depois de registrado, é possível chamar AddHttpMessageHandler, passando o tipo para o
manipulador.
Vários manipuladores podem ser registrados na ordem em que eles devem ser executados. Cada manipulador
encapsula o próximo manipulador até que o HttpClientHandler final execute a solicitação:
services.AddTransient<SecureRequestHandler>();
services.AddTransient<RequestDataHandler>();
services.AddHttpClient("clientwithhandlers")
// This handler is on the outside and called first during the
// request, last during the response.
.AddHttpMessageHandler<SecureRequestHandler>()
// This handler is on the inside, closest to the request being
// sent.
.AddHttpMessageHandler<RequestDataHandler>();
Usar manipuladores baseados no Polly

O IHttpClientFactory integra-se a uma biblioteca de terceiros popular chamada Polly. O Polly é uma biblioteca
abrangente de tratamento de falha transitória e de resiliência para .NET. Ela permite que os desenvolvedores
expressem políticas, como Repetição, Disjuntor, Tempo Limite, Isolamento de Bulkhead e Fallback de maneira
fluente e thread-safe.
Os métodos de extensão são fornecidos para habilitar o uso de políticas do Polly com instâncias de HttpClient
configuradas. As extensões do Polly estão disponíveis no pacote do NuGet Microsoft.Extensions.Http.Polly. Esse
pacote não está incluído no metapacote Microsoft.AspNetCore.App. Para usar as extensões, um
<PackageReference /> explícito deve ser incluído no projeto.
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netcoreapp2.1</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Http.Polly" Version="2.1.1" />
</ItemGroup>
</Project>
Depois de restaurar este pacote, os métodos de extensão ficam disponíveis para permitir a adição de
manipuladores baseados no Polly aos clientes.
Tratar falhas transitórias
As falhas mais comuns ocorrem quando as chamadas HTTP externas são transitórias. Um método de extensão
conveniente chamado AddTransientHttpErrorPolicy é incluído para permitir que uma política seja definido para
tratar erros transitórios. As políticas configuradas com esse método de extensão tratam HttpRequestException ,
respostas HTTP 5xx e respostas HTTP 408.
A extensão AddTransientHttpErrorPolicy pode ser usada em Startup.ConfigureServices . A extensão fornece
acesso a um objeto PolicyBuilder configurado para tratar erros que representam uma possível falha transitória:
services.AddHttpClient<UnreliableEndpointCallerService>()
.AddTransientHttpErrorPolicy(p =>
p.WaitAndRetryAsync(3, _ => TimeSpan.FromMilliseconds(600)));
No código anterior, uma política WaitAndRetryAsync é definida. As solicitações com falha são repetidas até três
vezes com um atraso de 600 ms entre as tentativas.
Selecionar políticas dinamicamente
Existem métodos de extensão adicionais que podem ser usados para adicionar manipuladores baseados no Polly.
Uma dessas extensões é a AddPolicyHandler , que tem várias sobrecargas. Uma sobrecarga permite que a
solicitação seja inspecionada durante a definição da política a ser aplicada:
var timeout = Policy.TimeoutAsync<HttpResponseMessage>(

TimeSpan.FromSeconds(10));
var longTimeout = Policy.TimeoutAsync<HttpResponseMessage>(
services.AddHttpClient("conditionalpolicy")
// Run some code to select a policy based on the request
.AddPolicyHandler(request =>
request.Method == HttpMethod.Get ? timeout : longTimeout);
No código anterior, se a solicitação de saída é um GET, é aplicado um tempo limite de 10 segundos. Para qualquer
outro método HTTP, é usado um tempo limite de 30 segundos.
Adicionar vários manipuladores do Polly
É comum aninhar políticas do Polly para fornecer uma funcionalidade avançada:
services.AddHttpClient("multiplepolicies")
.AddTransientHttpErrorPolicy(p => p.RetryAsync(3))
.AddTransientHttpErrorPolicy(
p => p.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30)));
No exemplo anterior, dois manipuladores são adicionados. O primeiro usa a extensão

AddTransientHttpErrorPolicy para adicionar uma política de repetição. As solicitações com falha são repetidas até
três vezes. A segunda chamada a AddTransientHttpErrorPolicy adiciona uma política de disjuntor. As solicitações
externas adicionais são bloqueadas por 30 segundos quando ocorrem cinco tentativas com falha
consecutivamente. As políticas de disjuntor são políticas com estado. Todas as chamadas por meio desse cliente
compartilham o mesmo estado do circuito.
Adicionar políticas do registro do Polly
Uma abordagem para gerenciar as políticas usadas com frequência é defini-las uma única vez e registrá-las em
um PolicyRegistry . É fornecido um método de extensão que permite que um manipulador seja adicionado
usando uma política do registro:
var registry = services.AddPolicyRegistry();
registry.Add("regular", timeout);
registry.Add("long", longTimeout);
services.AddHttpClient("regulartimeouthandler")
.AddPolicyHandlerFromRegistry("regular");
No código anterior, duas políticas são registradas quando PolicyRegistry é adicionado ao ServiceCollection .
Para usar uma política do registro, o método AddPolicyHandlerFromRegistry é usado, passando o nome da política
a ser aplicada.
Mais informações sobre o IHttpClientFactory e as integrações do Polly podem ser encontradas no Wiki do Polly.
HttpClient e gerenciamento de tempo de vida

Uma nova instância de HttpClient é chamada, sempre que CreateClient é chamado na IHttpClientFactory .
Haverá um HttpMessageHandler para cada cliente nomeado. IHttpClientFactory cria pools com as instâncias de
HttpMessageHandler criadas pelo alocador para reduzir o consumo de recursos. Uma instância de
HttpMessageHandler poderá ser reutilizada no pool, ao criar uma nova instância de HttpClient , se o respectivo
tempo de vida não tiver expirado.
O pooling de manipuladores é preferível porque normalmente cada manipulador gerencia as próprias conexões
HTTP subjacentes. Criar mais manipuladores do que o necessário pode resultar em atrasos de conexão. Alguns
manipuladores também mantêm as conexões abertas indefinidamente, o que pode impedir que o manipulador
reaja a alterações de DNS.
O tempo de vida padrão do manipulador é de 2 minutos. O valor padrão pode ser substituído para cada cliente
nomeado. Para substituí-lo, chame SetHandlerLifetime no IHttpClientBuilder que é retornado ao criar o cliente:
services.AddHttpClient("extendedhandlerlifetime")
.SetHandlerLifetime(TimeSpan.FromMinutes(5));
Não é necessário descartar o cliente. O descarte cancela as solicitações de saída e garante que a determinada
instância de HttpClient não seja mais usada depois de chamar Dispose. IHttpClientFactory rastreia e descarta
recursos usados pelas instâncias de HttpClient . Geralmente, as instâncias de HttpClient podem ser tratadas
como objetos do .NET e não exigem descarte.
Manter uma única instância de HttpClient ativa por uma longa duração é um padrão comum usado, antes do
início de IHttpClientFactory . Esse padrão se torna desnecessário após a migração para IHttpClientFactory .
Registrando em log
Os clientes criado pelo IHttpClientFactory registram mensagens de log para todas as solicitações. Habilite o nível
apropriado de informações na configuração de log para ver as mensagens de log padrão. Os registros em log
adicionais, como o registro em log dos cabeçalhos de solicitação, estão incluídos somente no nível de
rastreamento.
A categoria de log usada para cada cliente inclui o nome do cliente. Um cliente chamado MyNamedClient, por
exemplo, registra mensagens com uma categoria de System.Net.Http.HttpClient.MyNamedClient.LogicalHandler .
Mensagens sufixadas com LogicalHandler ocorrem fora do pipeline do manipulador de solicitações. Na
solicitação, as mensagens são registradas em log antes que qualquer outro manipulador no pipeline a tenha
processado. Na resposta, as mensagens são registradas depois que qualquer outro manipulador do pipeline tenha
recebido a resposta.
O registro em log também ocorre dentro do pipeline do manipulador de solicitações. No caso do exemplo de
MyNamedClient, essas mensagens são registradas em log na categoria de log
System.Net.Http.HttpClient.MyNamedClient.ClientHandler . Para a solicitação, isso ocorre depois que todos os outros
manipuladores são executados e imediatamente antes que a solicitação seja enviada pela rede. Na resposta, esse
registro em log inclui o estado da resposta antes que ela seja retornada por meio do pipeline do manipulador.
Habilitar o registro em log dentro e fora do pipeline permite a inspeção das alterações feitas por outros
manipuladores do pipeline. Isso pode incluir, por exemplo, alterações nos cabeçalhos de solicitação ou no código
de status da resposta.
Incluir o nome do cliente na categoria de log permite a filtragem de log para clientes nomeados específicos,
quando necessário.
Configurar o HttpMessageHandler
Talvez seja necessário controlar a configuração do HttpMessageHandler interno usado por um cliente.
Um IHttpClientBuilder é retornado ao adicionar clientes nomeados ou com tipo. O método de extensão
ConfigurePrimaryHttpMessageHandler pode ser usado para definir um delegado. O representante que é usado
para criar e configurar o HttpMessageHandler primário usado pelo cliente:
services.AddHttpClient("configured-inner-handler")
.ConfigurePrimaryHttpMessageHandler(() =>
{
return new HttpClientHandler()
{
AllowAutoRedirect = false,
UseDefaultCredentials = true
};
});
Introdução a Páginas do Razor no ASP.NET Core
Por Rick Anderson e Ryan Nowak

Páginas do Razor é um novo aspecto do ASP.NET Core MVC que torna a codificação de cenários focados
em página mais fácil e produtiva.
Se você estiver procurando um tutorial que utiliza a abordagem Modelo-Exibição-Controlador, consulte a
Introdução ao ASP.NET Core MVC.
Este documento proporciona uma introdução a páginas do Razor. Este não é um tutorial passo a passo. Se
você achar que algumas das seções são muito avançadas, consulte a Introdução a Páginas do Razor. Para
obter uma visão geral do ASP.NET Core, consulte a Introdução ao ASP.NET Core.
Pré-requisitos
Clique em uma das seguintes opções:
Ferramentas da CLI: Windows, Linux ou macOS: SDK 2.0 ou posterior do .NET Core
Ferramentas de editor/IDE
Windows: Visual Studio para Windows
Carga de trabalho ASP.NET e desenvolvimento para a Web
Carga de trabalho de desenvolvimento multiplataforma do .NET Core
Linux: Visual Studio Code
macOS: Visual Studio para Mac
Criando um projeto de Páginas do Razor

Visual Studio
Visual Studio Code
CLI do .NET Core
Consulte a Introdução a Páginas do Razor para obter instruções detalhadas sobre como criar um projeto de
Páginas do Razor usando o Visual Studio.
Páginas do Razor
O Páginas do Razor está habilitado em Startup.cs:
{
{
// Includes support for Razor Pages and controllers.
services.AddMvc();
}

{
app.UseMvc();
}
}
Considere uma página básica:
@page
<h1>Hello, world!</h1>
<h2>The time on the server is @DateTime.Now</h2>
O código anterior é muito parecido com um arquivo de exibição do Razor. O que o torna diferentes é a
diretiva @page . @page transforma o arquivo em uma ação do MVC – o que significa que ele trata
solicitações diretamente, sem passar por um controlador. @page deve ser a primeira diretiva do Razor em
uma página. @page afeta o comportamento de outros constructos do Razor.
Uma página semelhante, usando uma classe PageModel , é mostrada nos dois arquivos a seguir. O arquivo
Pages/Index2.cshtml:
@page
@using RazorPagesIntro.Pages
@model IndexModel2
<h2>Separate page model</h2>

<p>
@Model.Message
</p>
O modelo de página Pages/Index2.cshtml.cs:
using Microsoft.AspNetCore.Mvc.RazorPages;
using System;
namespace RazorPagesIntro.Pages
{
public class IndexModel2 : PageModel
{
public string Message { get; private set; } = "PageModel in C#";
public void OnGet()

{
Message += $" Server time is { DateTime.Now }";
}
}
}
Por convenção, o arquivo de classe PageModel tem o mesmo nome que o arquivo na Página do Razor com
.cs acrescentado. Por exemplo, a Página do Razor anterior é Pages/Index2.cshtml. O arquivo que contém a
classe PageModel é chamado Pages/Index2.cshtml.cs.
As associações de caminhos de URL para páginas são determinadas pelo local da página no sistema de
arquivos. A tabela a seguir mostra um caminho de Página do Razor e a URL correspondente:
CAMINHO E NOME DO ARQUIVO URL CORRESPONDENTE
/Pages/Index.cshtml / ou /Index
/Pages/Contact.cshtml /Contact
/Pages/Store/Contact.cshtml /Store/Contact
/Pages/Store/Index.cshtml /Store ou /Store/Index
Notas:
O tempo de execução procura arquivos de Páginas do Razor na pasta Pages por padrão.
Index é a página padrão quando uma URL não inclui uma página.
Escrevendo um formulário básico

Páginas do Razor foi projetado para facilitar a implementação de padrões comuns usados com navegadores
da Web ao criar um aplicativo. Model binding, auxiliares de marcas e auxiliares HTML funcionam todos
apenas com as propriedades definidas em uma classe de Página do Razor. Considere uma página que
implementa um formulário básico "Fale conosco" para o modelo Contact :
Para as amostras neste documento, o DbContext é inicializado no arquivo Startup.cs.
using RazorPagesContacts.Data;
namespace RazorPagesContacts
{
{
public IHostingEnvironment HostingEnvironment { get; }

{
services.AddDbContext<AppDbContext>(options =>
options.UseInMemoryDatabase("name"));
services.AddMvc();
}

{
app.UseMvc();
}
}
}
O modelo de dados:
namespace RazorPagesContacts.Data
{
public class Customer
{
public int Id { get; set; }
[Required, StringLength(100)]
}
}
O contexto do banco de dados:
namespace RazorPagesContacts.Data
{
public class AppDbContext : DbContext
{
public AppDbContext(DbContextOptions options)
: base(options)
{
}
public DbSet<Customer> Customers { get; set; }

}
}
O arquivo de exibição Pages/Create.cshtml:
@page
@model RazorPagesContacts.Pages.CreateModel
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
<html>
<body>
<p>
Enter your name.
</p>
<div asp-validation-summary="All"></div>
<form method="POST">
<div>Name: <input asp-for="Customer.Name" /></div>
<input type="submit" />
</form>
</body>
</html>
O modelo de página Pages/Create.cshtml.cs:

namespace RazorPagesContacts.Pages
{
public class CreateModel : PageModel
{
public CreateModel(AppDbContext db)

{
_db = db;
}
[BindProperty]
public Customer Customer { get; set; }
public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}
_db.Customers.Add(Customer);
return RedirectToPage("/Index");
}
}
}
Por convenção, a classe PageModel é chamada de <PageName>Model e está no mesmo namespace que a
página.
A classe PageModel permite separar a lógica de uma página da respectiva apresentação. Ela define
manipuladores para as solicitações enviadas e os dados usados para renderizar a página. Esta separação
permite gerenciar as dependências da página por meio de injeção de dependência e realizar um teste de
unidade nas páginas.
A página tem um método de manipulador OnPostAsync , que é executado em solicitações POST (quando
um usuário posta o formulário). Você pode adicionar métodos de manipulador para qualquer verbo HTTP.
Os manipuladores mais comuns são:
OnGet para inicializar o estado necessário para a página. Amostra de OnGet.
OnPost para manipular envios de formulário.
O sufixo de nomenclatura Async é opcional, mas geralmente é usado por convenção para funções
assíncronas. O código OnPostAsync no exemplo anterior tem aparência semelhante ao que você
normalmente escreve em um controlador. O código anterior é comum para as Páginas do Razor. A maioria
dos primitivos MVC como model binding, validação e resultados da ação são compartilhados.
O método OnPostAsync anterior:
{
{
return Page();
}
}
O fluxo básico de OnPostAsync :

Verifique se há erros de validação.
Se não houver nenhum erro, salve os dados e redirecione.
Se houver erros, mostre a página novamente com as mensagens de validação. A validação do lado do
cliente é idêntica para aplicativos ASP.NET Core MVC tradicionais. Em muitos casos, erros de validação
seriam detectados no cliente e nunca enviados ao servidor.
Quando os dados são inseridos com êxito, o método de manipulador OnPostAsync chama o método auxiliar
RedirectToPage para retornar uma instância de RedirectToPageResult . RedirectToPage é um novo resultado
de ação, semelhante a RedirectToAction ou RedirectToRoute , mas personalizado para páginas. Na amostra
anterior, ele redireciona para a página de Índice raiz ( /Index ). RedirectToPage é descrito em detalhes na
seção Geração de URLs para páginas.
Quando o formulário enviado tem erros de validação (que são passados para o servidor), o método de
manipulador OnPostAsync chama o método auxiliar Page . Page retorna uma instância de PageResult .
Retornar Page é semelhante a como as ações em controladores retornam View . PageResult é o tipo de
retorno padrão para um método de manipulador. Um método de manipulador que retorna void renderiza
a página.
A propriedade Customer usa o atributo [BindProperty] para aceitar o model binding.

{
public CreateModel(AppDbContext db)

{
_db = db;
}
[BindProperty]

{
{
return Page();
}
}
}
Páginas do Razor, por padrão, associam as propriedades somente com verbos não GET. A associação de
propriedades pode reduzir a quantidade de código que você precisa escrever. A associação reduz o código
usando a mesma propriedade para renderizar os campos de formulário ( <input asp-for="Customer.Name" />
) e aceitar a entrada.
NOTE
Por motivos de segurança, você deve optar por associar os dados da solicitação GET às propriedades do modelo de
página. Verifique a entrada do usuário antes de mapeá-la para as propriedades. Aceitar esse comportamento é útil
quando você lida com cenários que contam com a cadeia de caracteres de consulta ou com os valores de rota.
Para associar uma propriedade às solicitações GET, defina a propriedade SupportsGet do atributo
[BindProperty] como true : [BindProperty(SupportsGet = true)]
A home page (Index.cshtml):
@page
@model RazorPagesContacts.Pages.IndexModel
<h1>Contacts</h1>
<form method="post">
<table class="table">
<thead>
<tr>
<th>ID</th>
<th>Name</th>
</tr>
</thead>
<tbody>
@foreach (var contact in Model.Customers)
{
<tr>
<td>@contact.Id</td>
<td>@contact.Name</td>
<td>
<a asp-page="./Edit" asp-route-id="@contact.Id">edit</a>
<button type="submit" asp-page-handler="delete"
asp-route-id="@contact.Id">delete</button>
</td>
</tr>
}
</tbody>
</table>
<a asp-page="./Create">Create</a>
</form>
A classe PageModel (Index.cshtml.cs) associada:

{
{
public IndexModel(AppDbContext db)

{
_db = db;
}
public IList<Customer> Customers { get; private set; }

{
Customers = await _db.Customers.AsNoTracking().ToListAsync();
}
public async Task<IActionResult> OnPostDeleteAsync(int id)

{
var contact = await _db.Customers.FindAsync(id);
if (contact != null)
{
_db.Customers.Remove(contact);
}
return RedirectToPage();
}
}
}
O arquivo cshtml contém a marcação a seguir para criar um link de edição para cada contato:
<a asp-page="./Edit" asp-route-id="@contact.Id">edit</a>
O auxiliar de marcas de âncora usou o atributo asp-route-{value} para gerar um link para a página Edit. O
link contém dados de rota com a ID de contato. Por exemplo, http://localhost:5000/Edit/1 .
O arquivo Pages/Edit.cshtml:
@page "{id:int}"
@model RazorPagesContacts.Pages.EditModel
@{
ViewData["Title"] = "Edit Customer";
}
<h1>Edit Customer - @Model.Customer.Id</h1>

<input asp-for="Customer.Id" type="hidden" />
<div>
<label asp-for="Customer.Name"></label>
<div>
<input asp-for="Customer.Name" />
<span asp-validation-for="Customer.Name" ></span>
</div>
</div>
<div>
<button type="submit">Save</button>
</div>
</form>
A primeira linha contém a diretiva @page "{id:int}" . A restrição de roteamento "{id:int}" informa à
página para aceitar solicitações para a página que contêm dados da rota int . Se uma solicitação para a
página não contém dados de rota que podem ser convertidos em um int , o tempo de execução retorna
um erro HTTP 404 (não encontrado). Para tornar a ID opcional, acrescente ? à restrição de rota:
@page "{id:int?}"
O arquivo Pages/Edit.cshtml.cs:
using System;
{
public class EditModel : PageModel
{
public EditModel(AppDbContext db)

{
_db = db;
}
[BindProperty]
public async Task<IActionResult> OnGetAsync(int id)

{
Customer = await _db.Customers.FindAsync(id);
if (Customer == null)
{
}
return Page();
}

{
{
return Page();
}
_db.Attach(Customer).State = EntityState.Modified;
try
{
}
catch (DbUpdateConcurrencyException)
{
throw new Exception($"Customer {Customer.Id} not found!");
}
}
}
}
O arquivo Index.cshtml também contém a marcação para criar um botão de exclusão para cada contato de
cliente:
<button type="submit" asp-page-handler="delete"

asp-route-id="@contact.Id">delete</button>
Quando o botão de exclusão é renderizado em HTML, seu formaction inclui parâmetros para:
A ID de contato do cliente especificada pelo atributo asp-route-id .
O handler especificado pelo atributo asp-page-handler .
Este é um exemplo de um botão de exclusão renderizado com uma ID de contato do cliente de 1 :
<button type="submit" formaction="/?id=1&handler=delete">delete</button>
Quando o botão é selecionado, uma solicitação de formulário POST é enviada para o servidor. Por
convenção, o nome do método do manipulador é selecionado com base no valor do parâmetro handler de
acordo com o esquema OnPost[handler]Async .
Como o handler é delete neste exemplo, o método do manipulador OnPostDeleteAsync é usado para
processar a solicitação POST . Se o asp-page-handler for definido como um valor diferente, como remove ,
um método de manipulador de página com o nome OnPostRemoveAsync será selecionado.
public async Task<IActionResult> OnPostDeleteAsync(int id)

{
var contact = await _db.Customers.FindAsync(id);
if (contact != null)
{
_db.Customers.Remove(contact);
}
}
O método OnPostDeleteAsync :
Aceita o id da cadeia de caracteres de consulta.
Consulta o banco de dados para o contato de cliente com FindAsync .
Se o contato do cliente for encontrado, eles serão removidos da lista de contatos do cliente. O banco de
dados é atualizado.
Chama RedirectToPage para redirecionar para a página de índice de raiz ( /Index ).
Marque as propriedades da página conforme necessário

As propriedades em um PageModel podem ser decoradas com o atributo Required:
namespace RazorPagesMovie.Pages.Movies
{
{
public IActionResult OnGet()
{
return Page();
}
[BindProperty]
[Required(ErrorMessage = "Color is required")]
public string Color { get; set; }
public IActionResult OnPostAsync()

{
{
return Page();
}
// Process color.
return RedirectToPage("./Index");
}
}
}
Confira Validação de modelo para obter mais informações.
Gerenciar solicitações HEAD com o manipulador OnGet

As solicitações HEAD permitem recuperar os cabeçalhos de um recurso específico. Ao contrário das
solicitações GET, as solicitações HEAD não retornam um corpo de resposta.
Geralmente, um manipulador HEAD é criado e chamado para solicitações HEAD:
public void OnHead()

{
HttpContext.Response.Headers.Add("HandledBy", "Handled by OnHead!");
}
Caso nenhum manipulador HEAD ( OnHead ) seja definido, as Páginas Razor voltam a chamar o
manipulador de página GET ( OnGet ) no ASP.NET Core 2.1 ou posterior. No ASP.NET Core 2.1 e 2.2, esse
comportamento ocorre com o SetCompatibilityVersion em Startup.Configure :
services.AddMvc()
.SetCompatibilityVersion(Microsoft.AspNetCore.Mvc.CompatibilityVersion.Version_2_1);
Os modelos padrão geram a chamada SetCompatibilityVersion no ASP.NET Core 2.1 e 2.2.

SetCompatibilityVersion define de forma eficiente a opção de Páginas Razor
AllowMappingHeadRequestsToGetHandler como true .
Em vez de aceitar todos os 2.1 comportamentos com SetCompatibilityVersion , você pode explicitamente
participar de comportamentos específicos. O código a seguir aceita as solicitações de mapeamento HEAD
para o manipulador GET.
services.AddMvc()
.AddRazorPagesOptions(options =>
{
options.AllowMappingHeadRequestsToGetHandler = true;
});
XSRF/CSRF e Páginas do Razor

Você não precisa escrever nenhum código para validação antifalsificação. Validação e geração de token
antifalsificação são automaticamente incluídas nas Páginas do Razor.
Usando Layouts, parciais, modelos e auxiliares de marcas com

Páginas do Razor
As Páginas funcionam com todos os recursos do mecanismo de exibição do Razor. Layouts, parciais,
modelos, auxiliares de marcas, _ViewStart.cshtml e _ViewImports.cshtml funcionam da mesma forma que
funcionam exibições convencionais do Razor.
Organizaremos essa página aproveitando alguns desses recursos.
Adicione uma página de layout a Pages/Shared/_Layout.cshtml:
Adicione uma página de layout a Pages/_Layout.cshtml:
<!DOCTYPE html>
<html>
<head>
<title>Razor Pages Sample</title>
</head>
<body>
<a asp-page="/Index">Home</a>
@RenderBody()
<a asp-page="/Customers/Create">Create</a> <br />
</body>
</html>
O Layout:
Controla o layout de cada página (a menos que a página opte por não usar o layout).
Importa estruturas HTML como JavaScript e folhas de estilo.
Veja página de layout para obter mais informações.
A propriedade Layout é definida em Pages/_ViewStart.cshtml:
@{
Layout = "_Layout";
}
O layout está na pasta Pages/Shared. As páginas buscam outras exibições (layouts, modelos, parciais)
hierarquicamente, iniciando na mesma pasta que a página atual. Um layout na pasta Pages/Shared pode
ser usado em qualquer página do Razor na pasta Pages.
O arquivo de layout deve entrar na pasta Pages/Shared.
O layout está na pasta Pages. As páginas buscam outras exibições (layouts, modelos, parciais)
hierarquicamente, iniciando na mesma pasta que a página atual. Um layout na pasta Pages pode ser usado
em qualquer Página do Razor na pasta Pages.
Recomendamos que você não coloque o arquivo de layout na pasta Views/Shared. Views/Shared é um
padrão de exibições do MVC. As Páginas do Razor devem confiar na hierarquia de pasta e não nas
convenções de caminho.
A pesquisa de modo de exibição de uma Página do Razor inclui a pasta Pages. Os layouts, modelos e
parciais que você está usando com controladores MVC e exibições do Razor convencionais apenas
funcionam.
Adicione um arquivo Pages/_ViewImports.cshtml:
@namespace RazorPagesContacts.Pages
@namespace é explicado posteriormente no tutorial. A diretiva @addTagHelper coloca os auxiliares de marcas

internos em todas as páginas na pasta Pages.
Quando a diretiva @namespace é usada explicitamente em uma página:
@page
@namespace RazorPagesIntro.Pages.Customers
@model NameSpaceModel
<h2>Name space</h2>
<p>
@Model.Message
</p>
A diretiva define o namespace da página. A diretiva @model não precisa incluir o namespace.
Quando a diretiva @namespace está contida em _ViewImports.cshtml, o namespace especificado fornece o
prefixo do namespace gerado na página que importa a diretiva @namespace . O restante do namespace
gerado (a parte do sufixo) é o caminho relativo separado por ponto entre a pasta que contém
_ViewImports.cshtml e a pasta que contém a página.
Por exemplo, a classe PageModel Pages/Customers/Edit.cshtml.cs define explicitamente o namespace:
{
{
public EditModel(AppDbContext db)

{
_db = db;
}
// Code removed for brevity.
O arquivo Pages/_ViewImports.cshtml define o namespace a seguir:
@namespace RazorPagesContacts.Pages
O namespace gerado para o Razor Pages Pages/Customers/Edit.cshtml é o mesmo que a classe PageModel .
@namespace também funciona com exibições do Razor convencionais.
O arquivo de exibição Pages/Create.cshtml original:
@page
@model RazorPagesContacts.Pages.CreateModel
<html>
<body>
<p>
Enter your name.
</p>
</form>
</body>
</html>
O arquivo de exibição Pages/Create.cshtml atualizado:
@page
@model CreateModel
<html>
<body>
<p>
Enter your name.
</p>
</form>
</body>
</html>
O projeto inicial de Páginas do Razor contém o Pages/_ValidationScriptsPartial.cshtml, que conecta a

validação do lado do cliente.
Para obter mais informações sobre exibições parciais, consulte Exibições parciais no ASP.NET Core.
Geração de URL para Páginas

A página Create , exibida anteriormente, usa RedirectToPage :

{
{
return Page();
}
}
O aplicativo tem a estrutura de arquivos/pastas a seguir:
/Pages
Index.cshtml
/Clientes
Create.cshtml
Edit.cshtml
Index.cshtml
As páginas Pages/Customers/Create.cshtml e Pages/Customers/Edit.cshtml redirecionam para o
Pages/Index.cshtml após êxito. A cadeia de caracteres /Index faz parte do URI para acessar a página
anterior. A cadeia de caracteres /Index pode ser usada para gerar URIs para a página Pages/Index.cshtml.
Por exemplo:
Url.Page("/Index", ...)
<a asp-page="/Index">My Index Page</a>
RedirectToPage("/Index")
O nome da página é o caminho para a página da pasta raiz /Pages, incluindo um / à direita (por exemplo,
/Index ). Os exemplos anteriores de geração de URL oferecem opções avançadas e recursos funcionais
para codificar uma URL. A geração de URL usa roteamento e pode gerar e codificar parâmetros de acordo
com o modo como a rota é definida no caminho de destino.
A Geração de URL para páginas dá suporte a nomes relativos. A tabela a seguir mostra qual página de
Índice é selecionada com diferentes parâmetros RedirectToPage de Pages/Customers/Create.cshtml:
REDIRECTTOPAGE(X) PÁGINA
RedirectToPage("/Index") Pages/Index
RedirectToPage("./Index"); Pages/Customers/Index
RedirectToPage("../Index") Pages/Index
RedirectToPage("Index") Pages/Customers/Index
RedirectToPage("Index") , e RedirectToPage("../Index") são nomes relativos. O

RedirectToPage("./Index")
parâmetro RedirectToPage é combinado com o caminho da página atual para calcular o nome da página de
destino.
Vinculação de nome relativo é útil ao criar sites com uma estrutura complexa. Se você usar nomes relativos
para vincular entre páginas em uma pasta, você poderá renomear essa pasta. Todos os links ainda
funcionarão (porque eles não incluirão o nome da pasta).
Atributo ViewData
Os dados podem ser passados para uma página com ViewDataAttribute. As propriedades nos
controladores ou nos modelos da Página Razor decoradas com [ViewData] têm seus valores armazenados
e carregados em ViewDataDictionary.
No exemplo a seguir, o AboutModel contém uma propriedade Title decorada com [ViewData] .A
propriedade Title está definida como o título da página Sobre:
{
[ViewData]
public string Title { get; } = "About";
public void OnGet()

{
}
}
Na página Sobre, acesse a propriedade Title como uma propriedade de modelo:
<h1>@Model.Title</h1>
No layout, o título é lido a partir do dicionário ViewData:
<!DOCTYPE html>
<html lang="en">
<head>
<title>@ViewData["Title"] - WebApplication</title>
...
TempData
O ASP.NET Core expõe a propriedade TempData em um controlador. Essa propriedade armazena dados
até eles serem lidos. Os métodos Keep e Peek podem ser usados para examinar os dados sem exclusão.
TempData é útil para redirecionamento nos casos em que os dados são necessários para mais de uma única
solicitação.
O atributo [TempData] é novo no ASP.NET Core 2.0 e tem suporte em controladores e páginas.
Os conjuntos de código a seguir definem o valor de Message usando TempData :
public class CreateDotModel : PageModel
{
public CreateDotModel(AppDbContext db)

{
_db = db;
}
[TempData]
[BindProperty]

{
{
return Page();
}
Message = $"Customer {Customer.Name} added";
}
}
A marcação a seguir no arquivo Pages/Customers/Index.cshtml exibe o valor de Message usando TempData .
<h3>Msg: @Model.Message</h3>
O modelo de página Pages/Customers/Index.cshtml.cs aplica o atributo [TempData] à propriedade Message .
[TempData]
Consulte TempData para obter mais informações.
Vários manipuladores por página

A página a seguir gera marcação para dois manipuladores de página usando o auxiliar de marcas
asp-page-handler :
@page
@model CreateFATHModel
<html>
<body>
<p>
Enter your name.
</p>
<input type="submit" asp-page-handler="JoinList" value="Join" />
<input type="submit" asp-page-handler="JoinListUC" value="JOIN UC" />
</form>
</body>
</html>
O formulário no exemplo anterior tem dois botões de envio, cada um usando o FormActionTagHelper para
enviar para uma URL diferente. O atributo asp-page-handler é um complemento para asp-page .
asp-page-handler gera URLs que enviam para cada um dos métodos de manipulador definidos por uma
página. asp-page não foi especificado porque a amostra está vinculando à página atual.
O modelo de página:
namespace RazorPagesContacts.Pages.Customers
{
public class CreateFATHModel : PageModel
{
public CreateFATHModel(AppDbContext db)

{
_db = db;
}
[BindProperty]
public async Task<IActionResult> OnPostJoinListAsync()

{
{
return Page();
}
}
public async Task<IActionResult> OnPostJoinListUCAsync()

{
{
return Page();
}
Customer.Name = Customer.Name?.ToUpper();
return await OnPostJoinListAsync();
}
}
}
O código anterior usa métodos de manipulador nomeados. Métodos de manipulador nomeados são
criados colocando o texto no nome após On<HTTP Verb> e antes de Async (se houver). No exemplo anterior,
os métodos de página são OnPostJoinListAsync e OnPostJoinListUCAsync. Com OnPost e Async
removidos, os nomes de manipulador são JoinList e JoinListUC .

Usando o código anterior, o caminho da URL que envia a é

OnPostJoinListAsync
http://localhost:5000/Customers/CreateFATH?handler=JoinList . O caminho da URL que envia a
OnPostJoinListUCAsync é http://localhost:5000/Customers/CreateFATH?handler=JoinListUC .
Rotas personalizadas
Use a diretiva @page para:
Especifique uma rota personalizada para uma página. Por exemplo, a rota para a página Sobre pode ser
definida como /Some/Other/Path com @page "/Some/Other/Path" .
Acrescente segmentos à rota padrão de uma página. Por exemplo, um segmento de "item" pode ser
adicionado à rota padrão da página com @page "item" .
Acrescente parâmetros à rota padrão de uma página. Por exemplo, um parâmetro de ID, id , pode ser
necessário para uma página com @page "{id}" .
Há suporte para um caminho relativo à raiz designado por um til ( ~ ) no início do caminho. Por exemplo,
@page "~/Some/Other/Path" é o mesmo que @page "/Some/Other/Path" .
Você pode alterar a cadeia de caracteres de consulta ?handler=JoinList na URL para um segmento de rota
/JoinList ao especificar o modelo de rota @page "{handler?}" .
Se você não deseja a cadeia de consulta ?handler=JoinList na URL, você pode alterar a rota para colocar o
nome do manipulador na parte do caminho da URL. Você pode personalizar a rota adicionando um modelo
de rota entre aspas duplas após a diretiva @page .
@page "{handler?}"
@model CreateRouteModel
<html>
<body>
<p>
Enter your name.
</p>
</form>
</body>
</html>
Usando o código anterior, o caminho da URL que envia a OnPostJoinListAsync é

http://localhost:5000/Customers/CreateFATH/JoinList . O caminho da URL que envia a
OnPostJoinListUCAsync é http://localhost:5000/Customers/CreateFATH/JoinListUC .
O ? após handler significa que o parâmetro de rota é opcional.
Configuração e definições
Para configurar opções avançadas, use o método de extensão AddRazorPagesOptions no construtor de MVC:

{
services.AddMvc()
{
options.RootDirectory = "/MyPages";
options.Conventions.AuthorizeFolder("/MyPages/Admin");
});
}
No momento, você pode usar o RazorPagesOptions para definir o diretório raiz para páginas ou adicionar as
convenções de modelo de aplicativo para páginas. Permitiremos mais extensibilidade dessa maneira no
futuro.
Para pré-compilar exibições, consulte Compilação de exibição do Razor.
Baixar ou exibir código de exemplo.
Consulte a Introdução a Páginas do Razor, que se baseia nesta introdução.
Especificar que as Páginas Razor estão na raiz do conteúdo
Por padrão, as Páginas Razor estão na raiz do diretório /Pages. Adicione WithRazorPagesAtContentRoot
em AddMvc para especificar que as Páginas Razor estão na raiz do conteúdo (ContentRootPath) do
aplicativo:
services.AddMvc()
{
...
})
.WithRazorPagesAtContentRoot();
Especificar que as Páginas Razor estão em um diretório raiz personalizado

Adicione WithRazorPagesRoot em AddMvc para especificar que as Páginas Razor estão em um diretório
raiz personalizado no aplicativo (forneça um caminho relativo):
services.AddMvc()
{
...
})
.WithRazorPagesRoot("/path/to/razor/pages");
Recursos adicionais
Referência da sintaxe Razor para ASP.NET Core
Introdução às Páginas do Razor no ASP.NET Core
Convenções de autorização de páginas do Razor no ASP.NET Core
Convenções de rota e aplicativo das Páginas do Razor no ASP.NET Core
Testes de unidade de páginas do Razor no ASP.NET Core
Exibições parciais no ASP.NET Core
ASP.NET Core
usando o Visual Studio. Outras versões dessa série incluem uma versão do macOS e uma versão do Visual
Studio Code.
1. Introdução a Páginas do Razor
5. Atualizando as páginas
Após o tutorial, para adicionar um recurso de upload de arquivo ao aplicativo de amostra, confira Carregar
arquivos para uma Página Razor no ASP.NET Core.
Tutorial: introdução ao Razor Pages no ASP.NET
Core
Por Rick Anderson

Recomendamos que você siga a versão ASP.NET Core 2.1 deste tutorial. É muito mais fácil de seguir e
cobre muito mais recursos. Selecione ASP.NET Core 2.1 no seletor de versão.
Este tutorial ensina as noções básicas de criação de um aplicativo Web de Páginas do Razor do ASP.NET
Core. As Páginas do Razor são a maneira recomendada para criar a interface do usuário para aplicativos
Web no ASP.NET Core.
Windows: este tutorial
MacOS: Introdução a Páginas Razor com o Visual Studio para Mac
macOS, Linux e Windows: Introdução a Páginas Razor no ASP.NET Core no Visual Studio Code
Pré-requisitos
Criar um aplicativo Web do Razor

No menu Arquivo do Visual Studio, selecione Novo > Projeto.
Crie um novo Aplicativo Web ASP.NET Core. Nomeie o projeto RazorPagesMovie. É importante
nomear o projeto RazorPagesMovie de modo que os namespaces façam a correspondência quando
você copiar/colar código.
Selecione ASP.NET Core 2.1 na lista suspensa e selecione Aplicativo Web.
O modelo do Visual Studio cria um projeto inicial:

Pressione F5 para executar o aplicativo no modo de depuração ou Ctrl-F5 para executar sem anexar o
depurador. Selecione Aceitar para dar consentimento ao acompanhamento. Este aplicativo não
acompanha informações pessoais. O código de modelo gerado inclui ativos para ajudar a cumprir o
RGPD (Regulamento Geral sobre a Proteção de Dados).
A imagem a seguir mostra o aplicativo depois de aceitar o rastreamento:

O Visual Studio inicia o IIS Express e executa o aplicativo. A barra de endereços mostra
localhost:port# e não algo como example.com . Isso ocorre porque localhost é o nome do host
padrão do computador local. Localhost serve somente solicitações da Web do computador local.
Quando o Visual Studio cria um projeto Web, uma porta aleatória é usada para o servidor Web. Na
imagem anterior, o número da porta é 5001. Quando você executar o aplicativo, verá um número de
porta diferente.
Iniciar o aplicativo com Ctrl+F5 (modo de não depuração) permite que você faça alterações de
código, salve o arquivo, atualize o navegador e veja as alterações de código. Muitos desenvolvedores
preferem usar o modo de não depuração para iniciar o aplicativo rapidamente e exibir alterações.
O modelo padrão cria os links e páginas RazorPagesMovie, Início, Sobre e Contato. Dependendo do
tamanho da janela do navegador, talvez você precise clicar no ícone de navegação para mostrar os links.
Teste os links. Os links RazorPagesMovie e Início vão para a página de Índice. Os links Sobre e
Contato vão para as páginas About e Contact , respectivamente.
Pastas e arquivos de projeto

A tabela a seguir lista os arquivos e pastas no projeto. Para este tutorial, o arquivo Startup.cs é o mais
importante de se entender. Não é necessário examinar cada link fornecido abaixo. Os links são
fornecidos como uma referência para quando você precisar de mais informações sobre um arquivo ou
pasta no projeto.
ARQUIVO OU PASTA FINALIDADE
wwwroot Contém ativos estáticos. Confira Arquivos estáticos.
Páginas Pasta para Páginas do Razor.
appsettings.json Configuração
Program.cs Configura o host do aplicativo do ASP.NET Core.
Startup.cs Configura os serviços e o pipeline de solicitação.

Consulte Inicialização.
A pasta Pages/Shared
O arquivo _Layout.cshtml contém elementos HTML comuns (scripts e folhas de estilo) e define o layout
do aplicativo. Por exemplo, ao selecionar RazorPagesMovie, Início, Sobre ou Contato, um conjunto
comum de elementos aparece na página da Web. Os elementos comuns incluem o menu de navegação
na parte superior e o cabeçalho na parte inferior da janela. Veja Layout para obter mais informações.
O arquivo _ValidationScriptsPartial.cshtml fornece uma referência a scripts de validação jQuery. Quando
adicionarmos as páginas Create e Edit posteriormente no tutorial, o arquivo
_ValidationScriptsPartial.cshtml será usado.
O arquivo _CookieConsentPartial.cshtml fornece uma barra de navegação e conteúdo para resumir a
política de privacidade e de uso de cookies. Para saber mais sobre os ativos do RGPD incluídos no
projeto, confira Suporte ao RGPD (Regulamento Geral sobre a Proteção de Dados) da UE no ASP.NET
Core.
A pasta Páginas
O _ViewStart.cshtml define a propriedade Layout das Páginas do Razor para usar o arquivo
_Layout.cshtml. Veja Layout para obter mais informações.
O arquivo _ViewImports.cshtml contém diretivas do Razor que são importadas para cada Página do
Razor. Veja Importando diretivas compartilhadas para obter mais informações.
As páginas About , Contact e Index são páginas básicas que você pode usar para iniciar um aplicativo.
A página Error é usada para exibir informações de erro.
Use F7 para alternar entre um Razor Page e o PageModel

Para habilitar a alternância com F7 entre um Razor Page (arquivo *.cshtml) e o arquivo do C#
(*.cshtml.cs):
Selecione Ferramentas > Opções > Ambiente > Teclado
Insira ToggleRazorView em Mostrar comandos que contenham.
Selecione EditorContextMenus.CodeWindow.ToggleRazorView
Na caixa de entrada Pressionar teclas de atalho, pressione F7.
Selecione Atribuir > OK
Pré-requisitos

Crie um novo Aplicativo Web ASP.NET Core. Nomeie o projeto RazorPagesMovie. É
importante nomear o projeto RazorPagesMovie de modo que os namespaces façam a
correspondência quando você copiar/colar código.
NOTE
Para usar o ASP.NET Core com o .NET Framework, primeiro selecione .NET Framework na lista suspensa
mais à esquerda na caixa de diálogo e, em seguida, selecione a versão desejada do ASP.NET Core.
O modelo do Visual Studio cria um projeto inicial:
Pressione F5 para executar o aplicativo no modo de depuração ou Ctrl-F5 para executar sem anexar o
depurador
O Visual Studio inicia o IIS Express e executa o aplicativo. A barra de endereços mostra
localhost:port# e não algo como example.com . Isso ocorre porque localhost é o nome do host
padrão do computador local. Localhost serve somente solicitações da Web do computador local.
Quando o Visual Studio cria um projeto Web, uma porta aleatória é usada para o servidor Web. Na
imagem anterior, o número da porta é 5000. Quando você executar o aplicativo, verá um número de
porta diferente.
Iniciar o aplicativo com Ctrl+F5 (modo de não depuração) permite que você faça alterações de
código, salve o arquivo, atualize o navegador e veja as alterações de código. Muitos desenvolvedores
preferem usar o modo de não depuração para iniciar o aplicativo rapidamente e exibir alterações.
O modelo padrão cria os links e páginas RazorPagesMovie, Início, Sobre e Contato. Dependendo do
tamanho da janela do navegador, talvez você precise clicar no ícone de navegação para mostrar os links.
Teste os links. Os links RazorPagesMovie e Início vão para a página de Índice. Os links Sobre e
Contato vão para as páginas About e Contact , respectivamente.

A tabela a seguir lista os arquivos e pastas no projeto. Para este tutorial, o arquivo Startup.cs é o mais
importante de se entender. Não é necessário examinar cada link fornecido abaixo. Os links são
fornecidos como uma referência para quando você precisar de mais informações sobre um arquivo ou
pasta no projeto.
wwwroot Contém arquivos estáticos. Confira Arquivos estáticos.
Pages (Páginas) Pasta para Páginas do Razor.
Program.cs Hospeda o aplicativo ASP.NET Core.
Startup.cs Configura os serviços e o pipeline de solicitação.

Consulte Startup (Inicialização).
A pasta Páginas
O arquivo _Layout.cshtml contém elementos HTML comuns (scripts e folhas de estilo) e define o layout
para o aplicativo. Por exemplo, quando você clica em RazorPagesMovie, Início, Sobre ou Contato,
você vê os mesmos elementos. Os elementos comuns incluem o menu de navegação na parte superior e
o cabeçalho na parte inferior da janela. Veja Layout para obter mais informações.
O arquivo _ViewImports.cshtml contém diretivas do Razor que são importadas para cada Página do
Razor. Veja Importando diretivas compartilhadas para obter mais informações.
O _ViewStart.cshtml define a propriedade Layout das Páginas do Razor para usar o arquivo
_Layout.cshtml. Veja Layout para obter mais informações.
adicionarmos as páginas Create e Edit posteriormente no tutorial, o arquivo
_ValidationScriptsPartial.cshtml será usado.
As páginas About , Contact e Index são páginas básicas que você pode usar para iniciar um aplicativo.
A página Error é usada para exibir informações de erro. A página Privacy permite especificar detalhes
sobre a política de privacidade do site.
P R Ó X IM O : A D IC IO N A N D O U M
M ODELO
Adicionar um modelo a um aplicativo Páginas Razor
no ASP.NET Core
Por Rick Anderson

Nesta seção, você adiciona classes para gerenciamento de filmes em um banco de dados. Você usa essas classes
com o Entity Framework Core (EF Core) para trabalhar com um banco de dados. O EF Core é uma estrutura
ORM (de mapeamento relacional de objetos) que simplifica o código de acesso a dados que você precisa escrever.
As classes de modelo que você cria são conhecidas como classes de dados POCO (de "objetos CLR básicos")
porque elas não têm nenhuma dependência do EF Core. Elas definem as propriedades dos dados que são
armazenados no banco de dados.
Neste tutorial, você escreve as classes de modelo primeiro e o EF Core cria o banco de dados. Uma abordagem
alternativa não abordada aqui é gerar classes de modelo de um banco de dados existente.
Exiba ou baixe a amostra.
Adicionar um modelo de dados

No Gerenciador de Soluções, clique com o botão direito do mouse no projeto RazorPagesMovie > Adicionar >
Nova Pasta. Nomeie a pasta Models.
Clique com o botão direito do mouse na pasta Modelos. Selecione Adicionar > Classe. Nomeie a classe Movie e
substitua o conteúdo da classe Movie pelo seguinte código:
using System;
using System.ComponentModel.DataAnnotations.Schema;
namespace RazorPagesMovie.Models
{
public class Movie
{
public int ID { get; set; }
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }
public decimal Price { get; set; }
}
}
Fazer scaffold do modelo de filme

Nesta seção, é feito o scaffold do modelo de filme. Ou seja, a ferramenta de scaffolding gera páginas para
operações de CRUD (Criar, Ler, Atualizar e Excluir) para o modelo do filme.
Crie uma pasta Pages/Movies:
No Gerenciador de Soluções, clique com o botão direito do mouse na pasta Páginas > Adicionar > Nova
Pasta.
Dê à pasta o nome Movies
No Gerenciador de Soluções, clique com o botão direito do mouse na pasta Páginas/Filmes pasta > Adicionar
> Novo item com scaffold.
Na caixa de diálogo Adicionar Scaffold, selecione Razor Pages usando o Entity Framework (CRUD ) >
Adicionar.
Conclua a caixa de diálogo Adicionar Razor Pages usando o Entity Framework (CRUD ):
Na lista suspensa Classe de modelo, selecione Filme (RazorPagesMovie.Models).
Na linha Classe de contexto de dados, selecione o sinal + (+) e aceite o nome gerado
RazorPagesMovie.Models.RazorPagesMovieContext.
Selecione Adicionar.
O processo de scaffold cria e atualiza os arquivos a seguir:

Arquivos criados
Pages/Movies: Criar, Excluir, Detalhes, Editar, Índice. Essas páginas serão detalhadas no próximo tutorial.
Data/RazorPagesMovieContext.cs
Arquivo atualizado
Startup.cs: alterações nesse arquivo serão detalhadas na próxima seção.
appsettings.json: a cadeia de conexão usada para se conectar a um banco de dados local é adicionada.
Examinar o contexto registrado com a injeção de dependência

O ASP.NET Core é construído com a injeção de dependência. Serviços (como o contexto de BD do EF Core) são
registrados com injeção de dependência durante a inicialização do aplicativo. Os componentes que exigem esses
serviços (como as Páginas do Razor) recebem esses serviços por meio de parâmetros do construtor. O código de
construtor que obtém uma instância de contexto do BD será mostrado mais adiante no tutorial.
A ferramenta de scaffolding criou automaticamente um contexto de BD e o registrou no contêiner da injeção de
dependência.
Examine o método Startup.ConfigureServices . A linha destacada foi adicionada pelo scaffolder:
{
{
});
services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));
}
A classe principal que coordena a funcionalidade do EF Core de um modelo de dados é a classe de contexto de
BD. O contexto de dados deriva de Microsoft.EntityFrameworkCore.DbContext. O contexto de dados especifica
quais entidades são incluídas no modelo de dados. Neste projeto, a classe é chamada RazorPagesMovieContext .
{
public class RazorPagesMovieContext : DbContext
{
public RazorPagesMovieContext (DbContextOptions<RazorPagesMovieContext> options)
: base(options)
{
}
public DbSet<Movie> Movie { get; set; }

}
}
O código anterior cria uma propriedade DbSet<Movie> para o conjunto de entidades. Na terminologia do Entity
Framework, um conjunto de entidades normalmente corresponde a uma tabela de banco de dados. Uma entidade
corresponde a uma linha da tabela.
O nome da cadeia de conexão é passado para o contexto com a chamada de um método em um objeto
DbContextOptions. Para o desenvolvimento local, o sistema de configuração do ASP.NET Core lê a cadeia de
conexão do arquivo appsettings.json.
Executar a migração inicial

Nesta seção, você deve usar o PMC (Console de Gerenciador de Pacotes) para:
Adicione uma migração inicial.
Atualize o banco de dados com a migração inicial.
No menu Ferramentas, selecione Gerenciador de Pacotes NuGet > Console do Gerenciador de Pacotes.
No PMC, insira os seguintes comandos:
Add-Migration Initial
Update-Database
Como alternativa, é possível usar os seguintes comandos do .NET Core CLI na pasta do projeto:
dotnet ef migrations add Initial

dotnet ef database update
Ignore a mensagem de aviso a seguir, pois você corrigirá isso em um tutorial posterior:
Microsoft.EntityFrameworkCore.Model.Validation[30000]
No type was specified for the decimal column 'Price' on entity type 'Movie'. This will cause values to
be silently truncated if they do not fit in the default precision and scale. Explicitly specify the SQL server
column type that can accommodate all the values using 'ForHasColumnType()'.
O comando Add-Migration gera código para criar o esquema de banco de dados inicial. O esquema é baseado no
modelo especificado no RazorPagesMovieContext (no arquivo Data/RazorPagesMovieContext.cs). O argumento
Initial é usado para nomear as migrações. Você pode usar qualquer nome, mas, por convenção, escolha um
nome que descreve a migração. Consulte Introdução às migrações para obter mais informações.
O comando Update-Database executa o método Up no arquivo Migrations/{time-stamp }_InitialCreate.cs, que cria
o banco de dados.
Se você obtiver o erro:
SqlException: Cannot open database "RazorPagesMovieContext-GUID" requested by the login. The login failed.
Login failed for user 'User-name'.
Você perdeu a etapa de migrações.

Por Rick Anderson

No Gerenciador de Soluções, clique com o botão direito do mouse no projeto RazorPagesMovie > Adicionar >
Nova Pasta. Nomeie a pasta Models.
Clique com o botão direito do mouse na pasta Modelos. Selecione Adicionar > Classe. Nomeie a classe Movie e
adicione as seguintes propriedades:
Adicione as seguintes propriedades à classe Movie :
using System;
{
public class Movie
{
}
}
O campo ID é necessário para o banco de dados para a chave primária.

Adicionar uma classe de contexto de banco de dados
Adicione a seguinte classe MovieContext.cs à pasta Modelos:
{
public class MovieContext : DbContext
{
public MovieContext(DbContextOptions<MovieContext> options)
: base(options)
{
}

}
}
O código anterior cria uma propriedade DbSet para o conjunto de entidades. Na terminologia do Entity
Framework, um conjunto de entidades normalmente corresponde a uma tabela de banco de dados, enquanto
uma entidade corresponde a uma linha na tabela.
Adicionar uma cadeia de conexão de banco de dados
Adicione uma cadeia de conexão ao arquivo appsettings.json.
{
"Logging": {
"LogLevel": {
}
},
"ConnectionStrings": {
"MovieContext": "Server=(localdb)\\mssqllocaldb;Database=Movie-
1;Trusted_Connection=True;MultipleActiveResultSets=true"
}
}

Registre o contexto do banco de dados com o contêiner de injeção de dependência no método ConfigureServices
da classe Startup (Startup.cs):

{
// requires
// using RazorPagesMovie.Models;
// using Microsoft.EntityFrameworkCore;
services.AddDbContext<MovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("MovieContext")));
services.AddMvc();
}
Compile o projeto para verificar se não há erros.
Adicionar ferramentas de scaffold e executar a migração inicial

Nesta seção, você deve usar o PMC (Console de Gerenciador de Pacotes) para:
Adicione o pacote de geração de código da Web do Visual Studio. Esse pacote é necessário para executar o
mecanismo de scaffolding.
Adicionar uma migração inicial.
Install-Package Microsoft.VisualStudio.Web.CodeGeneration.Design -Version 2.0.3

Update-Database
Como alternativa, os seguintes comandos da CLI do .NET Core podem ser usados:
dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design

Ignore a mensagem a seguir:
Microsoft.EntityFrameworkCore.Model.Validation[30000]
No type was specified for the decimal column 'Price' on entity type 'Movie'. This will cause values to
be silently truncated if they do not fit in the default precision and scale. Explicitly specify the SQL server
column type that can accommodate all the values using 'ForHasColumnType()'
você corrigirá isso no próximo tutorial.

O comando Install-Package instala as ferramentas necessárias para executar o mecanismo de scaffolding.
O comando Add-Migration gera código para criar o esquema de banco de dados inicial. O esquema é baseado no
modelo especificado no DbContext (no arquivo Models/MovieContext.cs). O argumento Initial é usado para
nomear as migrações. Você pode usar qualquer nome, mas, por convenção, escolha um nome que descreve a
migração. Consulte Introdução às migrações para obter mais informações.
O comando Update-Database executa o método Up no arquivo Migrations/{time-stamp }_InitialCreate.cs, que cria
o banco de dados.
Fazer scaffolding do modelo de filme
Execute o seguinte na linha de comando (o diretório do projeto que contém os arquivos Program.cs,
Startup.cs e .csproj):
dotnet restore
dotnet aspnet-codegenerator razorpage -m Movie -dc MovieContext -udl -outDir Pages\Movies --
referenceScriptLibraries
No executable found matching command "dotnet-aspnet-codegenerator"
O erro anterior ocorre quando você está no diretório errado. Abra um shell de comando para o diretório do
projeto (o diretório que contém os arquivos Program.cs, Startup.cs e .csproj) e, em seguida, execute o comando
anterior.
The process cannot access the file

'RazorPagesMovie/bin/Debug/netcoreapp2.0/RazorPagesMovie.dll'
because it is being used by another process.
Saia do Visual Studio e execute o comando novamente.

A tabela a seguir detalha os parâmetros dos geradores de código do ASP.NET Core:
PARÂMETRO DESCRIÇÃO
-m O nome do modelo.
-dc O contexto de dados.
-udl Use o layout padrão.
-outDir O caminho da pasta de saída relativa para criar as exibições.
--referenceScriptLibraries Adiciona _ValidationScriptsPartial para editar e criar

páginas
Use a opção h para obter ajuda sobre o comando aspnet-codegenerator razorpage :
dotnet aspnet-codegenerator razorpage -h
Testar o aplicativo
Executar o aplicativo e acrescentar /Movies à URL no navegador ( http://localhost:port/movies ).
Teste o link Criar.
Teste os links Editar, Detalhes e Excluir.
Se você receber uma exceção SQL, verifique se executou migrações e atualizou o banco de dados.
O tutorial a seguir explica os arquivos criados por scaffolding.
A N T E R IO R : P R Ó X IM O : P Á G IN A S R A Z O R G E R A D A S P O R
IN T R O D U Ç Ã O S C A F F O L D IN G
Páginas do Razor geradas por scaffolding no
ASP.NET Core
Por Rick Anderson

Este tutorial examina as Páginas do Razor criadas por scaffolding no tutorial anterior.
As páginas Criar, Excluir, Detalhes e Editar.

Examine o Modelo de Página, Pages/Movies/Index.cshtml.cs:
using RazorPagesMovie.Models;
{
{
private readonly MovieContext _context;
public IndexModel(MovieContext context)

{
_context = context;
}
public IList<Movie> Movie { get;set; }

{
Movie = await _context.Movie.ToListAsync();
}
}
}
{
{
private readonly RazorPagesMovie.Models.RazorPagesMovieContext _context;
public IndexModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}
public IList<Movie> Movie { get; set; }

{
}
}
}
As Páginas do Razor são derivadas de PageModel . Por convenção, a classe derivada de PageModel é chamada de
<PageName>Model . O construtor usa injeção de dependência para adicionar o MovieContext à página. Todas as
páginas geradas por scaffolding seguem esse padrão. Consulte Código assíncrono para obter mais informações
sobre a programação assíncrona com o Entity Framework.
Quando uma solicitação é feita à página, o método OnGetAsync retorna uma lista de filmes para a Página do
Razor. OnGetAsync ou OnGet é chamado em uma Página do Razor para inicializar o estado da página. Nesse
caso, OnGetAsync obtém uma lista de filmes e os exibe.
Quando OnGet retorna void ou OnGetAsync retorna Task , então nenhum método de retorno é usado. Quando
o tipo de retorno for IActionResult ou Task<IActionResult> , é necessário fornecer uma instrução de retorno. Por
exemplo, o método OnPostAsync do arquivo Pages/Movies/Create.cshtml.cs:

{
{
return Page();
}
_context.Movie.Add(Movie);
await _context.SaveChangesAsync();
}
Examine a Página do Razor Pages/Movies/Index.cshtml:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel
@{
ViewData["Title"] = "Index";
}
<h2>Index</h2>
<p>
<a asp-page="Create">Create New</a>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Movie[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Movie[0].ReleaseDate)
</th>
<th>
@Html.DisplayNameFor(model => model.Movie[0].Genre)
</th>
<th>
@Html.DisplayNameFor(model => model.Movie[0].Price)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Movie) {
<tr>
<td>
@Html.DisplayFor(modelItem => item.Title)
</td>
<td>
@Html.DisplayFor(modelItem => item.ReleaseDate)
</td>
<td>
@Html.DisplayFor(modelItem => item.Genre)
</td>
<td>
@Html.DisplayFor(modelItem => item.Price)
</td>
<td>
<a asp-page="./Edit" asp-route-id="@item.ID">Edit</a> |
<a asp-page="./Details" asp-route-id="@item.ID">Details</a> |
<a asp-page="./Delete" asp-route-id="@item.ID">Delete</a>
</td>
</tr>
}
</tbody>
</table>
O Razor pode fazer a transição do HTML em C# ou em marcação específica do Razor. Quando um símbolo @ é
seguido por uma palavra-chave reservada do Razor, ele faz a transição para marcação específica do Razor, caso
contrário, ele faz a transição para C#.
A diretiva do Razor @page transforma o arquivo em uma ação do MVC —, o que significa que ele pode
manipular as solicitações. @page deve ser a primeira diretiva do Razor em uma página. @page é um exemplo de
transição para a marcação específica do Razor. Consulte Sintaxe Razor para obter mais informações.
Examine a expressão lambda usada no auxiliar HTML a seguir:
@Html.DisplayNameFor(model => model.Movie[0].Title))
O auxiliar HTML DisplayNameFor inspeciona a propriedade Title referenciada na expressão lambda para
determinar o nome de exibição. A expressão lambda é inspecionada em vez de avaliada. Isso significa que não há
nenhuma violação de acesso quando model , model.Movie ou model.Movie[0] são null ou vazios. Quando a
expressão lambda é avaliada (por exemplo, com @Html.DisplayFor(modelItem => item.Title) ), os valores de
propriedade do modelo são avaliados.
A diretiva @model
@page
A diretiva @model especifica o tipo de modelo passado para a Página do Razor. No exemplo anterior, a linha
@model torna a classe derivada de PageModel disponível para a Página do Razor. O modelo é usado nos
auxiliares HTML @Html.DisplayNameFor e @Html.DisplayName na página.
ViewData e layout
Considere o código a seguir:
@page
@{
}
O código realçado anterior é um exemplo de transição do Razor para C#. Os caracteres { e } circunscrevem
um bloco de código C#.
A classe base PageModel tem uma propriedade de dicionário ViewData que pode ser usada para adicionar os
dados que você deseja passar para uma exibição. Você adiciona objetos ao dicionário ViewData usando um
padrão de chave/valor. No exemplo anterior, a propriedade "Title" é adicionada ao dicionário ViewData .
A propriedade "Título" é usada no arquivo Pages/_Layout.cshtml. A marcação a seguir mostra as primeiras linhas
do arquivo Pages/Shared/_Layout.cshtml.
do arquivo Pages/_Layout.cshtml.
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - RazorPagesMovie</title>
@*Markup removed for brevity.*@
A linha @*Markup removed for brevity.*@é um comentário do Razor. Ao contrário de comentários HTML (
 ), comentários do Razor não são enviados ao cliente.
Execute o aplicativo e teste os links no projeto (Início, Sobre, Contato, Criar, Editar e Excluir). Cada página
define o título, que pode ser visto na guia do navegador. Quando você coloca um indicador em uma página, o
título é usado para o indicador. Pages/Index.cshtml e Pages/Movies/Index.cshtml atualmente têm o mesmo título,
mas você pode modificá-los para terem valores diferentes.
NOTE
Talvez você não consiga inserir casas decimais ou vírgulas no campo Price . Para dar suporte à validação do jQuery para
localidades de idiomas diferentes do inglês que usam uma vírgula (“,”) para um ponto decimal e formatos de data diferentes
do inglês dos EUA, você deve tomar medidas para globalizar o aplicativo. Veja Problema 4076 do GitHub para obter
instruções sobre como adicionar casas decimais.
A propriedade Layout é definida no arquivo Pages/_ViewStart.cshtml:
@{
Layout = "_Layout";
}
A marcação anterior define o arquivo de layout como Pages/Shared/_Layout.cshtml para todos os arquivos do
Razor na pasta Pages. Veja Layout para obter mais informações.
Atualizar o layout
Altere o elemento <title> no arquivo Pages/Shared/_Layout.cshtml para usar uma cadeia de caracteres mais
curta.
<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] - Movie</title>
Localizar o elemento de âncora a seguir no arquivo Pages/_Layout.cshtml.
<a asp-page="/Index" class="navbar-brand">RazorPagesMovie</a>
Substitua o elemento anterior pela marcação a seguir.
<a asp-page="/Movies/Index" class="navbar-brand">RpMovie</a>
O elemento de âncora anterior é um Auxiliar de Marcas. Nesse caso, ele é o Auxiliar de Marcas de Âncora. O
atributo e valor do auxiliar de marcas asp-page="/Movies/Index" cria um link para a Página do Razor
/Movies/Index .
Salve suas alterações e teste o aplicativo clicando no link RpMovie. Consulte o arquivo cshtml no GitHub.
O modelo Criar página
Examine o modelo de página Pages/Movies/Create.cshtml.cs:
// Unused usings removed.
{
{
public CreateModel(MovieContext context)

{
_context = context;
}

{
return Page();
}
[BindProperty]
public Movie Movie { get; set; }

{
{
return Page();
}
}
}
}
{
{
public CreateModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}

{
return Page();
}
[BindProperty]

{
{
return Page();
}
}
}
}
O método OnGet inicializa qualquer estado necessário para a página. A página Criar não tem nenhum estado
para inicializar, assim, Page é retornado. Mais adiante no tutorial, você verá o estado de inicialização do método
OnGet . O método Page cria um objeto PageResult que renderiza a página Create.cshtml.
A propriedade Movie usa o atributo [BindProperty] para aceitar o model binding. Quando o formulário Criar
posta os valores de formulário, o tempo de execução do ASP.NET Core associa os valores postados ao modelo
Movie .
O método OnPostAsync é executado quando a página posta dados de formulário:

{
{
return Page();
}
}
Se há algum erro de modelo, o formulário é reexibido juntamente com quaisquer dados de formulário postados.
A maioria dos erros de modelo podem ser capturados no lado do cliente antes do formulário ser enviado. Um
exemplo de um erro de modelo é postar, para o campo de data, um valor que não pode ser convertido em uma
data. Falaremos sobre a validação do lado do cliente e a validação de modelo posteriormente no tutorial.
Se não há nenhum erro de modelo, os dados são salvos e o navegador é redirecionado à página Índice.
A Página do Razor Criar
Examine o arquivo na Página do Razor Pages/Movies/Create.cshtml:
@page
@model RazorPagesMovie.Pages.Movies.CreateModel
@{
ViewData["Title"] = "Create";
}
<h2>Create</h2>
<h4>Movie</h4>
<hr />
<div class="row">
<div class="col-md-4">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<label asp-for="Movie.Title" class="control-label"></label>
<input asp-for="Movie.Title" class="form-control" />
<span asp-validation-for="Movie.Title" class="text-danger"></span>
</div>
<label asp-for="Movie.ReleaseDate" class="control-label"></label>
<input asp-for="Movie.ReleaseDate" class="form-control" />
<span asp-validation-for="Movie.ReleaseDate" class="text-danger"></span>
</div>
<label asp-for="Movie.Genre" class="control-label"></label>
<input asp-for="Movie.Genre" class="form-control" />
<span asp-validation-for="Movie.Genre" class="text-danger"></span>
</div>
<label asp-for="Movie.Price" class="control-label"></label>
<input asp-for="Movie.Price" class="form-control" />
<span asp-validation-for="Movie.Price" class="text-danger"></span>
</div>
<input type="submit" value="Create" class="btn btn-default" />
</div>
</form>
</div>
</div>
<div>
<a asp-page="Index">Back to List</a>
</div>
@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}
O Visual Studio exibe a marca <form method="post"> em uma fonte diferente usada para os auxiliares de marcas:
O elemento <form method="post"> é um auxiliar de marcas de formulário. O auxiliar de marcas de formulário
inclui automaticamente um token antifalsificação.
O mecanismo de scaffolding cria marcação do Razor para cada campo no modelo (exceto a ID ) semelhante ao
seguinte:

</div>
Os auxiliares de marcas de validação ( <div asp-validation-summary e <span asp-validation-for ) exibem erros de

validação. A validação será abordada em mais detalhes posteriormente nesta série.
O auxiliar de marcas de rótulo ( <label asp-for="Movie.Title" class="control-label"></label> ) gera a legenda do
rótulo e o atributo for para a propriedade Title .
O auxiliar de marcas de entrada ( <input asp-for="Movie.Title" class="form-control" /> ) usa os atributos
DataAnnotations e produz os atributos HTML necessários para validação jQuery no lado do cliente.
O tutorial a seguir explica o LocalDB do SQL Server e a propagação do banco de dados.
A N T E R IO R : A D IC IO N A N D O U M P R Ó X IM O : L O C A L D B D O S Q L
M ODELO SERVER
Trabalhar com o LocalDB do SQL Server e o
ASP.NET Core
Por Rick Anderson e Joe Audette

O objeto MovieContext cuida da tarefa de se conectar ao banco de dados e mapear objetos Movie para registros
do banco de dados. O contexto de banco de dados é registrado com o contêiner Injeção de Dependência no
método ConfigureServices no arquivo Startup.cs:

{
// requires
options.UseSqlServer(Configuration.GetConnectionString("MovieContext")));
services.AddMvc();
}

{
{
});
services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));
}
Para obter mais informações sobre os métodos usados em ConfigureServices , veja:

Suporte ao RGPD (Regulamento Geral sobre a Proteção de Dados) da UE no ASP.NET Core para
CookiePolicyOptions .
SetCompatibilityVersion
O sistema de Configuração do ASP.NET Core lê a ConnectionString . Para o desenvolvimento local, ele obtém a
cadeia de conexão do arquivo appsettings.json. O valor do nome do banco de dados ( Database={Database name} )
será diferente para o seu código gerado. O valor do nome é arbitrário.
"MovieContext": "Server=(localdb)\\mssqllocaldb;Database=Movie-
}
Quando você implanta o aplicativo em um servidor de teste ou de produção, você pode usar uma variável de
ambiente ou outra abordagem para definir a cadeia de conexão como um SQL Server real. Consulte
Configuração para obter mais informações.
SQL Server Express LocalDB

O LocalDB é uma versão leve do Mecanismo de Banco de Dados do SQL Server Express, que é direcionado para
o desenvolvimento de programas. O LocalDB é iniciado sob demanda e executado no modo de usuário e,
portanto, não há nenhuma configuração complexa. Por padrão, o banco de dados LocalDB cria arquivos “*.mdf”
no diretório C:/Users/<user>.
No menu Exibir, abra SSOX (Pesquisador de Objetos do SQL Server).
Clique com o botão direito do mouse na tabela Movie e selecione Designer de exibição:
Observe o ícone de chave ao lado de ID . Por padrão, o EF cria uma propriedade chamada ID para a chave
primária.
Clique com o botão direito do mouse na tabela Movie e selecione Exibir dados:
Propagar o banco de dados

Crie uma nova classe chamada SeedData na pasta Models. Substitua o código gerado pelo seguinte:
using System;
using System.Linq;
{
public static class SeedData
{
public static void Initialize(IServiceProvider serviceProvider)
{
using (var context = new MovieContext(
serviceProvider.GetRequiredService<DbContextOptions<MovieContext>>()))
{
// Look for any movies.
if (context.Movie.Any())
{
return; // DB has been seeded
}
context.Movie.AddRange(
new Movie
{
Title = "When Harry Met Sally",
ReleaseDate = DateTime.Parse("1989-2-12"),
Genre = "Romantic Comedy",
Price = 7.99M
},
new Movie
{
Title = "Ghostbusters",
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Title = "Ghostbusters 2",
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Title = "Rio Bravo",
Genre = "Western",
Price = 3.99M
}
);
context.SaveChanges();
}
}
}
}
using System;
using System.Linq;
{
{
{
using (var context = new RazorPagesMovieContext(
serviceProvider.GetRequiredService<DbContextOptions<RazorPagesMovieContext>>()))
{
{
}
new Movie
{
Price = 7.99M
},
new Movie
{
Title = "Ghostbusters ",
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Genre = "Western",
Price = 3.99M
}
);
}
}
}
}
Se houver um filme no BD, o inicializador de semeadura será retornado e nenhum filme será adicionado.
{
return; // DB has been seeded.
}
Adicionar o inicializador de semeadura

Em Program.cs, modifique o método Main para fazer o seguinte:
Obtenha uma instância de contexto de BD do contêiner de injeção de dependência.
Chame o método de semente passando a ele o contexto.
Descarte o contexto quando o método de semente for concluído.
O código a seguir mostra o arquivo Program.cs atualizado.

using Microsoft.AspNetCore;
using System;
namespace RazorPagesMovie
{
{
{
using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;
try
{
var context = services.GetRequiredService<MovieContext>();
// requires using Microsoft.EntityFrameworkCore;
context.Database.Migrate();
// Requires using RazorPagesMovie.Models;
SeedData.Initialize(services);
}
{
logger.LogError(ex, "An error occurred seeding the DB.");
}
}
host.Run();
}

.Build();
}
}
using System;
{
{
{

{
try
{
var context = services.GetRequiredService<RazorPagesMovieContext>();
}
{
}
}
host.Run();
}

}
}
Um aplicativo de produção não chamaria Database.Migrate . Ele é adicionado ao código anterior para evitar a
exceção a seguir quando Update-Database não foi executado:
SqlException: não pode abrir o banco de dados "RazorPagesMovieContext-21" solicitado pelo logon. O logon
falhou. O logon falhou para o usuário 'user name'.
Testar o aplicativo
Exclua todos os registros no BD. Faça isso com os links Excluir no navegador ou no SSOX
Force o aplicativo a ser inicializado (chame os métodos na classe Startup ) para que o método de
semeadura seja executado. Para forçar a inicialização, o IIS Express deve ser interrompido e reiniciado. Faça
isso com uma das seguintes abordagens:
Clique com botão direito do mouse no ícone de bandeja do sistema do IIS Express na área de
notificação e toque em Sair ou Parar site:
Se você estiver executando o VS no modo sem depuração, pressione F5 para executar no modo
de depuração.
Se você estiver executando o VS no modo de depuração, pare o depurador e pressione F5.
O aplicativo mostra os dados propagados:
O próximo tutorial limpará a apresentação dos dados.
A N T E R IO R : P Á G IN A S D O R A Z O R G E R A D A S P O R P R Ó X IM O : A T U A L IZ A Ç Ã O D A S
S C A F F O L D IN G P Á G IN A S
Atualizar as páginas geradas em um aplicativo
ASP.NET Core
Por Rick Anderson

Temos um bom começo para o aplicativo de filme, mas a apresentação não é ideal. Você não deseja ver a hora
(12:00:00 AM na imagem abaixo) e ReleaseDate deve ser Release Date (duas palavras).
Atualize o código gerado

Abra o arquivo Models/Movie.cs e adicione as linhas realçadas mostradas no seguinte código:
using System;
{
public class Movie
{
[Display(Name = "Release Date")]

[DataType(DataType.Date)]
}
}
using System;
{
public class Movie
{

[Column(TypeName = "decimal(18, 2)")]

}
}
Clique com o botão direito do mouse em uma linha vermelha ondulada > Ações Rápidas e Refatorações.
Selecione using System.ComponentModel.DataAnnotations;

O Visual Studio adiciona using System.ComponentModel.DataAnnotations; .
Clique com o botão direito do mouse em uma linha vermelha ondulada > Ações Rápidas e Refatorações no
atributo [Column] e selecione using System.ComponentModel.DataAnnotations.Schema;
A anotação de dados [Column(TypeName = "decimal(18, 2)")] é necessária para que o Entity Framework Core
possa mapear corretamente o Price para a moeda no banco de dados. Para obter mais informações, veja Tipos
de Dados.
O modelo concluído:
using System;
{
public class Movie
{


}
}
Abordaremos DataAnnotations no próximo tutorial. O atributo Display especifica o que deve ser exibido no nome
de um campo (neste caso, “Release Date” em vez de “ReleaseDate”). O atributo DataType especifica o tipo de
dados (Data) e, portanto, as informações de hora armazenadas no campo não são exibidas.
Procure Pages/Movies e focalize um link Editar para ver a URL de destino.
Os links Editar, Detalhes e Excluir são gerados pelo Auxiliar de Marcação de Âncora no arquivo
Pages/Movies/Index.cshtml.

<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
Os Auxiliares de Marcação permitem que o código do servidor participe da criação e renderização de elementos
HTML em arquivos do Razor. No código anterior, o AnchorTagHelper gera dinamicamente o valor do atributo
href HTML da página Razor (a rota é relativa), o asp-page e a ID da rota ( asp-route-id ). Consulte Geração de
URL para Páginas para obter mais informações.
Use Exibir Código-fonte em seu navegador favorito para examinar a marcação gerada. Uma parte do HTML
gerado é mostrada abaixo:
<td>
<a href="/Movies/Edit?id=1">Edit</a> |
<a href="/Movies/Details?id=1">Details</a> |
<a href="/Movies/Delete?id=1">Delete</a>
</td>
Os links gerados dinamicamente passam a ID de filme com uma cadeia de consulta (por exemplo,
http://localhost:5000/Movies/Details?id=2 ).
Atualize as Páginas Editar, Detalhes e Excluir do Razor para que elas usem o modelo de rota “{id:int}”. Altere a
diretiva de página de cada uma dessas páginas de @page para @page "{id:int}" . Execute o aplicativo e, em
seguida, exiba o código-fonte. O HTML gerado adiciona a ID à parte do caminho da URL:
<td>
<a href="/Movies/Edit/1">Edit</a> |
<a href="/Movies/Details/1">Details</a> |
<a href="/Movies/Delete/1">Delete</a>
</td>
Uma solicitação para a página com o modelo de rota “{id:int}” que não inclui o inteiro retornará um erro HTTP
404 (não encontrado). Por exemplo, http://localhost:5000/Movies/Details retornará um erro 404. Para tornar a
ID opcional, acrescente ? à restrição de rota:
@page "{id:int?}"
Atualizar o tratamento de exceção de simultaneidade

Atualize o método OnPostAsync no arquivo Pages/Movies/Edit.cshtml.cs. O seguinte código realçado mostra as
alterações:

{
{
return Page();
}
_context.Attach(Movie).State = EntityState.Modified;
try
{
}
{
if (!_context.Movie.Any(e => e.ID == Movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
}
O código anterior apenas detecta as exceções de simultaneidade quando o primeiro cliente simultâneo exclui o
filme e o segundo cliente simultâneo posta alterações no filme.
Para testar o bloco catch :
Definir um ponto de interrupção em catch (DbUpdateConcurrencyException)
Edite um filme.
Em outra janela do navegador, selecione o link Excluir do mesmo filme e, em seguida, exclua o filme.
Na janela do navegador anterior, poste as alterações no filme.
O código de produção geralmente detectará conflitos de simultaneidade quando dois ou mais clientes
atualizarem um registro ao mesmo tempo. Confira Lidar com conflitos de simultaneidade para obter mais
informações.
Análise de postagem e associação
Examine o arquivo Pages/Movies/Edit.cshtml.cs:
{
private readonly RazorPagesMovie.Models.MovieContext _context;
public EditModel(RazorPagesMovie.Models.MovieContext context)

{
_context = context;
}
[BindProperty]
public async Task<IActionResult> OnGetAsync(int? id)

{
if (id == null)
{
return NotFound();
}
Movie = await _context.Movie.SingleOrDefaultAsync(m => m.ID == id);
if (Movie == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
}
{
private readonly RazorPagesMovieContext _context;
public EditModel(RazorPagesMovieContext context)

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
if (Movie == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
}
Quando uma solicitação HTTP GET é feita para a página Movies/Edit (por exemplo,
http://localhost:5000/Movies/Edit/2 ):
O método OnGetAsync busca o filme do banco de dados e retorna o método Page .

O método Page renderiza a página Razor Pages/Movies/Edit.cshtml. O arquivo Pages/Movies/Edit.cshtml
contém a diretiva de modelo ( @model RazorPagesMovie.Pages.Movies.EditModel ), que disponibiliza o modelo de
filme na página.
O formulário Editar é exibido com os valores do filme.
Quando a página Movies/Edit é postada:
Os valores de formulário na página são associados à propriedade Movie . O atributo [BindProperty]
habilita o Model binding.
[BindProperty]
Se houver erros no estado do modelo (por exemplo, ReleaseDate não pode ser convertida em uma data),
o formulário será postado novamente com os valores enviados.
Se não houver erros do modelo, o filme será salvo.
Os métodos HTTP GET nas páginas Índice, Criar e Excluir do Razor seguem um padrão semelhante. O método
OnPostAsync HTTP POST na página Criar do Razor segue um padrão semelhante ao método OnPostAsync na
página Editar do Razor.
A pesquisa é adicionada no próximo tutorial.
A N T E R IO R : T R A B A L H A N D O C O M O L O C A L D B D O S Q L P R Ó X IM O : A D IC IO N A R
SERVER P E S Q U IS A
Adicionar a pesquisa às Páginas Razor do ASP.NET
Core
Por Rick Anderson

Neste documento, a funcionalidade de pesquisa é adicionada à página de Índice que permite pesquisar filmes por
gênero ou nome.
Adicione as seguintes propriedades realçadas em Pages/Movies/Index.cshtml.cs:

{
public IndexModel(RazorPagesMovie.Models.MovieContext context)

{
_context = context;
}

public string SearchString { get; set; }
public SelectList Genres { get; set; }
public string MovieGenre { get; set; }

{

{
_context = context;
}

SearchString : contém o texto que os usuários inserem na caixa de texto de pesquisa.

Genres : contém a lista de gêneros. Isso permite que o usuário selecione um gênero na lista.
MovieGenre : contém o gênero específico que o usuário seleciona (por exemplo, "Oeste").
Você trabalhará com as propriedades Genres e MovieGenre neste documento.

Atualize o método OnGetAsync da página de Índice pelo seguinte código:
public async Task OnGetAsync(string searchString)
{
var movies = from m in _context.Movie
select m;
if (!String.IsNullOrEmpty(searchString))
{
movies = movies.Where(s => s.Title.Contains(searchString));
}
Movie = await movies.ToListAsync();

SearchString = searchString;
}
A primeira linha do método OnGetAsync cria uma consulta LINQ para selecionar os filmes:
// using System.Linq;
select m;
A consulta é somente definida neste ponto; ela não foi executada no banco de dados.
Se o parâmetro searchString contiver uma cadeia de caracteres, a consulta de filmes será modificada para filtrar
a cadeia de caracteres de pesquisa:
{
}
O código s => s.Title.Contains() é uma Expressão Lambda. Lambdas são usados em consultas LINQ baseadas
em método como argumentos para métodos de operadores de consulta padrão, como o método Where ou
Contains (usado no código anterior ). As consultas LINQ não são executadas quando são definidas ou quando
são modificadas com uma chamada a um método (como Where , Contains ou OrderBy ). Em vez disso, a
execução da consulta é adiada. Isso significa que a avaliação de uma expressão é atrasada até que seu valor
realizado seja iterado ou o método ToListAsync seja chamado. Consulte Execução de consulta para obter mais
informações.
Observação: o método Contains é executado no banco de dados, não no código C#. A diferenciação de
maiúsculas e minúsculas na consulta depende do banco de dados e da ordenação. No SQL Server, Contains é
mapeado para SQL LIKE, que não diferencia maiúsculas de minúsculas. No SQLite, com a ordenação padrão, ele
diferencia maiúsculas de minúsculas.
Por fim, a linha final do método OnGetAsync preenche a propriedade SearchString com o valor de pesquisa do
usuário. Com a propriedade SearchString preenchida, o valor de pesquisa é mantido na caixa de pesquisa após a
execução da pesquisa.
Navegue para a página Movies e acrescente uma cadeia de consulta, como ?searchString=Ghost , à URL (por
exemplo, http://localhost:5000/Movies?searchString=Ghost ). Os filmes filtrados são exibidos.
Se o modelo de rota a seguir for adicionado à página de Índice, a cadeia de caracteres de pesquisa poderá ser
passada como um segmento de URL (por exemplo, http://localhost:5000/Movies/Ghost ).
@page "{searchString?}"
A restrição da rota anterior permite a pesquisa do título como dados de rota (um segmento de URL ), em vez de
como um valor de cadeia de caracteres de consulta. O ? em "{searchString?}" significa que esse é um
parâmetro de rota opcional.
No entanto, você não pode esperar que os usuários modifiquem a URL para pesquisar um filme. Nesta etapa, a
interface do usuário é adicionada para filtrar filmes. Se você adicionou a restrição de rota "{searchString?}" ,
remova-a.
Abra o arquivo Pages/Movies/Index.cshtml e, em seguida, adicione a marcação <form> realçada no seguinte
código:
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
Title: <input type="text" name="SearchString">
<input type="submit" value="Filter" />
</p>
</form>
A marcação <form> HTML usa o Auxiliar de Marcação de Formulário. Quando o formulário é enviado, a cadeia
de caracteres de filtro é enviada para a página Pages/Movies/Index. Salve as alterações e teste o filtro.
Pesquisar por gênero

Atualize o método OnGetAsync pelo seguinte código:
// Requires using Microsoft.AspNetCore.Mvc.Rendering;
public async Task OnGetAsync(string movieGenre, string searchString)
{
// Use LINQ to get list of genres.
IQueryable<string> genreQuery = from m in _context.Movie
orderby m.Genre
select m.Genre;

select m;
{
}
if (!String.IsNullOrEmpty(movieGenre))
{
movies = movies.Where(x => x.Genre == movieGenre);
}
Genres = new SelectList(await genreQuery.Distinct().ToListAsync());
}
O código a seguir é uma consulta LINQ que recupera todos os gêneros do banco de dados.

orderby m.Genre
select m.Genre;
O SelectList de gêneros é criado com a projeção dos gêneros distintos.
Adicionando uma pesquisa por gênero

Atualize Index.cshtml da seguinte maneira:
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
<select asp-for="MovieGenre" asp-items="Model.Genres">
<option value="">All</option>
</select>

</p>
</form>
<thead>
Teste o aplicativo pesquisando por gênero, título do filme e por ambos.
A N T E R IO R : A T U A L IZ A N D O A S P R Ó X IM O : A D IC IO N A N D O U M N O V O
P Á G IN A S CAM PO
Adicionar um novo campo em uma página Razor
no ASP.NET Core
Por Rick Anderson

Nesta seção, você usará as Migrações do Code First do Entity Framework para adicionar um novo campo ao
modelo e migrar essa alteração ao banco de dados.
Ao usar o Code First do EF para criar automaticamente um banco de dados, o Code First:
Adiciona uma tabela ao banco de dados para acompanhar se o esquema do banco de dados está
sincronizado com as classes de modelo das quais ele foi gerado.
Se as classes de modelo não estiverem em sincronia com o banco de dados, o EF gerará uma exceção.
Verificação automática de esquema/modelo em sincronia torna mais fácil encontrar problemas de código/banco
de dados inconsistente.
Adicionando uma propriedade de classificação ao modelo de filme

Abra o arquivo Models/Movie.cs e adicione uma propriedade Rating :
public class Movie

{

public string Rating { get; set; }
}
public class Movie

{


}
Compile o aplicativo (Ctrl+Shift+B ).

Edite Pages/Movies/Index.cshtml e adicione um campo Rating :
@page
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
</select>
Title: <input asp-for="SearchString">

</p>
</form>
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
@Html.DisplayNameFor(model => model.Movie[0].Rating)
</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.Rating)
</td>
<td>
</td>
</tr>
}
}
</tbody>
</table>
Adicione o campo Rating às páginas Excluir e Detalhes.

Atualize Create.cshtml com um campo Rating . Copie/cole o elemento <div> anterior e permita que o
IntelliSense ajude você a atualizar os campos. O IntelliSense funciona com os Auxiliares de Marcação.
O seguinte código mostra Create.cshtml com um campo Rating :

@page
@{
}
<h2>Create</h2>
<h4>Movie</h4>
<hr />
<div class="row">
</div>
</div>
</div>
</div>
<label asp-for="Movie.Rating" class="control-label"></label>
<input asp-for="Movie.Rating" class="form-control" />
<span asp-validation-for="Movie.Rating" class="text-danger"></span>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
Adicione o campo Rating à página Editar.

O aplicativo não funcionará até que o BD seja atualizado para incluir o novo campo. Se for executado agora, o
aplicativo gerará uma SqlException :
SqlException: Invalid column name 'Rating'.
Esse erro é causado devido à classe de modelo Movie atualizada ser diferente do esquema da tabela Movie do
banco de dados. (Não há nenhuma coluna Rating na tabela de banco de dados.)
Existem algumas abordagens para resolver o erro:
1. Faça com que o Entity Framework remova automaticamente e recrie o banco de dados usando o novo
esquema de classe de modelo. Essa abordagem é conveniente no início do ciclo de desenvolvimento; ela
permite que você desenvolva rapidamente o modelo e o esquema de banco de dados juntos. A
desvantagem é que você perde os dados existentes no banco de dados. Você não deseja usar essa
abordagem em um banco de dados de produção! A remoção do BD em alterações de esquema e o uso de
um inicializador para propagar automaticamente o banco de dados com os dados de teste é muitas vezes
uma maneira produtiva de desenvolver um aplicativo.
2. Modifique explicitamente o esquema do banco de dados existente para que ele corresponda às classes de
modelo. A vantagem dessa abordagem é que você mantém os dados. Faça essa alteração manualmente
ou criando um script de alteração de banco de dados.
3. Use as Migrações do Code First para atualizar o esquema de banco de dados.
Para este tutorial, use as Migrações do Code First.
Atualize a classe SeedData para que ela forneça um valor para a nova coluna. Uma alteração de amostra é
mostrada abaixo, mas é recomendável fazer essa alteração em cada bloco new Movie .
new Movie
{
Price = 7.99M,
Rating = "R"
},
Consulte o arquivo SeedData.cs concluído.

Consulte o arquivo SeedData.cs concluído.
Compile a solução.
Add-Migration Rating
Update-Database
O comando Add-Migration informa à estrutura:

Compare o modelo Movie com o esquema de BD Movie .
Crie um código para migrar o esquema de BD para o novo modelo.
O nome “Classificação” é arbitrário e é usado para nomear o arquivo de migração. É útil usar um nome
significativo para o arquivo de migração.
Se você excluir todos os registros no BD, o inicializador propagará o BD e incluirá o campo Rating . Faça isso
com os links Excluir no navegador ou no SSOX (Pesquisador de Objetos do SQL Server). Para excluir o banco de
dados do SSOX:
Selecione o banco de dados no SSOX.
Clique com o botão direito do mouse no banco de dados e selecione Excluir.
Marque Fechar conexões existentes.
Selecione OK.
No PMC, atualize o banco de dados:
Update-Database
Execute o aplicativo e verifique se você pode criar/editar/exibir filmes com um campo Rating . Se o banco de
dados não for propagado, pare o IIS Express e, em seguida, execute o aplicativo.
A N T E R IO R : A D IC IO N A N D O U M A P R Ó X IM O : A D IC IO N A N D O
P E S Q U IS A V A L ID A Ç Ã O
Adicionar validação a uma Página Razor do ASP.NET
Core
Por Rick Anderson

Nesta seção, a lógica de validação é adicionada para o modelo Movie . As regras de validação são impostas
sempre que um usuário cria ou edita um filme.
Validação
Um princípio-chave do desenvolvimento de software é chamado DRY (“Don't Repeat Yourself”). As Páginas
Razor incentivam o desenvolvimento quando a funcionalidade é especificada uma vez e ela é refletida em todo o
aplicativo. O DRY pode ajudar a reduzir a quantidade de código em um aplicativo. O DRY faz com que o código
seja menos propenso a erros e mais fácil de testar e manter.
O suporte de validação fornecido pelas Páginas Razor e pelo Entity Framework é um bom exemplo do princípio
DRY. As regras de validação são especificadas de forma declarativa em um único lugar (na classe de modelo) e as
regras são impostas em qualquer lugar no aplicativo.
Adicionando regras de validação ao modelo de filme
Abra o arquivo Models/Movie.cs. DataAnnotations fornece um conjunto interno de atributos de validação que
são aplicados de forma declarativa a uma classe ou propriedade. DataAnnotations também contém atributos de
formatação como DataType , que ajudam com a formatação e não fornecem validação.
Atualize a classe Movie para aproveitar os atributos de validação Required , StringLength , RegularExpression e
Range .
public class Movie

{
[StringLength(60, MinimumLength = 3)]

[Required]

[Range(1, 100)]
[DataType(DataType.Currency)]
[RegularExpression(@"^[A-Z]+[a-zA-Z""'\s-]*$")]
[Required]
[StringLength(30)]
[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$")]
[StringLength(5)]
[Required]
}
public class Movie
{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}
Os atributos de validação especificam o comportamento que é imposto nas propriedades do modelo:

Os atributos Required e MinimumLength indicam que uma propriedade deve ter um valor. No entanto, nada
impede que um usuário digite espaços em branco para atender à restrição de validação para um tipo de
permite valor nulo. Os tipos de valor que não permitem valores nulos (como decimal , int , float e
DateTime ) são inerentemente necessários e não precisam do atributo Required .
O atributo RegularExpression limita os caracteres que o usuário pode inserir. No código anterior, Genre
precisa começar com uma ou mais letras maiúsculas e seguir com zero ou mais letras, aspas simples ou
duplas, caracteres de espaço em branco ou traço. Rating precisa começar com uma ou mais letras
maiúsculas e seguir com zero ou mais letras, números, aspas simples ou duplas, caracteres de espaço em
branco ou traço.
O atributo Range restringe um valor a um intervalo especificado.
O atributo StringLength define o tamanho máximo de uma cadeia de caracteres e, opcionalmente, o tamanho
mínimo.
Ter as regras de validação automaticamente impostas pelo ASP.NET Core ajuda a tornar um aplicativo mais
robusto. A validação automática em modelos ajuda a proteger o aplicativo porque você não precisa se lembrar
de aplicá-los quando um novo código é adicionado.
Interface do usuário do erro de validação nas Páginas Razor
Execute o aplicativo e navegue para Pages/Movies.
Selecione o link Criar Novo. Preencha o formulário com alguns valores inválidos. Quando a validação do lado
do cliente do jQuery detecta o erro, ela exibe uma mensagem de erro.
NOTE
Talvez você não consiga inserir pontos decimais ou vírgulas no campo Price . Para dar suporte à validação do jQuery para
do inglês dos EUA, você deve tomar medidas para globalizar o aplicativo. Consulte Recursos adicionais para obter mais
informações. Por enquanto, insira apenas números inteiros como 10.
Observe como o formulário renderizou automaticamente uma mensagem de erro de validação em cada campo
que contém um valor inválido. Os erros são impostos no lado do cliente (usando o JavaScript e o jQuery) e no
lado do servidor (quando um usuário tem o JavaScript desabilitado).
Uma vantagem significativa é que nenhuma alteração de código foi necessária nas páginas Criar ou Editar.
Depois que DataAnnotations foi aplicado ao modelo, a interface do usuário de validação foi habilitada. As
Páginas Razor criadas neste tutorial selecionaram automaticamente as regras de validação (usando os atributos
de validação nas propriedades da classe do modelo Movie ). Validação do teste usando a página Editar: a mesma
validação é aplicada.
Os dados de formulário não serão postados no servidor enquanto houver erros de validação do lado do cliente.
Verifique se os dados de formulário não são postados por uma ou mais das seguintes abordagens:
Coloque um ponto de interrupção no método OnPostAsync . Envie o formulário (selecione Criar ou Salvar). O
ponto de interrupção nunca é atingido.
Use a ferramenta Fiddler.
Use as ferramentas do desenvolvedor do navegador para monitorar o tráfego de rede.
Validação do servidor
Quando o JavaScript está desabilitado no navegador, o envio do formulário com erros será postado no servidor.
(Opcional) Teste a validação do servidor:
Desabilite o JavaScript no navegador. É possível fazer isso usando as ferramentas para desenvolvedores
do navegador. Se você não conseguir desabilitar o JavaScript no navegador, tente outro navegador.
Defina um ponto de interrupção no método OnPostAsync da página Criar ou Editar.
Envie um formulário com erros de validação.
Verifique se o estado do modelo é inválido:
{
return Page();
}
O código a seguir mostra uma parte da página Create.cshtml gerada por scaffolding anteriormente no tutorial.
Ele é usado pelas páginas Criar e Editar para exibir o formulário inicial e exibir o formulário novamente, em caso
de erro.
</div>
O Auxiliar de Marcação de Entrada usa os atributos de DataAnnotations e produz os atributos HTML necessários
para a Validação do jQuery no lado do cliente. O Auxiliar de Marcação de Validação exibe erros de validação.
Consulte Validação para obter mais informações.
As páginas Criar e Editar não têm nenhuma regra de validação. As regras de validação e as cadeias de caracteres
de erro são especificadas somente na classe Movie . Essas regras de validação são aplicadas automaticamente às
Páginas Razor que editam o modelo Movie .
Quando a lógica de validação precisa ser alterada, ela é feita apenas no modelo. A validação é aplicada de forma
consistente em todo o aplicativo (a lógica de validação é definida em um único lugar). A validação em um único
lugar ajuda a manter o código limpo e facilita sua manutenção e atualização.
Usando atributos DataType

Examine a classe Movie . O namespace System.ComponentModel.DataAnnotations fornece atributos de formatação,
além do conjunto interno de atributos de validação. O atributo DataType é aplicado às propriedades
ReleaseDate e Price .
[Range(1, 100)]
Os atributos DataType fornecem apenas dicas para que o mecanismo de exibição formate os dados (e fornece
atributos como <a> para as URLs e <a href="mailto:EmailAddress.com"> para o email). Use o atributo
RegularExpression para validar o formato dos dados. O atributo DataType é usado para especificar um tipo de
dados mais específico do que o tipo intrínseco de banco de dados. Os atributos DataType não são atributos de
validação. No aplicativo de exemplo, apenas a data é exibida, sem a hora.
A Enumeração DataType fornece muitos tipos de dados, como Date, Time, PhoneNumber, Currency,
EmailAddress e muito mais. O atributo DataType também pode permitir que o aplicativo forneça
automaticamente recursos específicos a um tipo. Por exemplo, um link mailto: pode ser criado para
DataType.EmailAddress . Um seletor de data pode ser fornecido para DataType.Date em navegadores que dão
suporte a HTML5. Os atributos DataType emitem atributos data- HTML 5 (pronunciados “data dash”) que são
consumidos pelos navegadores HTML 5. Os atributos DataType não fornecem nenhuma validação.
DataType.Date não especifica o formato da data exibida. Por padrão, o campo de dados é exibido de acordo com
os formatos padrão com base nas CultureInfo do servidor.
de Dados.
O atributo DisplayFormat é usado para especificar explicitamente o formato de data:
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]

A configuração ApplyFormatInEditMode especifica que a formatação deve ser aplicada quando o valor é exibido
para edição. Não é recomendável ter esse comportamento em alguns campos. Por exemplo, em valores de
moeda, você provavelmente não deseja que o símbolo de moeda seja exibido na interface do usuário de edição.
O atributo DisplayFormat pode ser usado por si só, mas geralmente é uma boa ideia usar o atributo DataType . O
atributo DataType transmite a semântica dos dados, ao invés de apresentar como renderizá-lo em uma tela e
oferece os seguintes benefícios que você não obtém com DisplayFormat:
O navegador pode habilitar os recursos do HTML5 (por exemplo, mostrar um controle de calendário, o
símbolo de moeda apropriado à localidade, links de email, etc.)
Por padrão, o navegador renderizará os dados usando o formato correto de acordo com a localidade.
O atributo DataType pode permitir que a estrutura ASP.NET Core escolha o modelo de campo correto para
renderizar os dados. O DisplayFormat , se usado por si só, usa o modelo de cadeia de caracteres.
Observação: a validação do jQuery não funciona com os atributos Range e DateTime . Por exemplo, o seguinte
código sempre exibirá um erro de validação do lado do cliente, mesmo quando a data estiver no intervalo
especificado:
[Range(typeof(DateTime), "1/1/1966", "1/1/2020")]
Geralmente, não é uma boa prática compilar datas rígidas nos modelos e, portanto, o uso do atributo Range e de
DateTime não é recomendado.
O seguinte código mostra como combinar atributos em uma linha:
public class Movie

{

[Display(Name = "Release Date"), DataType(DataType.Date)]

[RegularExpression(@"^[A-Z]+[a-zA-Z""'\s-]*$"), Required, StringLength(30)]

[Range(1, 100), DataType(DataType.Currency)]

[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$"), StringLength(5)]
}
public class Movie

{




}
Comece com o Razor Pages e o EF Core mostra operações mais avançadas do EF Core com o Razor Pages.
Publicar no Azure
Para obter informações sobre como implantar no Azure, consulte Tutorial: compilar um aplicativo ASP.NET no
Azure com o Banco de Dados SQL. As instruções são para um aplicativo ASP.NET, não um aplicativo ASP.NET
Core, mas as etapas são as mesmas.
Obrigado por concluir esta introdução às Páginas Razor. Agradecemos os comentários. A Introdução ao Razor
Pages e ao EF Core é um excelente acompanhamento para este tutorial.
Recursos adicionais
Auxiliares de marca em formulários no ASP.NET Core
Globalização e localização no ASP.NET Core
Auxiliares de Marca no ASP.NET Core
Auxiliares de marca de autor no ASP.NET Core
A N T E R IO R : A D IC IO N A N D O U M N O V O
CAM PO
ASP.NET Core e o Visual Studio Code

usando o Visual Studio Code.
1. Introdução às Páginas do Razor com o VSCode
Introdução a Páginas Razor do ASP.NET Core no
Visual Studio Code
Por Rick Anderson

Este tutorial ensina as noções básicas de criação de um aplicativo Web de Páginas do Razor do ASP.NET Core.
Recomendamos que você conclua a Introdução a Páginas do Razor antes de iniciar este tutorial. Páginas do Razor
é a maneira recomendada para criar a interface do usuário para aplicativos Web no ASP.NET Core.
Pré-requisitos
Instale o seguinte:
Visual Studio Code
Visual Studio Code

Em um terminal, execute os seguintes comandos:
dotnet new webapp -o RazorPagesMovie

cd RazorPagesMovie
dotnet run
dotnet new razor -o RazorPagesMovie

cd RazorPagesMovie
dotnet run
Os comandos anteriores usam a CLI do .NET Core para criar e executar um projeto de Páginas do Razor. Abra
um navegador em http://localhost:5000 para exibir o aplicativo.
O modelo padrão cria os links e páginas RazorPagesMovie, Início, Sobre e Contato. Dependendo do tamanho
da janela do navegador, talvez você precise clicar no ícone de navegação para mostrar os links.
Teste os links. Os links RazorPagesMovie e Início vão para a página de Índice. Os links Sobre e Contato vão
para as páginas About e Contact , respectivamente.

A tabela a seguir lista os arquivos e pastas no projeto. Para este tutorial, o arquivo Startup.cs é o mais importante
de se entender. Não é necessário examinar cada link fornecido abaixo. Os links são fornecidos como uma
referência para quando você precisar de mais informações sobre um arquivo ou pasta no projeto.
Startup.cs Configura os serviços e o pipeline de solicitação. Consulte

Startup (Inicialização).
A pasta Páginas
O arquivo _Layout.cshtml contém elementos HTML comuns (scripts e folhas de estilo) e define o layout para o
aplicativo. Por exemplo, quando você clica em RazorPagesMovie, Início, Sobre ou Contato, você vê os
mesmos elementos. Os elementos comuns incluem o menu de navegação na parte superior e o cabeçalho na
parte inferior da janela. Veja Layout para obter mais informações.
O arquivo _ViewImports.cshtml contém diretivas do Razor que são importadas para cada Página do Razor. Veja
Importando diretivas compartilhadas para obter mais informações.
O _ViewStart.cshtml define a propriedade Layout das Páginas do Razor para usar o arquivo _Layout.cshtml. Veja
Layout para obter mais informações.
adicionarmos as páginas Create e Edit posteriormente no tutorial, o arquivo _ValidationScriptsPartial.cshtml
será usado.
As páginas About , Contact e Index são páginas básicas que você pode usar para iniciar um aplicativo. A página
Error é usada para exibir informações de erro. A página Privacy permite especificar detalhes sobre a política de
privacidade do site.
Abrir o projeto
Pressione Ctrl + C para encerrar o aplicativo.
No Visual Studio Code (VSCode), selecione Arquivo > Abrir Pasta e, em seguida, selecione a pasta
RazorPagesMovie.
Selecione Sim para a mensagem de Aviso "Os ativos necessários para criar e depurar estão ausentes no
'RazorPagesMovie'. Deseja adicioná-los?"
Selecione Restaurar para a mensagem Informativa "Há dependências não resolvidas".
Pressione Ctrl+F5 para iniciar o aplicativo sem depuração. Alternativamente, do menu Depurar, selecione Iniciar
Sem Depurar.
No próximo tutorial, adicionaremos um modelo para o projeto.
M ODELO
do ASP.NET Core com o Visual Studio Code
Por Rick Anderson


Adicione uma pasta denominada Modelos.
Adicionar uma classe denominada Movie.cs à pasta Modelos.
Adicione o código a seguir ao arquivo Models/Movie.cs:
using System;
{
public class Movie
{
}
}

{
{
: base(options)
{
}

}
}
{
"Logging": {
"LogLevel": {
}
},
"AllowedHosts": "*",
"MovieContext": "Data Source=MvcMovie.db"
}
}
Pacotes do NuGet do Entity Framework Core para SQLite

Na linha de comando, execute o seguinte comando de CLI do .NET Core:
dotnet add package Microsoft.EntityFrameworkCore.SQLite

{
{
// This lambda determines whether user consent for non-essential cookies is needed for a given
request.
});
options.UseSqlite(Configuration.GetConnectionString("MovieContext")));
}
Adicione os demonstrativos do using a seguir à parte superior do Startup.cs:


Pacotes NuGet do Entity Framework Core para migrações
As ferramentas do EF para a CLI (interface de linha de comando) são fornecidas em
Microsoft.EntityFrameworkCore.Tools.DotNet. Para instalar esse pacote, adicione-o à coleção
DotNetCliToolReference no arquivo .csproj. Observação: é necessário instalar este pacote editando o arquivo
.csproj; não é possível usar o comando install-package ou a GUI do Gerenciador de Pacotes.
Edite o arquivo RazorPagesMovie.csproj:
Selecione Arquivo > Abrir Arquivo, e, em seguida, selecione o arquivo RazorPagesMovie.csproj.
Adicione a referência da ferramenta para o Microsoft.EntityFrameworkCore.Tools.DotNet ao segundo
<ItemGroup>:
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Razor.Design" Version="2.1.2" PrivateAssets="All" />
<PackageReference Include="Microsoft.EntityFrameworkCore.SQLite" Version="2.1.4" />
</ItemGroup>
</Project>

Adicione as seguintes linhas ao arquivo RazorPagesMovie.csproj, logo antes da marca de fechamento </Project>
:
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.1.0-preview1-
final"/>
</ItemGroup>
Na linha de comando, execute os seguintes comandos de CLI do .NET Core:

dotnet restore
dotnet ef migrations add InitialCreate
O elemento DotNetCliToolReference e o comando add package instalam as ferramentas necessárias para

executar o mecanismo de scaffolding.
O comando ef migrations add InitialCreate gera código para criar o esquema de banco de dados inicial. O
esquema é baseado no modelo especificado no DbContext (no arquivo Models/MovieContext.cs). O argumento
InitialCreate é usado para nomear as migrações. Você pode usar qualquer nome, mas, por convenção, escolha
um nome que descreve a migração. Consulte Introdução às migrações para obter mais informações.
O comando ef database update executa o método Up no arquivo Migrations/<time-stamp>_InitialCreate.cs,
que cria o banco de dados.
Abra uma janela de comando no diretório do projeto (o diretório que contém os arquivos Program.cs,
Startup.cs e .csproj).
Execute o seguinte comando:
Observação: execute o comando a seguir no Windows. Para MacOS e Linux, consulte o próximo
comando
dotnet aspnet-codegenerator razorpage -m Movie -dc MovieContext -udl -outDir Pages\Movies --

No MacOS e Linux, execute o seguinte comando:
dotnet aspnet-codegenerator razorpage -m Movie -dc MovieContext -udl -outDir Pages/Movies --




páginas
Testar o aplicativo
Teste o link Criar.
Se você receber um erro similar ao seguinte, verifique se você executou migrações e atualizou o banco de dados:
An unhandled exception occurred while processing the request.

'no such table: Movie'.
ASP.NET Core
Por Rick Anderson


{
{

{
_context = context;
}

{
}
}
}
{
{

{
_context = context;
}

{
}
}
}
Razor. OnGetAsync ou OnGet é chamado em uma Página do Razor para inicializar o estado da página. Nesse caso,
OnGetAsync obtém uma lista de filmes e os exibe.

{
{
return Page();
}
}

@page
@{
}
<h2>Index</h2>
<p>
</p>
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
A diretiva do Razor @page transforma o arquivo em uma ação do MVC —, o que significa que ele pode manipular
as solicitações. @page deve ser a primeira diretiva do Razor em uma página. @page é um exemplo de transição
para a marcação específica do Razor. Consulte Sintaxe Razor para obter mais informações.
A diretiva @model
@page
@model torna a classe derivada de PageModel disponível para a Página do Razor. O modelo é usado nos auxiliares
HTML @Html.DisplayNameFor e @Html.DisplayName na página.
ViewData e layout
@page
@{
}
<!DOCTYPE html>
<html>
<head>
NOTE
@{
Layout = "_Layout";
}
Atualizar o layout
curta.
<!DOCTYPE html>
<html>
<head>
/Movies/Index .
{
{

{
_context = context;
}

{
return Page();
}
[BindProperty]

{
{
return Page();
}
}
}
}
{
{

{
_context = context;
}

{
return Page();
}
[BindProperty]

{
{
return Page();
}
}
}
}
Movie .

{
{
return Page();
}
}
@page
@{
}
<h2>Create</h2>
<h4>Movie</h4>
<hr />
<div class="row">
</div>
</div>
</div>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}

seguinte:

</div>

O tutorial a seguir explica o SQLite e a propagação do banco de dados.
A N T E R IO R : A D IC IO N A N D O U M P R Ó X IM O :
M ODELO S Q L IT E
Trabalhar com SQLite em um aplicativo ASP.NET
Core no Razor Pages
Por Rick Anderson

do banco de dados. O contexto de banco de dados é registrado no contêiner de DI (Injeção de Dependência) no

{
// requires
services.AddMvc();
}
Para obter mais informações de como usar o DbContext com a DI, confira Usando o DbContext com a DI.
SQLite
O site do SQLite afirma:
O SQLite é um mecanismo de banco de dados SQL independente, de alta confiabilidade, inserido, completo e
de domínio público. O SQLite é o mecanismo de banco de dados mais usado no mundo.
Há muitas ferramentas de terceiros que podem ser baixadas para gerenciar e exibir um banco de dados SQLite. A
imagem abaixo é do Navegador do DB para SQLite. Se você tiver uma ferramenta favorita do SQLite, deixe um
comentário sobre o que mais gosta dela.
using System;
using System.Linq;
{
{
{
{
{
}
new Movie
{
Price = 7.99M
},
new Movie
{
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Genre = "Western",
Price = 3.99M
}
);
}
}
}
}
Se houver um filme no BD, o inicializador de semeadura será retornado.

{
}

Adicione o inicializador de semeadura ao método Main no arquivo Program.cs:

using System;
{
{
{

{
try
{
}
{
}
}
host.Run();
}

.Build();
}
}
Testar o aplicativo
Exclua todos os registros no BD (para que o método de semeadura seja executado). Interrompa e inicie o
aplicativo para propagar o banco de dados.
O aplicativo mostra os dados propagados.
A N T E R IO R : A D IC IO N A N D O U M P R Ó X IM O : A T U A L IZ A R A S
M ODELO P Á G IN A S
Atualizar as páginas geradas
Por Rick Anderson


using System;
{
public class Movie
{

}
}
de Dados.
using System;
{
public class Movie
{


}
}

<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
<td>
</td>
<td>
</td>
@page "{id:int?}"

alterações:

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
Edite um filme.
informações.
{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
if (Movie == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
}
{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
if (Movie == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
}

filme na página.
[BindProperty]
A N T E R IO R : T R A B A L H A N D O C O M O A D IC IO N A R
S Q L L IT E P E S Q U IS A
Adicionar a pesquisa ao aplicativo Razor Pages do
ASP.NET Core
Por Rick Anderson

gênero ou nome.
@{
Layout = "_Layout";
}

{
select m;
{
}

}

select m;
Se o parâmetro searchString contiver uma cadeia de caracteres, a consulta de filmes será modificada para filtrar a
cadeia de caracteres de pesquisa:
{
}
Contains (usado no código anterior ). As consultas LINQ não são executadas quando são definidas ou quando são
modificadas com uma chamada a um método (como Where , Contains ou OrderBy ). Em vez disso, a execução da
consulta é adiada. Isso significa que a avaliação de uma expressão é atrasada até que seu valor realizado seja
iterado ou o método ToListAsync seja chamado. Consulte Execução de consulta para obter mais informações.
maiúsculas e minúsculas na consulta depende do banco de dados e do agrupamento. No SQL Server, Contains é
mapeado para SQL LIKE, que não diferencia maiúsculas de minúsculas. No SQLite, com o agrupamento padrão,
ele diferencia maiúsculas de minúsculas.
passada como um segmento de URL (por exemplo, http://localhost:5000/Movies/ghost ).
como um valor de cadeia de caracteres de consulta. O ? em "{searchString?}" significa que esse é um parâmetro
de rota opcional.
remova-a.
código:
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
</p>
</form>
A marcação <form> HTML usa o Auxiliar de Marcação de Formulário. Quando o formulário é enviado, a cadeia de
caracteres de filtro é enviada para a página Pages/Movies/Index. Salve as alterações e teste o filtro.

{

{
_context = context;
}

O SelectList Genres contém a lista de gêneros. Isso permite que o usuário selecione um gênero na lista.
A propriedade MovieGenre contém o gênero específico selecionado pelo usuário (por exemplo, “Faroeste”).

{
orderby m.Genre
select m.Genre;

select m;
{
}
{
}
}

orderby m.Genre
select m.Genre;

@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
</select>

</p>
</form>
<thead>
ASP.NET Core no macOS com o Visual Studio para
Mac

Esta série explica as noções básicas de criação de um aplicativo Web de Páginas do Razor com o ASP.NET Core
no macOS.
1. Introdução às Páginas do Razor no macOS
Introdução a Páginas Razor no ASP.NET Core no
macOS com o Visual Studio para Mac
Por Rick Anderson

Este tutorial ensina as noções básicas de criação de um aplicativo Web de Páginas do Razor do ASP.NET Core.
Recomendamos que você examine a Introdução a Páginas do Razor antes de iniciar este tutorial. Páginas do
Razor é a maneira recomendada para criar a interface do usuário para aplicativos Web no ASP.NET Core.
Pré-requisitos

dotnet new webapp -o RazorPagesMovie

cd RazorPagesMovie
dotnet run
dotnet new razor -o RazorPagesMovie

cd RazorPagesMovie
dotnet run
Os comandos anteriores usam a CLI do .NET Core para criar e executar um projeto de Páginas do Razor. Abra
um navegador em http://localhost:5000 para exibir o aplicativo.
O modelo padrão cria os links e páginas RazorPagesMovie, Início, Sobre e Contato. Dependendo do tamanho
da janela do navegador, talvez você precise clicar no ícone de navegação para mostrar os links.
Teste os links. Os links RazorPagesMovie e Início vão para a página de Índice. Os links Sobre e Contato vão
para as páginas About e Contact , respectivamente.

A tabela a seguir lista os arquivos e pastas no projeto. Para este tutorial, o arquivo Startup.cs é o mais importante
de se entender. Não é necessário examinar cada link fornecido abaixo. Os links são fornecidos como uma
referência para quando você precisar de mais informações sobre um arquivo ou pasta no projeto.
Startup.cs Configura os serviços e o pipeline de solicitação. Consulte

Startup (Inicialização).
A pasta Páginas
O arquivo _Layout.cshtml contém elementos HTML comuns (scripts e folhas de estilo) e define o layout para o
aplicativo. Por exemplo, quando você clica em RazorPagesMovie, Início, Sobre ou Contato, você vê os
mesmos elementos. Os elementos comuns incluem o menu de navegação na parte superior e o cabeçalho na
parte inferior da janela. Veja Layout para obter mais informações.
O arquivo _ViewImports.cshtml contém diretivas do Razor que são importadas para cada Página do Razor. Veja
Importando diretivas compartilhadas para obter mais informações.
O _ViewStart.cshtml define a propriedade Layout das Páginas do Razor para usar o arquivo _Layout.cshtml. Veja
Layout para obter mais informações.
adicionarmos as páginas Create e Edit posteriormente no tutorial, o arquivo _ValidationScriptsPartial.cshtml
será usado.
As páginas About , Contact e Index são páginas básicas que você pode usar para iniciar um aplicativo. A página
Error é usada para exibir informações de erro. A página Privacy permite especificar detalhes sobre a política de
privacidade do site.
Abrir o projeto
Pressione Ctrl + C para encerrar o aplicativo.
No Visual Studio, selecione Arquivo > Abrir e, em seguida, selecione o arquivo RazorPagesMovie.csproj.
No Visual Studio, selecione Executar > Iniciar Sem Depuração para iniciar o aplicativo. O Visual Studio inicia o
Kestrel, inicia um navegador e navega para http://localhost:5000 .
No próximo tutorial, adicionaremos um modelo para o projeto.
M ODELO
do ASP.NET Core com o Visual Studio para Mac
Por Rick Anderson


No Gerenciador de Soluções, clique com o botão direito do mouse no projeto RazorPagesMovie e então
selecione Adicionar > Nova Pasta. Nomeie a pasta Models.
Clique com o botão direito do mouse na pasta Modelos e, em seguida, selecione Adicionar > Novo
Arquivo.
Na caixa de diálogo Novo Arquivo:
Selecione Geral no painel esquerdo.
Selecione Classe Vazia no painel central.
Nomeie a classe Movie e selecione Novo.
using System;
{
public class Movie
{
}
}

{
{
: base(options)
{
}

}
}
{
"Logging": {
"LogLevel": {
}
},
"AllowedHosts": "*",
"MovieContext": "Data Source=MvcMovie.db"
}
}

{
{
request.
});
}
Clique com o botão direito do mouse em uma linha curvada vermelha, por exemplo, MovieContext na linha
services.AddDbContext<MovieContext>(options => . Selecione Correção Rápida > using
RazorPagesMovie.Models;. O Visual studio adiciona a instrução using.
Microsoft.EntityFrameworkCore.Tools.DotNet. Clique no link Microsoft.EntityFrameworkCore.Tools.DotNet para
obter o número de versão a ser usado. Para instalar esse pacote, adicione-o à coleção DotNetCliToolReference no
arquivo .csproj. Observação: é necessário instalar este pacote editando o arquivo .csproj; não é possível usar o
comando install-package ou a GUI do Gerenciador de Pacotes.
Para editar um arquivo .csproj:
Selecione Arquivo > Abrir, e, em seguida, selecione o arquivo .csproj.
Selecione Opções.
Alterar Abrir com para Editor de código-fonte.
Adicione a referência da ferramenta Microsoft.EntityFrameworkCore.Tools.DotNet para o segundo <ItemGroup>.:

<PropertyGroup>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Razor.Design" Version="2.1.2" PrivateAssets="All" />
<PackageReference Include="Microsoft.EntityFrameworkCore.SQLite" Version="2.1.4" />
</ItemGroup>
</Project>
Os números de versão mostrados no código a seguir estavam corretos no momento da gravação.

Adicione as seguintes linhas ao arquivo RazorPagesMovie.csproj, logo antes da marca de fechamento </Project>
:
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.1.0-preview1-
final"/>
</ItemGroup>

dotnet restore
O elemento DotNetCliToolReference e o comando add package instalam as ferramentas necessárias para

executar o mecanismo de scaffolding.
O comando ef migrations add InitialCreate gera código para criar o esquema de banco de dados inicial. O
esquema é baseado no modelo especificado no DbContext (no arquivo Models/MovieContext.cs). O argumento
InitialCreate é usado para nomear as migrações. Você pode usar qualquer nome, mas, por convenção, escolha
um nome que descreve a migração. Consulte Introdução às migrações para obter mais informações.
O comando ef database update executa o método Up no arquivo Migrations/<time-stamp>_InitialCreate.cs,
que cria o banco de dados.
Execute o seguinte na linha de comando (o diretório do projeto que contém os arquivos Program.cs,
Startup.cs e .csproj):
dotnet aspnet-codegenerator razorpage -m Movie -dc MovieContext -udl -outDir Pages/Movies --

No executable found matching command "dotnet-aspnet-codegenerator"
Abra um Shell de Comando no diretório do projeto (o diretório que contém os arquivos Program.cs, Startup.cs e
.csproj).



páginas
Testar o aplicativo
Teste o link Criar.
Se você receber um erro similar ao seguinte, verifique se você executou migrações e atualizou o banco de dados:

'no such table: Movie'.
Adicionar os arquivos de páginas/filmes ao projeto

No Visual Studio, clique com o botão direito do mouse na pasta Páginas e selecione Adicionar > Adicionar
Pasta Existente.
Selecione a pasta Filmes.
Na caixa de diálogo Escolher arquivos para incluir no projeto, selecione Incluir Todos.
ASP.NET Core
Por Rick Anderson


{
{

{
_context = context;
}

{
}
}
}
{
{

{
_context = context;
}

{
}
}
}
Razor. OnGetAsync ou OnGet é chamado em uma Página do Razor para inicializar o estado da página. Nesse caso,
OnGetAsync obtém uma lista de filmes e os exibe.

{
{
return Page();
}
}

@page
@{
}
<h2>Index</h2>
<p>
</p>
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
A diretiva do Razor @page transforma o arquivo em uma ação do MVC —, o que significa que ele pode manipular
as solicitações. @page deve ser a primeira diretiva do Razor em uma página. @page é um exemplo de transição
para a marcação específica do Razor. Consulte Sintaxe Razor para obter mais informações.
A diretiva @model
@page
@model torna a classe derivada de PageModel disponível para a Página do Razor. O modelo é usado nos auxiliares
HTML @Html.DisplayNameFor e @Html.DisplayName na página.
ViewData e layout
@page
@{
}
<!DOCTYPE html>
<html>
<head>
NOTE
@{
Layout = "_Layout";
}
Atualizar o layout
curta.
<!DOCTYPE html>
<html>
<head>
/Movies/Index .
{
{

{
_context = context;
}

{
return Page();
}
[BindProperty]

{
{
return Page();
}
}
}
}
{
{

{
_context = context;
}

{
return Page();
}
[BindProperty]

{
{
return Page();
}
}
}
}
Movie .

{
{
return Page();
}
}
@page
@{
}
<h2>Create</h2>
<h4>Movie</h4>
<hr />
<div class="row">
</div>
</div>
</div>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}

seguinte:

</div>

O tutorial a seguir explica o SQLite e a propagação do banco de dados.
A N T E R IO R : A D IC IO N A N D O U M P R Ó X IM O :
M ODELO S Q L IT E
Trabalhar com SQLite em um aplicativo ASP.NET
Core no Razor Pages
Por Rick Anderson

do banco de dados. O contexto de banco de dados é registrado no contêiner de DI (Injeção de Dependência) no

{
// requires
services.AddMvc();
}
Para obter mais informações de como usar o DbContext com a DI, confira Usando o DbContext com a DI.
SQLite
using System;
using System.Linq;
{
{
{
{
{
}
new Movie
{
Price = 7.99M
},
new Movie
{
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Genre = "Western",
Price = 3.99M
}
);
}
}
}
}

{
}


using System;
{
{
{

{
try
{
}
{
}
}
host.Run();
}

.Build();
}
}
Testar o aplicativo
A N T E R IO R : A D IC IO N A N D O U M P R Ó X IM O : A T U A L IZ A R A S
M ODELO P Á G IN A S
Atualizar as páginas geradas
Por Rick Anderson


using System;
{
public class Movie
{

}
}
de Dados.
using System;
{
public class Movie
{


}
}

<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
<td>
</td>
<td>
</td>
@page "{id:int?}"

alterações:

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
Edite um filme.
informações.
{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
if (Movie == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
}
{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
if (Movie == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
}

filme na página.
[BindProperty]
A N T E R IO R : T R A B A L H A R C O M O A D IC IO N A R
S Q L L IT E P E S Q U IS A
Adicionar a pesquisa ao aplicativo Razor Pages do
ASP.NET Core
Por Rick Anderson

gênero ou nome.
@{
Layout = "_Layout";
}

{
select m;
{
}

}

select m;
a cadeia de caracteres de pesquisa:
{
}
Contains (usado no código anterior ). As consultas LINQ não são executadas quando são definidas ou quando
são modificadas com uma chamada a um método (como Where , Contains ou OrderBy ). Em vez disso, a execução
da consulta é adiada. Isso significa que a avaliação de uma expressão é atrasada até que seu valor realizado seja
iterado ou o método ToListAsync seja chamado. Consulte Execução de consulta para obter mais informações.
maiúsculas e minúsculas na consulta depende do banco de dados e do agrupamento. No SQL Server, Contains é
mapeado para SQL LIKE, que não diferencia maiúsculas de minúsculas. No SQLite, com o agrupamento padrão,
ele diferencia maiúsculas de minúsculas.
passada como um segmento de URL (por exemplo, http://localhost:5000/Movies/ghost ).
como um valor de cadeia de caracteres de consulta. O ? em "{searchString?}" significa que esse é um
parâmetro de rota opcional.
remova-a.
código:
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
</p>
</form>
A marcação <form> HTML usa o Auxiliar de Marcação de Formulário. Quando o formulário é enviado, a cadeia
de caracteres de filtro é enviada para a página Pages/Movies/Index. Salve as alterações e teste o filtro.

{

{
_context = context;
}

O SelectList Genres contém a lista de gêneros. Isso permite que o usuário selecione um gênero na lista.
A propriedade MovieGenre contém o gênero específico selecionado pelo usuário (por exemplo, “Faroeste”).

{
orderby m.Genre
select m.Genre;

select m;
{
}
{
}
}

orderby m.Genre
select m.Genre;

@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
</select>

</p>
</form>
<thead>
Métodos de filtro para Páginas Razor no ASP.NET
Core
Por Rick Anderson

Os filtros de página Razor IPageFilter e IAsyncPageFilter permitem que as Páginas Razor executem código antes e
após a execução de um manipulador de Página Razor. Os filtros de página Razor são semelhantes aos filtros de
ação de MVC do ASP.NET Core, exceto que eles não podem ser aplicados aos métodos do manipulador de cada
página individual.
Filtros de página Razor:
Executam o código depois que um método do manipulador é selecionado, mas antes que o model binding
ocorra.
Executam o código antes que o método do manipulador seja executado, após a conclusão do model binding.
Executam o código após a execução do método do manipulador.
Podem ser implementados em uma única página ou globalmente.
Não podem ser aplicados a métodos do manipulador de uma página específica.
O código pode ser executado antes que um método do manipulador seja executado usando o construtor de
página ou o middleware, mas somente os filtros de página Razor têm acesso a HttpContext. Os filtros têm um
parâmetro derivado FilterContext, que fornece acesso a HttpContext . Por exemplo, a amostra Implementar um
atributo de filtro adiciona um cabeçalho à resposta, algo que não pode ser feito com construtores nem
middlewares.
Os filtros de página Razor fornecem os métodos a seguir, que podem ser aplicados globalmente ou no nível da
página:
Métodos síncronos:
OnPageHandlerSelected: chamado depois que um método do manipulador é selecionado, mas antes
que o model binding ocorra.
OnPageHandlerExecuting: chamado antes que o método do manipulador seja executado, após a
conclusão do model binding.
OnPageHandlerExecuted: chamado depois que o método do manipulador é executado, antes do
resultado da ação.
Métodos assíncronos:
OnPageHandlerSelectionAsync: chamado de forma assíncrona depois que o método do manipulador é
selecionado, mas antes que o model binding ocorra.
OnPageHandlerExecutionAsync: chamado de forma assíncrona, antes que o método do manipulador
seja invocado, após a conclusão do model binding.
NOTE
Implemente ou a versão assíncrona ou a versão síncrona de uma interface de filtro, não ambas. Primeiro, a estrutura verifica
se o filtro implementa a interface assíncrona e, se for esse o caso, a chama. Caso contrário, ela chama os métodos da
interface síncrona. Se ambas as interfaces forem implementadas, somente os métodos assíncronos serão chamados. A
mesma regra aplica-se para substituições em páginas. Implemente a versão síncrona ou a assíncrona da substituição, não
ambas.
Implementar filtros de página Razor globalmente

O código a seguir implementa IAsyncPageFilter :
using Microsoft.AspNetCore.Mvc.Filters;
namespace PageFilter.Filters
{
public class SampleAsyncPageFilter : IAsyncPageFilter
{
public SampleAsyncPageFilter(ILogger logger)

{
_logger = logger;
}
public async Task OnPageHandlerSelectionAsync(

PageHandlerSelectedContext context)
{
_logger.LogDebug("Global OnPageHandlerSelectionAsync called.");
await Task.CompletedTask;
}
public async Task OnPageHandlerExecutionAsync(

PageHandlerExecutingContext context,
PageHandlerExecutionDelegate next)
{
_logger.LogDebug("Global OnPageHandlerExecutionAsync called.");
}
}
}
No código anterior, ILogger não é necessário. Ele é usado na amostra para fornecer informações de rastreamento
do aplicativo.
O código a seguir habilita o SampleAsyncPageFilter na classe Startup :

{
services.AddMvc(options =>
{
options.Filters.Add(new SampleAsyncPageFilter(_logger));
});
}
O código a seguir mostra a classe Startup completa:

using PageFilter.Filters;
namespace PageFilter
{
{
ILogger _logger;
public Startup(ILoggerFactory loggerFactory, IConfiguration configuration)
{
_logger = loggerFactory.CreateLogger<GlobalFiltersLogger>();
}

{
{
options.Filters.Add(new SampleAsyncPageFilter(_logger));
});
}

{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
}
}
O código a seguir chama AddFolderApplicationModelConvention para aplicar o SampleAsyncPageFilter somente às

páginas em /subFolder:

{
services.AddMvc()
{
options.Conventions.AddFolderApplicationModelConvention(
"/subFolder",
model => model.Filters.Add(new SampleAsyncPageFilter(_logger)));
});
}
O código a seguir implementa o IPageFilter síncrono:

{
public class SamplePageFilter : IPageFilter
{
public SamplePageFilter(ILogger logger)

{
_logger = logger;
}
public void OnPageHandlerSelected(PageHandlerSelectedContext context)

{
_logger.LogDebug("Global sync OnPageHandlerSelected called.");
}
public void OnPageHandlerExecuting(PageHandlerExecutingContext context)

{
_logger.LogDebug("Global sync PageHandlerExecutingContext called.");
}
public void OnPageHandlerExecuted(PageHandlerExecutedContext context)

{
_logger.LogDebug("Global sync OnPageHandlerExecuted called.");
}
}
}
O código a seguir habilita o SamplePageFilter :

{
{
options.Filters.Add(new SamplePageFilter(_logger));
});
}
Implementar filtros de página Razor substituindo os métodos de filtro

O código a seguir substitui os filtros de página Razor síncronos:
namespace PageFilter.Pages
{
{
public IndexModel(ILogger<IndexModel> logger)

{
_logger = logger;
}
public void OnGet()

{
_logger.LogDebug("IndexModel/OnGet");
}
public override void OnPageHandlerSelected(

PageHandlerSelectedContext context)
{
_logger.LogDebug("IndexModel/OnPageHandlerSelected");
}
public override void OnPageHandlerExecuting(

PageHandlerExecutingContext context)
{
Message = "Message set in handler executing";
_logger.LogDebug("IndexModel/OnPageHandlerExecuting");
}
public override void OnPageHandlerExecuted(

PageHandlerExecutedContext context)
{
_logger.LogDebug("IndexModel/OnPageHandlerExecuted");
}
}
}
Implementar um atributo de filtro

O filtro baseado em atributo interno OnResultExecutionAsync pode tornar-se uma subclasse. O filtro a seguir
adiciona um cabeçalho à resposta:
{
public class AddHeaderAttribute : ResultFilterAttribute
{
private readonly string _name;
private readonly string _value;
public AddHeaderAttribute (string name, string value)

{
_name = name;
_value = value;
}
public override void OnResultExecuting(ResultExecutingContext context)

{
context.HttpContext.Response.Headers.Add(_name, new string[] { _value });
}
}
}
O código a seguir se aplica ao atributo AddHeader :
[AddHeader("Author", "Rick")]
public class ContactModel : PageModel
{
public ContactModel(ILogger<ContactModel> logger)

{
_logger = logger;
}

{
Message = "Your contact page.";
_logger.LogDebug("Contact/OnGet");
await Task.CompletedTask;
}
}
Confira Substituindo a ordem padrão para obter instruções sobre a substituição da ordem.
Confira Cancelamento e curto-circuito para obter instruções para causar um curto-circuito no pipeline do filtro
por meio de um filtro.
Autorizar o atributo de filtro

O atributo Authorize pode ser aplicado a um PageModel :
using Microsoft.AspNetCore.Authorization;
namespace PageFilter.Pages
{
[Authorize]
public class ModelWithAuthFilterModel : PageModel
{
public IActionResult OnGet() => Page();
}
}
Criar a interface do usuário reutilizável usando o
projeto de biblioteca de classes Razor no ASP.NET
Core
Por Rick Anderson

Modos de exibição do Razor, páginas, controladores, modelos de página, Componentes de exibição e modelos
de dados podem ser inseridos em uma RCL (Biblioteca de Classes Razor). A RCL pode ser e empacotada e
reutilizada. Os aplicativos podem incluir a RCL e substituir as exibições e as páginas que ela contém. Quando
uma exibição, uma exibição parcial ou uma página Razor for encontrada no aplicativo Web e na RCL, a marcação
Razor (arquivo .cshtml) no aplicativo Web terá precedência.
Este recurso requer SDK do .NET Core 2.1 ou posteriores
Criar uma biblioteca de classes contendo a interface do usuário do

Razor
Visual Studio
CLI do .NET Core
Selecione Aplicativo Web ASP.NET Core.
Dê um nome à biblioteca (por exemplo, "RazorClassLib") > OK. Para evitar uma colisão de nome de arquivo
com a biblioteca de exibição gerada, verifique se o nome da biblioteca não termina em .Views .
Verifique se o ASP.NET Core 2.1 ou posterior está selecionado.
Selecione Biblioteca de Classes Razor > OK.
Uma biblioteca de classes Razor tem o seguinte arquivo de projeto:
<Project Sdk="Microsoft.NET.Sdk.Razor">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.1.2" />
</ItemGroup>
</Project>
Adicione arquivos Razor na RCL.

Os modelos do ASP.NET Core, suponha que o conteúdo da RCL está no áreas pasta. Ver layout de páginas RCL
para criar uma RCL que expõe conteúdo em ~/Pages em vez de ~/Areas/Pages .
Referenciando o conteúdo da Biblioteca de Classes Razor

A RCL pode ser referenciada por:
Pacote do NuGet. Confira Criando pacotes do NuGet, dotnet add package e Criar e publicar um pacote do
NuGet.
{ProjectName}.csproj. Confira dotnet-add reference.
Passo a passo: Criar um projeto de biblioteca de classes Razor e usar

um projeto de Páginas Razor
Você pode baixar o projeto completo e testá-lo em vez de criá-lo. O download de exemplo contém um código
adicional e links que facilitam o teste do projeto. Você pode deixar comentários nesse problema do GitHub com
suas opiniões sobre os exemplos de download em relação às instruções passo a passo.
Testar o aplicativo de download
Se você não tiver baixado o aplicativo concluído e preferir criar o projeto do passo a passo, vá para a próxima
seção.
Visual Studio
CLI do .NET Core
Abra o arquivo .sln no Visual Studio. Execute o aplicativo.
Siga as instruções em Testar WebApp1
Criar uma Biblioteca de Classes Razor

Nesta seção, uma RCL (Biblioteca de Classes Razor) é criada. Arquivos Razor são adicionados à RCL.
Visual Studio
CLI do .NET Core
Crie o projeto da RCL:
Nomeie o aplicativo RazorUIClassLib > Okey.
Selecione Biblioteca de Classes Razor > OK.
Adicione um arquivo Razor de exibição parcial chamado
RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml.
Adicionar pastas e arquivos Razor ao projeto
Substitua a marcação em RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml pelo código a
seguir:
<h3>_Message.cshtml partial view.</h3>
<p>RazorUIClassLib\Areas\MyFeature\Pages\Shared\_Message.cshtml</p>
Substitua a marcação em RazorUIClassLib/Areas/MyFeature/Pages/Page1.cshtml pelo código a seguir:

@page
<h2>Hello from a Razor UI class library!</h2>

<p> From RazorUIClassLib\Areas\MyFeature\Pages\Page1.cshtml</p>
<partial name="_Message" />
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers é necessário para usar a exibição parcial (

<partial name="_Message" /> ). Em vez de incluir a diretiva @addTagHelper , você pode adicionar um arquivo
_ViewImports.cshtml. Por exemplo:
dotnet new viewimports -o RazorUIClassLib/Areas/MyFeature/Pages
Para obter mais informações sobre viewimports. cshtml, consulte importando diretivas compartilhadas
Crie a biblioteca de classes para verificar se não há nenhum erro de compilador:
dotnet build RazorUIClassLib
A saída do build contém RazorUIClassLib.dll e RazorUIClassLib.Views.dll. RazorUIClassLib.Views.dll contém o

conteúdo Razor compilado.
Use a biblioteca da interface do usuário do Razor de um projeto Páginas Razor
Visual Studio
CLI do .NET Core
Crie aplicativo Web Páginas Razor:
No Gerenciador de Soluções, clique com o botão direito do mouse na solução > Adicionar > Novo
Projeto.
Nomeie o aplicativo como WebApp1.
Selecione Aplicativo Web > OK.
No Gerenciador de Soluções, clique com o botão direito do mouse em WebApp1 e selecione Definir
como projeto de inicialização.
No Gerenciador de Soluções, clique com o botão direito do mouse em WebApp1 e selecione
Dependências de Build > Dependências do Projeto.
Marque RazorUIClassLib como uma dependência de WebApp1.
No Gerenciador de Soluções, clique com o botão direito do mouse em WebApp1 e selecione
Adicionar > Referência.
Na caixa de diálogo Gerenciador de Referências, marque RazorUIClassLib > OK.
Testar o WebApp1
Verifique se a biblioteca de classes da interface do usuário do Razor está sendo usada.
Navegue para /MyFeature/Page1 .
Substituir exibições, exibições parciais e páginas

Quando uma exibição, uma exibição parcial ou uma Página Razor for encontrada no aplicativo Web e na
Biblioteca de Classes Razor, a marcação Razor (arquivo .cshtml) no aplicativo Web terá precedência. Por
exemplo, adicione WebApp1/Areas/MyFeature/Pages/Page1.cshtml ao WebApp1, e a Page1 ao WebApp1 terá
precedência sobre a Page1 na biblioteca de classes Razor.
No download de exemplo, renomeie WebApp1/Areas/MyFeature2 como WebApp1/Areas/MyFeature para
testar a precedência.
Copie a exibição parcial RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml para
WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Atualize a marcação para indicar o novo local. Crie
e execute o aplicativo para verificar se a versão da parcial do aplicativo está sendo usada.
Layout de páginas RCL
A RCL como se fosse parte do aplicativo web de conteúdo de referência páginas pasta, crie o projeto da RCL
com a seguinte estrutura de arquivo:
RazorUIClassLib/páginas
RazorUIClassLib/páginas/Shared
Suponha RazorUIClassLib/páginas/Shared contém dois arquivos parciais: _Header.cshtml e _Footer.cshtml. O
<partial> marcas pode ser adicionadas ao layout. cshtml arquivo:
<body>
<partial name="_Header">
@RenderBody()
<partial name="_Footer">
</body>
Convenções de rota e aplicativo das Páginas do
Razor no ASP.NET Core
Por Luke Latham

Saiba como usar a página convenções do provedor de modelo de rota e aplicativo para controlar o roteamento, a
descoberta e o processamento de páginas nos aplicativos Páginas do Razor.
Quando precisar configurar rotas de página personalizadas para páginas individuais, configure o roteamento para
páginas com a convenção AddPageRoute descrita mais adiante neste tópico.
Para especificar uma rota de página, adicione segmentos de rota ou adicionar parâmetros a uma rota, use a página
@page diretiva. Para obter mais informações, consulte rotas personalizadas.
Há palavras reservadas não podem ser usadas como segmentos de rota ou nomes de parâmetro. Para obter mais
informações, consulte roteamento: roteamentos nomes reservados.
CENÁRIO A AMOSTRA EXPLICA...
Convenções de modelo Adicione um cabeçalho e um modelo de rota às páginas de

um aplicativo.
Conventions.Add
IPageRouteModelConvention
IPageApplicationModelConvention
Convenções de ação da rota de página Adicione um modelo de rota às páginas em uma pasta e a
AddFolderRouteModelConvention uma única página.
AddPageRouteModelConvention
AddPageRoute
Convenções de ação do modelo de página Adicione um cabeçalho às páginas em uma pasta, adicione um
AddFolderApplicationModelConvention cabeçalho a uma única página e configure um alocador de
AddPageApplicationModelConvention filtro para adicionar um cabeçalho às páginas de um aplicativo.
ConfigureFilter (classe de filtro, expressão lambda ou
alocador de filtro)
Provedor de modelo de aplicativo de página padrão Substitua o provedor de modelo de página padrão para
alterar as convenções de nomes de manipulador.
Convenções de modelo Adicione um cabeçalho e um modelo de rota às páginas de

um aplicativo.
Conventions.Add
IPageRouteModelConvention
IPageApplicationModelConvention
IPageHandlerModelConvention
Convenções de ação da rota de página Adicione um modelo de rota às páginas em uma pasta e a
AddFolderRouteModelConvention uma única página.
AddPageRouteModelConvention
AddPageRoute
Convenções de ação do modelo de página Adicione um cabeçalho às páginas em uma pasta, adicione um
AddFolderApplicationModelConvention cabeçalho a uma única página e configure um alocador de
AddPageApplicationModelConvention filtro para adicionar um cabeçalho às páginas de um aplicativo.
ConfigureFilter (classe de filtro, expressão lambda ou
alocador de filtro)
Provedor de modelo de aplicativo de página padrão Substitua o provedor de modelo de página padrão para
alterar as convenções de nomes de manipulador.
As convenções de Páginas Razor são adicionadas e configuradas usando o método de extensão

AddRazorPagesOptions para AddMvc na coleção de serviços na classe Startup . Os exemplos de convenção a
seguir estão descritos mais adiante neste tópico:

{
services.AddMvc()
{
options.Conventions.Add( ... );
options.Conventions.AddFolderRouteModelConvention("/OtherPages", model => { ... });
options.Conventions.AddPageRouteModelConvention("/About", model => { ... });
options.Conventions.AddPageRoute("/Contact", "TheContactPage/{text?}");
options.Conventions.AddFolderApplicationModelConvention("/OtherPages", model => { ... });
options.Conventions.AddPageApplicationModelConvention("/About", model => { ... });
options.Conventions.ConfigureFilter(model => { ... });
options.Conventions.ConfigureFilter( ... );
});
}
Ordem de rota
As rotas especificam um Order para processamento (rota correspondente).
PEDIDO COMPORTAMENTO
-1 A rota é processada antes de outras rotas são processadas.
0 Ordem não for especificada (valor padrão). Não atribui Order

( Order = null ) usa como padrão a rota Order como 0
(zero) para processamento.
1, 2, … n Especifica a ordem de processamento de rota.
Processamento de rota é estabelecido por convenção:

As rotas são processadas em ordem sequencial (-1, 0, 1, 2, … n).
Quando as rotas têm a mesma Order , a maioria dos rota específica é correspondida primeiro, seguido por
rotas menos específicas.
Quando as rotas com o mesmo Order e o mesmo número de parâmetros corresponde a uma URL de
solicitação, as rotas são processadas na ordem em que eles forem adicionados à PageConventionCollection.
Se possível, evite dependendo de uma ordem de processamento de rota estabelecido. Em geral, o roteamento
seleciona a rota correta com a URL correspondente. Se você deve definir a rota Order propriedades para rotear
solicitações corretamente, o esquema do aplicativo roteamento é provavelmente confuso para os clientes e frágil
para manter. Para simplificar o esquema do aplicativo roteamento de busca. O aplicativo de exemplo requer uma
rota explícita de processamento de pedido para demonstrar os vários cenários de roteamento usando um único
aplicativo. No entanto, você deve tentar evitar a prática de rota de configuração Order em aplicativos de
produção.
Roteamento do Razor Pages e do controlador do MVC compartilham uma implementação. Informações sobre a
ordem de rota nos tópicos MVC estão disponíveis em roteamento para ações do controlador: ordenação de rotas
de atributo.
Convenções de modelo
Adicione um representante para IPageConvention para adicionar as convenções de modelo que se aplicam às
Páginas Razor.
Adicionar uma convenção de modelo de rota para todas as páginas
Use Convenções para criar e adicionar um IPageRouteModelConvention à coleção de instâncias de
IPageConvention que são aplicadas durante a construção do modelo de rota de página.
O aplicativo de exemplo adiciona um modelo de rota {globalTemplate?} a todas as páginas no aplicativo:
public class GlobalTemplatePageRouteModelConvention

: IPageRouteModelConvention
{
public void Apply(PageRouteModel model)
{
var selectorCount = model.Selectors.Count;
for (var i = 0; i < selectorCount; i++)
{
var selector = model.Selectors[i];
model.Selectors.Add(new SelectorModel
{
AttributeRouteModel = new AttributeRouteModel
{
Order = 1,
Template = AttributeRouteModel.CombineTemplates(
selector.AttributeRouteModel.Template,
"{globalTemplate?}"),
}
});
}
}
}
A propriedade Order do AttributeRouteModel é definida como 1 . Isso garante que a rota correspondência de
comportamento no aplicativo de exemplo a seguir:
Um modelo de rota para TheContactPage/{text?} é adicionado posteriormente no tópico. A rota de página
Contact tem uma ordem padrão de null ( Order = 0 ), para que ele corresponda ao antes do
{globalTemplate?} modelo de rota.
Um {aboutTemplate?} modelo de rota é adicionado posteriormente no tópico. O modelo {aboutTemplate?}
recebe uma Order de 2 . Quando a página About é solicitada no /About/RouteDataValue , "RouteDataValue" é
carregado no RouteData.Values["globalTemplate"] ( Order = 1 ) e não RouteData.Values["aboutTemplate"] (
Order = 2 ) devido à configuração da propriedade Order .
Um {otherPagesTemplate?} modelo de rota é adicionado posteriormente no tópico. O modelo
{otherPagesTemplate?} recebe uma Order de 2 . Quando qualquer página na páginas/OtherPages pasta for
solicitada com um parâmetro de rota (por exemplo, /OtherPages/Page1/RouteDataValue ), "RouteDataValue" é
carregado no RouteData.Values["globalTemplate"] ( Order = 1 ) e não RouteData.Values["otherPagesTemplate"] (
Order = 2 ) devido à configuração de Order propriedade.
Sempre que possível, não defina a Order , que resulta em Order = 0 . Dependem de roteamento para selecionar a
rota correta.
As opções de Páginas Razor, como a adição de Convenções, são adicionados quando o MVC é adicionado à
coleção de serviços em Startup.ConfigureServices . Para obter um exemplo, confira o aplicativo de exemplo.
options.Conventions.Add(new GlobalTemplatePageRouteModelConvention());
Solicite a página About da amostra em localhost:5000/About/GlobalRouteValue e inspecione o resultado:
Adicionar uma convenção de modelo de aplicativo para todas as páginas

Use Convenções para criar e adicionar um IPageApplicationModelConvention à coleção de instâncias de
IPageConvention que são aplicadas durante a construção do modelo de aplicativo de página.
Para demonstrar isso e outras convenções mais adiante no tópico, o aplicativo de exemplo inclui uma classe
AddHeaderAttribute . O construtor de classe aceita uma cadeia de caracteres name e uma matriz de cadeia de
caracteres values . Esses valores são usados em seu método OnResultExecuting para definir um cabeçalho de
resposta. A classe completa é mostrada na seção Convenções de ação do modelo de página mais adiante no
tópico.
O aplicativo de exemplo usa a classe AddHeaderAttribute para adicionar um cabeçalho, GlobalHeader , a todas as
páginas no aplicativo:
public class GlobalHeaderPageApplicationModelConvention
: IPageApplicationModelConvention
{
public void Apply(PageApplicationModel model)
{
model.Filters.Add(new AddHeaderAttribute(
"GlobalHeader", new string[] { "Global Header Value" }));
}
}
Startup.cs:
options.Conventions.Add(new GlobalHeaderPageApplicationModelConvention());
Solicite a página About da amostra em localhost:5000/About e inspecione os cabeçalhos para exibir o resultado:
Adicionar uma convenção de modelo de manipulador a todas as páginas

Use Convenções para criar e adicionar um IPageHandlerModelConvention à coleção de instâncias de
IPageConvention que são aplicadas durante a construção do modelo de manipulador de página.
public class GlobalPageHandlerModelConvention

: IPageHandlerModelConvention
{
public void Apply(PageHandlerModel model)
{
...
}
}
Startup.ConfigureServices :
services.AddMvc()
{
options.Conventions.Add(new GlobalPageHandlerModelConvention());
});
Convenções de ação da rota de página

O provedor de modelo de rota padrão derivado de IPageRouteModelProvider invoca convenções que foram
projetadas para fornecer pontos de extensibilidade para configuração de rotas de página.
Convenção de modelo de rota de pasta
Use AddFolderRouteModelConvention para criar e adicionar uma IPageRouteModelConvention que invoca uma
ação no PageRouteModel para todas as páginas da pasta especificada.
O aplicativo de exemplo usa AddFolderRouteModelConvention para adicionar um modelo de rota
{otherPagesTemplate?} às páginas da pasta OtherPages:
options.Conventions.AddFolderRouteModelConvention("/OtherPages", model =>

{
{
{
{
Order = 2,
"{otherPagesTemplate?}"),
}
});
}
});
A propriedade Order do AttributeRouteModel é definida como 2 . Isso garante que o modelo para
{globalTemplate?} (definido anteriormente no tópico para 1 ) tem prioridade para os dados de rota a primeira
posição de valor quando um único valor de rota é fornecido. Se uma página na páginas/OtherPages pasta for
solicitada com um valor de parâmetro de rota (por exemplo, /OtherPages/Page1/RouteDataValue ), "RouteDataValue"
é carregado no RouteData.Values["globalTemplate"] ( Order = 1 ) e não RouteData.Values["otherPagesTemplate"] (
Order = 2 ) devido à configuração de Order propriedade.
rota correta.
Solicite a página Page1 da amostra em localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue e
inspecione o resultado:
Convenção de modelo de rota de página

Use AddPageRouteModelConvention para criar e adicionar uma IPageRouteModelConvention que invoca uma
ação no PageRouteModel para a página com o nome especificado.
O aplicativo de exemplo usa AddPageRouteModelConvention para adicionar um modelo de rota {aboutTemplate?} à
página About:
options.Conventions.AddPageRouteModelConvention("/About", model =>
{
{
{
{
Order = 2,
"{aboutTemplate?}"),
}
});
}
});
A propriedade Order do AttributeRouteModel é definida como 2 . Isso garante que o modelo para
{globalTemplate?} (definido anteriormente no tópico para 1 ) tem prioridade para os dados de rota a primeira
posição de valor quando um único valor de rota é fornecido. Se a página About é solicitada com um valor de
parâmetro de rota no /About/RouteDataValue , "RouteDataValue" é carregado no
RouteData.Values["globalTemplate"] ( Order = 1 ) e não RouteData.Values["aboutTemplate"] ( Order = 2 ) devido à
configuração de Order propriedade.
rota correta.
Solicite a página About da amostra em localhost:5000/About/GlobalRouteValue/AboutRouteValue e inspecione o
resultado:
Usar um transformador de parâmetro para personalizar rotas de página

Rotas de página geradas pelo ASP.NET Core podem ser personalizadas usando um transformador de parâmetro.
Um transformador de parâmetro implementa IOutboundParameterTransformer e transforma o valor dos
parâmetros. Por exemplo, um transformador de parâmetro SlugifyParameterTransformer personalizado muda o
valor de rota SubscriptionManagement para subscription-management .
O PageRouteTransformerConvention convenção de modelo de rota de página aplica-se um transformador de
parâmetro para os segmentos de nome de arquivo e pasta de rotas de página gerada automaticamente em um
aplicativo. Por exemplo, as páginas do Razor arquivo cada /Pages/SubscriptionManagement/ViewAll.cshtml teria
sua rota do reescrita /SubscriptionManagement/ViewAll para /subscription-management/view-all .
PageRouteTransformerConvention apenas transforma os segmentos gerados automaticamente de uma rota de
página que vêm do nome de arquivo e pasta páginas do Razor. Ele não transformará os segmentos de rota
adicionados com o @page diretiva. A convenção não transformará rotas adicionadas por AddPageRoute.
O PageRouteTransformerConvention está registrado como uma opção na Startup.ConfigureServices :

{
services.AddMvc()
{
options.Conventions.Add(
new PageRouteTransformerConvention(
new SlugifyParameterTransformer()));
});
}
public class SlugifyParameterTransformer : IOutboundParameterTransformer

{
public string TransformOutbound(object value)
{
if (value == null) { return null; }
// Slugify value
return Regex.Replace(value.ToString(), "([a-z])([A-Z])", "$1-$2").ToLower();
}
}
Configurar uma rota de página

Use AddPageRoute para configurar uma rota para uma página no caminho de página especificado. Os links
gerados para a página usam a rota especificada. AddPageRoute usa AddPageRouteModelConvention para estabelecer a
rota.
O aplicativo de exemplo cria uma rota para /TheContactPage para Contact.cshtml:
options.Conventions.AddPageRoute("/Contact", "TheContactPage/{text?}");
A página Contact também pode ser acessada em /Contact por meio de sua rota padrão.
A rota personalizada do aplicativo de exemplo para a página Contact permite um segmento de rota text opcional
( {text?} ). A página também inclui esse segmento opcional em sua diretiva @page , caso o visitante acesse a
página em sua rota /Contact :
@page "{text?}"
@model ContactModel
@{
ViewData["Title"] = "Contact";
}
<address>
One Microsoft Way<br>
Redmond, WA 98052-6399<br>
<abbr title="Phone">P:</abbr>
425.555.0100
</address>
<address>
<strong>Support:</strong> <a href="mailto:Support@example.com">Support@example.com</a><br>
<strong>Marketing:</strong> <a href="mailto:Marketing@example.com">Marketing@example.com</a>
</address>
<p>@Model.RouteDataTextTemplateValue</p>
Observe que a URL gerada para o link Contato na página renderizada reflete a rota atualizada:
Visite a página Contact em sua rota comum, /Contact , ou na rota personalizada, /TheContactPage . Se você
fornecer um segmento de rota text adicional, a página mostrará o segmento codificado em HTML fornecido:
Convenções de ação do modelo de página
O provedor de modelo de página padrão que implementa IPageApplicationModelProvider invoca convenções que
foram projetadas para fornecer pontos de extensibilidade para configuração de modelos de página. Essas
convenções são úteis ao criar e modificar cenários de descoberta e processamento de página.
Para os exemplos desta seção, o aplicativo de exemplo usa uma classe AddHeaderAttribute , que é um
ResultFilterAttribute, aplicável a um cabeçalho de resposta:

{
private readonly string[] _values;
public AddHeaderAttribute(string name, string[] values)

{
_name = name;
_values = values;
}

{
context.HttpContext.Response.Headers.Add(_name, _values);
base.OnResultExecuting(context);
}
}
Usando convenções, a amostra explica como aplicar o atributo a todas as páginas de uma pasta e a uma única
página.
Convenção de modelo de aplicativo de pasta
Use AddFolderApplicationModelConvention para criar e adicionar uma IPageApplicationModelConvention que
invoca uma ação em instâncias de PageApplicationModel em todas as páginas na pasta especificada.
A amostra explica o uso de AddFolderApplicationModelConvention adicionando um cabeçalho, OtherPagesHeader , às
páginas dentro da pasta OtherPages do aplicativo:
options.Conventions.AddFolderApplicationModelConvention("/OtherPages", model =>

{
"OtherPagesHeader", new string[] { "OtherPages Header Value" }));
});
Solicite a página Page1 da amostra em localhost:5000/OtherPages/Page1 e inspecione os cabeçalhos para exibir o

resultado:
Convenção de modelo de aplicativo de página

Use AddPageApplicationModelConvention para criar e adicionar um IPageApplicationModelConvention que
invoca uma ação no PageApplicationModel para a página com o nome especificado.
A amostra explica o uso de AddPageApplicationModelConvention adicionando um cabeçalho, AboutHeader , à página
About:
options.Conventions.AddPageApplicationModelConvention("/About", model =>

{
"AboutHeader", new string[] { "About Header Value" }));
});
Configurar um filtro
ConfigureFilter configura o filtro especificado a ser aplicado. É possível implementar uma classe de filtro, mas o
aplicativo de exemplo mostra como implementar um filtro em uma expressão lambda, que é implementado em
segundo plano como um alocador que retorna um filtro:
options.Conventions.ConfigureFilter(model =>
{
if (model.RelativePath.Contains("OtherPages/Page2"))
{
return new AddHeaderAttribute(
"OtherPagesPage2Header",
new string[] { "OtherPages/Page2 Header Value" });
}
return new EmptyFilter();
});
O modelo de aplicativo de página é usado para verificar o caminho relativo para segmentos que levam à página
Page2 na pasta OtherPages. Se a condição é aprovada, um cabeçalho é adicionado. Caso contrário, o EmptyFilter
é aplicado.
EmptyFilter é um filtro de Ação. Como os filtros de Ação são ignorados pelas Páginas do Razor, o EmptyFilter
não funciona conforme esperado se o caminho não contém OtherPages/Page2 .
Solicite a página Page2 da amostra em localhost:5000/OtherPages/Page2 e inspecione os cabeçalhos para exibir o
resultado:
Configurar um alocador de filtro

ConfigureFilter configura o alocador especificado para aplicar filtros a todas as Páginas do Razor.
O aplicativo de exemplo fornece um exemplo de como usar um alocador de filtro adicionando um cabeçalho,
FilterFactoryHeader , com dois valores para as páginas do aplicativo:
options.Conventions.ConfigureFilter(new AddHeaderWithFactory());
AddHeaderWithFactory.cs:
public class AddHeaderWithFactory : IFilterFactory
{
// Implement IFilterFactory
public IFilterMetadata CreateInstance(IServiceProvider serviceProvider)
{
return new AddHeaderFilter();
}
private class AddHeaderFilter : IResultFilter

{
public void OnResultExecuting(ResultExecutingContext context)
{
context.HttpContext.Response.Headers.Add(
"FilterFactoryHeader",
new string[]
{
"Filter Factory Header Value 1",
"Filter Factory Header Value 2"
});
}
public void OnResultExecuted(ResultExecutedContext context)

{
}
}
public bool IsReusable

{
get
{
return false;
}
}
}
Substituir o provedor de modelo de aplicativo de página padrão

As Páginas do Razor usam a interface IPageApplicationModelProvider para criar um
DefaultPageApplicationModelProvider. Herde do provedor de modelo padrão para fornecer sua própria lógica de
implementação para descoberta e processamento do manipulador. A implementação padrão (fonte de referência)
estabelece convenções para a nomenclatura sem nome e nomeado do manipulador, que é descrita abaixo.
Métodos de manipulador sem nome padrão
Os métodos de manipulador para verbos HTTP (métodos de manipulador "sem nome") seguem uma convenção:
On<HTTP verb>[Async] (o acréscimo de Async é opcional, mas recomendado para métodos assíncronos).
MÉTODO DE MANIPULADOR SEM NOME OPERAÇÃO
OnGet / OnGetAsync Inicializar o estado da página.
OnPost / OnPostAsync Manipular solicitações POST.
OnDelete / OnDeleteAsync Manipular solicitações DELETE†.
OnPut / OnPutAsync Manipular solicitações PUT†.
OnPatch / OnPatchAsync Manipular solicitações PATCH8224;.
†Usado para fazer chamadas à API para a página.

Métodos de manipulador nomeado padrão
Os métodos de manipulador fornecidos pelo desenvolvedor (métodos de manipulador "nomeado") seguem uma
convenção semelhante. O nome do manipulador é exibido após o verbo HTTP ou entre o verbo HTTP e Async :
On<HTTP verb><handler name>[Async] (o acréscimo de Async é opcional, mas recomendado para métodos
assíncronos). Por exemplo, os métodos que processam mensagens podem usar a nomenclatura mostrada na
tabela abaixo.
MÉTODO DO MANIPULADOR NOMEADO DE EXEMPLO OPERAÇÃO DE EXEMPLO
OnGetMessage / OnGetMessageAsync Obter uma mensagem.
OnPostMessage / OnPostMessageAsync Executar POST em uma mensagem.
OnDeleteMessage / OnDeleteMessageAsync Executar DELETE em uma mensagem†.
OnPutMessage / OnPutMessageAsync Executar PUT em uma mensagem†.
OnPatchMessage / OnPatchMessageAsync Executar PATCH em uma mensagem†.

Personalizar os nomes do método de manipulador
Suponha que você prefira alterar a maneira como os métodos de manipulador nomeado e não nomeado são
nomeados. Um esquema de nomenclatura alternativo é evitar que os nomes de método comecem com "On" e
usar o primeiro segmento de palavra para determinar o verbo HTTP. Faça outras alterações, como converter os
verbos DELETE, PUT e PATCH em POST. Um esquema desse tipo fornece os nomes de método mostrados na
tabela a seguir.
MÉTODO DO MANIPULADOR OPERAÇÃO
Get Inicializar o estado da página.
Post / PostAsync Manipular solicitações POST.
Delete / DeleteAsync Manipular solicitações DELETE†.
Put / PutAsync Manipular solicitações PUT†.

MÉTODO DO MANIPULADOR OPERAÇÃO
Patch / PatchAsync Manipular solicitações PATCH8224;.
GetMessage Obter uma mensagem.
PostMessage / PostMessageAsync Executar POST em uma mensagem.
DeleteMessage / DeleteMessageAsync Executar POST em uma mensagem a ser excluída.
PutMessage / PutMessageAsync Executar POST em uma mensagem a ser colocada.
PatchMessage / PatchMessageAsync Executar POST em uma mensagem a ser corrigida.

Para estabelecer esse esquema, herde da classe DefaultPageApplicationModelProvider e substitua o método
CreateHandlerModel para fornecer uma lógica personalizada para resolver os nomes de manipulador de
PageModel. O aplicativo de exemplo mostra como isso é feito em sua classe CustomPageApplicationModelProvider :
public class CustomPageApplicationModelProvider :

DefaultPageApplicationModelProvider
{
public CustomPageApplicationModelProvider(IModelMetadataProvider modelMetadataProvider,
IOptions<MvcOptions> options)
: base (modelMetadataProvider, options)
{
}
protected override PageHandlerModel CreateHandlerModel(MethodInfo method)

{
if (method == null)
{
throw new ArgumentNullException(nameof(method));
}
if (!IsHandler(method))
{
return null;
}
if (!TryParseHandlerMethod(
method.Name, out var httpMethod, out var handlerName))
{
return null;
}
var handlerModel = new PageHandlerModel(

method,
method.GetCustomAttributes(inherit: true))
{
Name = method.Name,
HandlerName = handlerName,
HttpMethod = httpMethod,
};
var methodParameters = handlerModel.MethodInfo.GetParameters();
for (var i = 0; i < methodParameters.Length; i++)

{
var parameter = methodParameters[i];
var parameterModel = CreateParameterModel(parameter);
parameterModel.Handler = handlerModel;
handlerModel.Parameters.Add(parameterModel);
}
return handlerModel;
}
private static bool TryParseHandlerMethod(

string methodName, out string httpMethod, out string handler)
{
httpMethod = null;
handler = null;
// Parse the method name according to our conventions to

// determine the required HTTP verb and optional
// handler name.
//
// Valid names look like:
// - Get
// - Post
// - PostAsync
// - GetMessage
// - PostMessage
// - DeleteMessage
// - DeleteMessageAsync
var length = methodName.Length;

if (methodName.EndsWith("Async", StringComparison.Ordinal))
{
length -= "Async".Length;
}
if (length == 0)
{
// The method is named "Async". Exit processing.
return false;
}
// The HTTP verb is at the start of the method name. Use

// casing to determine where it ends.
var handlerNameStart = 1;
for (; handlerNameStart < length; handlerNameStart++)
{
if (char.IsUpper(methodName[handlerNameStart]))
{
break;
}
}
httpMethod = methodName.Substring(0, handlerNameStart);
// The handler name follows the HTTP verb and is optional.

// It includes everything up to the end excluding the
// "Async" suffix, if present.
handler = handlerNameStart == length ? null : methodName.Substring(0, length);
if (string.Equals(httpMethod, "GET", StringComparison.OrdinalIgnoreCase) ||

string.Equals(httpMethod, "POST", StringComparison.OrdinalIgnoreCase))
{
// Do nothing. The httpMethod is correct for GET and POST.
return true;
}
if (string.Equals(httpMethod, "DELETE", StringComparison.OrdinalIgnoreCase) ||
string.Equals(httpMethod, "PUT", StringComparison.OrdinalIgnoreCase) ||
string.Equals(httpMethod, "PATCH", StringComparison.OrdinalIgnoreCase))
{
// Convert HTTP verbs for DELETE, PUT, and PATCH to POST
// For example: DeleteMessage, PutMessage, PatchMessage -> POST
// For example: DeleteMessage, PutMessage, PatchMessage -> POST
httpMethod = "POST";
return true;
}
else
{
return false;
}
}
}
Destaques da classe incluem:

A classe herda de DefaultPageApplicationModelProvider .
O TryParseHandlerMethod processa um manipulador para determinar o verbo HTTP ( httpMethod ) e o nome do
manipulador nomeado ( handlerName ) ao criar o PageHandlerModel .
Um Async pós-fixado é ignorado, se presente.
O uso de maiúsculas é adotado para analisar o verbo HTTP com base no nome do método.
Quando o nome do método (sem Async ) é igual ao nome do verbo HTTP, não há um manipulador
nomeado. O handlerName é definido como null e o nome do método é Get , Post , Delete , Put ou
Patch .
Quando o nome do método (sem Async ) é maior que o nome do verbo HTTP, há um manipulador
nomeado. O handlerName é definido como <method name (less 'Async', if present)> . Por exemplo,
"GetMessage" e "GetMessageAsync" geram um nome de manipulador "GetMessage".
Os verbos HTTP DELETE, PUT e PATCH são convertidos em POST.
Registre o CustomPageApplicationModelProvider na classe Startup :
services.AddSingleton<IPageApplicationModelProvider,
CustomPageApplicationModelProvider>();
O modelo de página em Index.cshtml.cs mostra como as convenções de nomenclatura comuns de método de

manipulador são alteradas para as páginas no aplicativo. A nomenclatura de prefixo comum "On" usada com as
Páginas do Razor é removida. O método que inicializa o estado da página é agora nomeado Get . Você poderá ver
essa convenção usada em todo o aplicativo se abrir qualquer modelo de página de uma das páginas.
Cada um dos outros métodos começam com o verbo HTTP que descreve seu processamento. Os dois métodos
que começam com Delete normalmente são tratados como verbos HTTP DELETE, mas a lógica em
TryParseHandlerMethod define de forma explícita o verbo como POST para ambos os manipuladores.
Observe que Async é opcional entre DeleteAllMessages e DeleteMessageAsync . Os dois são métodos assíncronos,
mas você pode optar por usar o Async pós-fixado ou não; recomendamos que você faça isso. DeleteAllMessages é
usado aqui para fins de demonstração, mas recomendamos que você nomeie um método desse tipo
DeleteAllMessagesAsync . Isso não afeta o processamento da implementação da amostra, mas o uso do Async pós-
fixado indica que se trata de um método assíncrono.
public async Task Get()
{
Messages = await _db.Messages.AsNoTracking().ToListAsync();
}
public async Task<IActionResult> PostMessageAsync()

{
_db.Messages.Add(Message);
Result = $"{nameof(PostMessageAsync)} handler: Message '{Message.Text}' added.";
}
public async Task<IActionResult> DeleteAllMessages()

{
foreach (Message message in _db.Messages)
{
_db.Messages.Remove(message);
}
Result = $"{nameof(DeleteAllMessages)} handler: All messages deleted.";
}
public async Task<IActionResult> DeleteMessageAsync(int id)

{
var message = await _db.Messages.FindAsync(id);
if (message != null)
{
_db.Messages.Remove(message);
}
Result = $"{nameof(DeleteMessageAsync)} handler: Message with Id: {id} deleted.";
}
Observe que os nomes de manipulador fornecidos em Index.cshtml correspondem aos métodos de manipulador
DeleteAllMessages e DeleteMessageAsync :
<div class="row">
<h2>Clear all messages</h2>
<hr>
<button type="submit" asp-page-handler="DeleteAllMessages"
class="btn btn-danger">Clear All</button>
</div>
</form>
</div>
</div>
<div class="row">
<h2>Messages</h2>
<hr>
<ol>
@foreach (var message in Model.Messages)
{
<li>
@message.Text
<button type="submit" asp-page-handler="DeleteMessage"
class="btn btn-danger"
asp-route-id="@message.Id">Delete</button>
</li>
}
</ol>
</form>
</div>
Async no nome do método de manipulador DeleteMessageAsync é excluído do TryParseHandlerMethod para a

correspondência de manipulador da solicitação POST com o método. É feita a correspondência do nome
asp-page-handler de DeleteMessage ao método de manipulador DeleteMessageAsync .
Filtros MVC e o filtro de Página (IPageFilter)

Os filtros de Ação MVC são ignorados pelas Páginas do Razor, pois elas usam métodos de manipulador. Outros
tipos de filtros MVC estão disponíveis para uso: Autorização, Exceção, Recurso e Resultado. Para obter mais
informações, consulte o tópico Filtros.
O filtro de Página (IPageFilter) é um filtro que se aplica às Páginas do Razor. Para obter mais informações, confira
Métodos de filtro para Páginas Razor.
Recursos adicionais
Convenções de autorização de Páginas Razor
Carregar arquivos para uma Página Razor no
ASP.NET Core
Por Luke Latham

Este tópico tem como base o aplicativo de exemplo em Introdução às Páginas do Razor no ASP.NET Core.
Este tópico mostra como usar a associação de modelos simples para carregar arquivos, o que funciona bem para
carregar arquivos pequenos. Para obter informações sobre a transmissão de arquivos grandes, consulte
Carregando arquivos grandes com streaming.
Nas etapas a seguir, um recurso de upload de arquivo da agenda de filmes será adicionado ao aplicativo de
exemplo. Um agendamento de filmes é representado por uma classe Schedule . A classe inclui duas versões do
agendamento. Uma versão é fornecida aos clientes, PublicSchedule . A outra versão é usada para os funcionários
da empresa, PrivateSchedule . Cada versão é carregada como um arquivo separado. O tutorial demonstra como
executar dois carregamentos de arquivos de uma página com um único POST para o servidor.
Considerações sobre segurança

É preciso ter cuidado ao fornecer aos usuários a possibilidade de carregar arquivos em um servidor. Os invasores
podem executar uma negação de serviço e outros ataques em um sistema. Algumas etapas de segurança que
reduzem a probabilidade de um ataque bem-sucedido são:
Fazer o upload de arquivos para uma área de upload de arquivos dedicada no sistema, o que facilita a
aplicação de medidas de segurança sobre o conteúdo carregado. Ao permitir os uploads de arquivos,
certifique-se de que as permissões de execução estejam desabilitadas no local do upload.
Use um nome de arquivo seguro determinado pelo aplicativo, não da entrada do usuário ou o nome do
arquivo carregado.
Permitir somente um conjunto específico de extensões de arquivo aprovadas.
Certifique-se de que as verificações do lado do cliente sejam realizadas no servidor. As verificações do lado do
cliente são fáceis de contornar.
Verifique o tamanho do upload e evite uploads maiores do que o esperado.
Execute um verificador de vírus/malware no conteúdo carregado.
WARNING
Carregar códigos mal-intencionados em um sistema é frequentemente a primeira etapa para executar o código que pode:
Tomar o controle total de um sistema.
Sobrecarregar um sistema, fazendo com que ele falhe completamente.
Comprometer dados do sistema ou de usuários.
Aplicar pichações a uma interface pública.
Adicionar uma classe FileUpload

Criar uma Página Razor para lidar com um par de carregamentos de arquivos. Adicione uma classe FileUpload ,
que é vinculada à página para obter os dados do agendamento. Clique com o botão direito do mouse na pasta
Modelos. Selecione Adicionar > Classe. Nomeie a classe FileUpload e adicione as seguintes propriedades:
{
public class FileUpload
{
[Required]
[Display(Name="Title")]
[Required]
[Display(Name="Public Schedule")]
public IFormFile UploadPublicSchedule { get; set; }
[Required]
[Display(Name="Private Schedule")]
public IFormFile UploadPrivateSchedule { get; set; }
}
}
{
public class FileUpload
{
[Required]
[Display(Name="Title")]
[Required]
[Display(Name="Public Schedule")]
public IFormFile UploadPublicSchedule { get; set; }
[Required]
[Display(Name="Private Schedule")]
public IFormFile UploadPrivateSchedule { get; set; }
}
}
A classe tem uma propriedade para o título do agendamento e uma propriedade para cada uma das duas versões
do agendamento. Todas as três propriedades são necessárias e o título deve ter 3-60 caracteres.
Adicionar um método auxiliar para carregar arquivos

Para evitar duplicação de código para processar arquivos do agendamento carregados, primeiro, adicione um
método auxiliar estático. Crie uma pasta de Utilitários no aplicativo e adicione um arquivo FileHelpers.cs com o
seguinte conteúdo. O método auxiliar, ProcessFormFile , usa um IFormFile e ModelStateDictionary e retorna uma
cadeia de caracteres que contém o tamanho e o conteúdo do arquivo. O comprimento e o tipo de conteúdo são
verificados. Se o arquivo não passar em uma verificação de validação, um erro será adicionado ao ModelState .
using System;
using System.IO;
using System.Net;
using System.Reflection;
using System.Text;
using Microsoft.AspNetCore.Mvc.ModelBinding;
namespace RazorPagesMovie.Utilities
{
public class FileHelpers
{
public static async Task<string> ProcessFormFile(IFormFile formFile,
ModelStateDictionary modelState)
{
var fieldDisplayName = string.Empty;
// Use reflection to obtain the display name for the model

// property associated with this IFormFile. If a display
// name isn't found, error messages simply won't show
// a display name.
MemberInfo property =
typeof(FileUpload).GetProperty(
formFile.Name.Substring(formFile.Name.IndexOf(".") + 1));
if (property != null)
{
var displayAttribute =
property.GetCustomAttribute(typeof(DisplayAttribute))
as DisplayAttribute;
if (displayAttribute != null)
{
fieldDisplayName = $"{displayAttribute.Name} ";
}
}
// Use Path.GetFileName to obtain the file name, which will

// strip any path information passed as part of the
// FileName property. HtmlEncode the result in case it must
// be returned in an error message.
var fileName = WebUtility.HtmlEncode(
Path.GetFileName(formFile.FileName));
if (formFile.ContentType.ToLower() != "text/plain")
{
modelState.AddModelError(formFile.Name,
$"The {fieldDisplayName}file ({fileName}) must be a text file.");
}
// Check the file length and don't bother attempting to

// read it if the file contains no content. This check
// doesn't catch files that only have a BOM as their
// content, so a content length check is made later after
// reading the file's content to catch a file that only
// contains a BOM.
if (formFile.Length == 0)
{
$"The {fieldDisplayName}file ({fileName}) is empty.");
}
else if (formFile.Length > 1048576)
{
$"The {fieldDisplayName}file ({fileName}) exceeds 1 MB.");
}
else
{
try
{
string fileContents;
// The StreamReader is created to read files that are UTF-8 encoded.

// If uploads require some other encoding, provide the encoding in the
// using statement. To change to 32-bit encoding, change
// new UTF8Encoding(...) to new UTF32Encoding().
using (
var reader =
new StreamReader(
formFile.OpenReadStream(),
new UTF8Encoding(encoderShouldEmitUTF8Identifier: false,
throwOnInvalidBytes: true),
detectEncodingFromByteOrderMarks: true))
{
fileContents = await reader.ReadToEndAsync();
// Check the content length in case the file's only

// content was a BOM and the content is actually
// empty after removing the BOM.
if (fileContents.Length > 0)
{
return fileContents;
}
else
{
}
}
}
{
$"The {fieldDisplayName}file ({fileName}) upload failed. " +
$"Please contact the Help Desk for support. Error: {ex.Message}");
// Log the exception
}
}
return string.Empty;
}
}
}
using System;
using System.IO;
using System.Net;
using System.Text;
namespace RazorPagesMovie.Utilities
{
public class FileHelpers
{
public static async Task<string> ProcessFormFile(
IFormFile formFile, ModelStateDictionary modelState)
{
var fieldDisplayName = string.Empty;
// Use reflection to obtain the display name for the model

// property associated with this IFormFile. If a display
// name isn't found, error messages simply won't show
// a display name.
MemberInfo property =
typeof(FileUpload).GetProperty(formFile.Name.Substring(
typeof(FileUpload).GetProperty(formFile.Name.Substring(
formFile.Name.IndexOf(".") + 1));
if (property != null)
{
var displayAttribute =
property.GetCustomAttribute(typeof(DisplayAttribute))
as DisplayAttribute;
if (displayAttribute != null)
{
fieldDisplayName = $"{displayAttribute.Name} ";
}
}
// Use Path.GetFileName to obtain the file name, which will

// strip any path information passed as part of the
// FileName property. HtmlEncode the result in case it must
// be returned in an error message.
var fileName = WebUtility.HtmlEncode(
Path.GetFileName(formFile.FileName));
if (formFile.ContentType.ToLower() != "text/plain")
{
$"The {fieldDisplayName}file ({fileName}) must be a text file.");
}
// Check the file length and don't bother attempting to

// read it if the file contains no content. This check
// doesn't catch files that only have a BOM as their
// content, so a content length check is made later after
// reading the file's content to catch a file that only
// contains a BOM.
if (formFile.Length == 0)
{
}
else if (formFile.Length > 1048576)
{
$"The {fieldDisplayName}file ({fileName}) exceeds 1 MB.");
}
else
{
try
{
string fileContents;

// If uploads require some other encoding, provide the encoding in the
// using statement. To change to 32-bit encoding, change
// new UTF8Encoding(...) to new UTF32Encoding().
using (
var reader =
new StreamReader(
formFile.OpenReadStream(),
new UTF8Encoding(encoderShouldEmitUTF8Identifier: false,
throwOnInvalidBytes: true),
detectEncodingFromByteOrderMarks: true))
{
fileContents = await reader.ReadToEndAsync();
// Check the content length in case the file's only

// content was a BOM and the content is actually
// empty after removing the BOM.
if (fileContents.Length > 0)
{
}
else
{
}
}
}
{
$"The {fieldDisplayName}file ({fileName}) upload failed. " +
$"Please contact the Help Desk for support. Error: {ex.Message}");
// Log the exception
}
}
}
}
}
Salvar o arquivo no disco

O aplicativo de exemplo salva os arquivos carregados em campos de banco de dados. Para salvar um arquivo no
disco, use um FileStream. O exemplo a seguir copia um arquivo mantido por FileUpload.UploadPublicSchedule
para um FileStream em um método OnPostAsync . O FileStream grava o arquivo no disco no
<PATH-AND-FILE-NAME> fornecido:

{
// Perform an initial check to catch FileUpload class attribute violations.
{
return Page();
}
var filePath = "<PATH-AND-FILE-NAME>";
using (var fileStream = new FileStream(filePath, FileMode.Create))

{
await FileUpload.UploadPublicSchedule.CopyToAsync(fileStream);
}
}
O processo de trabalho deve ter permissões de gravação para o local especificado por filePath .
NOTE
O filePath precisa incluir o nome do arquivo. Se o nome do arquivo não for fornecido, uma
UnauthorizedAccessException será gerada no tempo de execução.
WARNING
Nunca persista os arquivos carregados na mesma árvore de diretório que o aplicativo.
O exemplo de código não oferece proteção do lado do servidor contra carregamentos de arquivos mal-intencionados. Para
obter informações de como reduzir a área da superfície de ataque ao aceitar arquivos de usuários, confira os seguintes
recursos:
Unrestricted File Upload (Carregamento de arquivo irrestrito)
Segurança do Azure: Verifique se os controles adequados estão em vigor ao aceitar arquivos de usuários
Salvar o arquivo no Armazenamento de Blobs do Azure

Para carregar o conteúdo do arquivo para o Armazenamento de Blobs do Azure, confira Introdução ao
Armazenamento de Blobs do Azure usando o .NET. O tópico demonstra como usar UploadFromStream para
salvar um FileStream para armazenamento de blobs.
Adicionar a classe de Agendamento

Clique com o botão direito do mouse na pasta Modelos. Selecione Adicionar > Classe. Nomeie a classe
Agendamento e adicione as seguintes propriedades:
using System;
{
public class Schedule
{
public string PublicSchedule { get; set; }
[Display(Name = "Public Schedule Size (bytes)")]

[DisplayFormat(DataFormatString = "{0:N1}")]
public long PublicScheduleSize { get; set; }
public string PrivateSchedule { get; set; }
[Display(Name = "Private Schedule Size (bytes)")]

public long PrivateScheduleSize { get; set; }
[Display(Name = "Uploaded (UTC)")]

[DisplayFormat(DataFormatString = "{0:F}")]
public DateTime UploadDT { get; set; }
}
}
using System;
{
public class Schedule
{
public string PublicSchedule { get; set; }
[Display(Name = "Public Schedule Size (bytes)")]

public long PublicScheduleSize { get; set; }
public string PrivateSchedule { get; set; }
[Display(Name = "Private Schedule Size (bytes)")]

public long PrivateScheduleSize { get; set; }
[Display(Name = "Uploaded (UTC)")]

[DisplayFormat(DataFormatString = "{0:F}")]
public DateTime UploadDT { get; set; }
}
}
Usa a classe usa os atributos Display e DisplayFormat , que produzem formatação e títulos fáceis quando os
dados de agendamento são renderizados.
Atualizar o RazorPagesMovieContext
Especifique um DbSet no RazorPagesMovieContext (Data/RazorPagesMovieContext.cs) para os agendamentos:
using System;
using System.Linq;
{
public class RazorPagesMovieContext : DbContext
{
public RazorPagesMovieContext (DbContextOptions<RazorPagesMovieContext> options)
: base(options)
{
}
public DbSet<RazorPagesMovie.Models.Movie> Movie { get; set; }

public DbSet<RazorPagesMovie.Models.Schedule> Schedule { get; set; }
}
}
Atualizar o MovieContext
Especifique um DbSet no MovieContext (Models/MovieContext.cs) para os agendamentos:
{
{
: base(options)
{
}

public DbSet<Schedule> Schedule { get; set; }
}
}
Adicione a tabela de Agendamento ao banco de dados

Abra o Console Gerenciador de pacote (PMC ): Ferramentas > Gerenciador de pacote NuGet > Console
Gerenciador de pacote.
No PMC, execute os seguintes comandos. Estes comandos adicionam uma tabela Schedule ao banco de dados:
Add-Migration AddScheduleTable
Update-Database
Adicionar uma página do Razor de upload de arquivo

Na pasta Páginas, crie uma pasta Agendamentos. Na pasta Agendamentos, crie uma página chamada
Index.cshtml para carregar um agendamento com o seguinte conteúdo:
@page
@model RazorPagesMovie.Pages.Schedules.IndexModel
@{
ViewData["Title"] = "Schedules";
}
<h2>Schedules</h2>
<hr />
<hr />
<h3>Upload Schedules</h3>
<div class="row">
<form method="post" enctype="multipart/form-data">
<label asp-for="FileUpload.Title" class="control-label"></label>
<input asp-for="FileUpload.Title" type="text" class="form-control" />
<span asp-validation-for="FileUpload.Title" class="text-danger"></span>
</div>
<label asp-for="FileUpload.UploadPublicSchedule" class="control-label"></label>
<input asp-for="FileUpload.UploadPublicSchedule" type="file" class="form-control"
style="height:auto" />
<span asp-validation-for="FileUpload.UploadPublicSchedule" class="text-danger"></span>
</div>
<label asp-for="FileUpload.UploadPrivateSchedule" class="control-label"></label>
<input asp-for="FileUpload.UploadPrivateSchedule" type="file" class="form-control"
<span asp-validation-for="FileUpload.UploadPrivateSchedule" class="text-danger"></span>
</div>
<input type="submit" value="Upload" class="btn btn-default" />
</form>
</div>
</div>
<h3>Loaded Schedules</h3>
<thead>
<tr>
<th></th>
<th>
@Html.DisplayNameFor(model => model.Schedule[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Schedule[0].UploadDT)
</th>
<th class="text-center">
@Html.DisplayNameFor(model => model.Schedule[0].PublicScheduleSize)
</th>
@Html.DisplayNameFor(model => model.Schedule[0].PrivateScheduleSize)
</th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Schedule) {
<tr>
<td>
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.UploadDT)
</td>
<td class="text-center">
@Html.DisplayFor(modelItem => item.PublicScheduleSize)
</td>
@Html.DisplayFor(modelItem => item.PrivateScheduleSize)
</td>
</tr>
}
</tbody>
</table>
@section Scripts {
}
@page
@model RazorPagesMovie.Pages.Schedules.IndexModel
@{
ViewData["Title"] = "Schedules";
}
<h2>Schedules</h2>
<hr />
<h3>Upload Schedules</h3>
<div class="row">
<form method="post" enctype="multipart/form-data">
<label asp-for="FileUpload.Title" class="control-label"></label>
<input asp-for="FileUpload.Title" type="text" class="form-control" />
<span asp-validation-for="FileUpload.Title" class="text-danger"></span>
</div>
<label asp-for="FileUpload.UploadPublicSchedule" class="control-label"></label>
<input asp-for="FileUpload.UploadPublicSchedule" type="file" class="form-control"
<span asp-validation-for="FileUpload.UploadPublicSchedule" class="text-danger"></span>
</div>
<label asp-for="FileUpload.UploadPrivateSchedule" class="control-label"></label>
<input asp-for="FileUpload.UploadPrivateSchedule" type="file" class="form-control"
<span asp-validation-for="FileUpload.UploadPrivateSchedule" class="text-danger"></span>
</div>
<input type="submit" value="Upload" class="btn btn-default" />
</form>
</div>
</div>
<h3>Loaded Schedules</h3>
<thead>
<tr>
<th></th>
<th>
@Html.DisplayNameFor(model => model.Schedule[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Schedule[0].UploadDT)
</th>
@Html.DisplayNameFor(model => model.Schedule[0].PublicScheduleSize)
</th>
@Html.DisplayNameFor(model => model.Schedule[0].PrivateScheduleSize)
</th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Schedule) {
<tr>
<td>
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.UploadDT)
</td>
@Html.DisplayFor(modelItem => item.PublicScheduleSize)
</td>
@Html.DisplayFor(modelItem => item.PrivateScheduleSize)
</td>
</tr>
}
</tbody>
</table>
@section Scripts {
}
Cada grupo de formulário inclui um <rótulo> que exibe o nome de cada propriedade de classe. Os atributos
Display no modelo FileUpload fornecem os valores de exibição para os rótulos. Por exemplo, o nome de
exibição da propriedade UploadPublicSchedule é definido com [Display(Name="Public Schedule")] e, portanto,
exibe "Agendamento público" no rótulo quando o formulário é renderizado.
Cada grupo de formulário inclui uma validação <span>. Se a entrada do usuário não atender aos atributos de
propriedade definidos na classe FileUpload ou se qualquer uma das verificações de validação do arquivo de
método ProcessFormFile falhar, o modelo não será validado. Quando a validação do modelo falha, uma
mensagem de validação útil é renderizada para o usuário. Por exemplo, a propriedade Title é anotada com
[Required] e [StringLength(60, MinimumLength = 3)] . Se o usuário não fornecer um título, ele receberá uma
mensagem indicando que um valor é necessário. Se o usuário inserir um valor com menos de três caracteres ou
mais de sessenta, ele receberá uma mensagem indicando que o valor tem um comprimento incorreto. Se um
arquivo que não tem nenhum conteúdo for fornecido, uma mensagem aparecerá indicando que o arquivo está
vazio.
Adicionar o modelo de página

Adicione o modelo de página (Index.cshtml.cs) à pasta Schedules:
using System;
using RazorPagesMovie.Utilities;
namespace RazorPagesMovie.Pages.Schedules
{
{

{
_context = context;
}
[BindProperty]
public FileUpload FileUpload { get; set; }
public IList<Schedule> Schedule { get; private set; }


{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
}

{
// Perform an initial check to catch FileUpload class
// attribute violations.
{
return Page();
}
var publicScheduleData =
await FileHelpers.ProcessFormFile(FileUpload.UploadPublicSchedule, ModelState);
var privateScheduleData =
await FileHelpers.ProcessFormFile(FileUpload.UploadPrivateSchedule, ModelState);
// Perform a second check to catch ProcessFormFile method

// violations.
{
return Page();
}
var schedule = new Schedule()

{
PublicSchedule = publicScheduleData,
PublicScheduleSize = FileUpload.UploadPublicSchedule.Length,
PrivateSchedule = privateScheduleData,
PrivateScheduleSize = FileUpload.UploadPrivateSchedule.Length,
Title = FileUpload.Title,
UploadDT = DateTime.UtcNow
};
_context.Schedule.Add(schedule);
}
}
}
using System;
using RazorPagesMovie.Utilities;
{
{

{
_context = context;
}
[BindProperty]

{
}

{
{
return Page();
}
await FileHelpers.ProcessFormFile(FileUpload.UploadPublicSchedule, ModelState);
await FileHelpers.ProcessFormFile(FileUpload.UploadPrivateSchedule, ModelState);
// Perform a second check to catch ProcessFormFile method

// violations.
{
return Page();
}

{
};
}
}
}
O modelo de página ( IndexModel no Index.cshtml.cs) associa a classe FileUpload :
[BindProperty]
[BindProperty]
O modelo também usa uma lista dos agendamentos ( IList<Schedule> ) para exibir os agendamentos
armazenados no banco de dados na página:
Quando a página for carregada com OnGetAsync , Schedules é preenchido com o banco de dados e usado para
gerar uma tabela HTML de agendamentos carregados:

{
}

{
}
Quando o formulário é enviado para o servidor, o ModelState é verificado. Se for inválido, Schedule é recriado e
a página é renderizada com uma ou mais mensagens de validação informando por que a validação de página
falhou. Se for válido, as propriedades FileUpload serão usadas em OnPostAsync para concluir o upload do
arquivo para as duas versões do agendamento e criar um novo objeto Schedule para armazenar os dados. O
agendamento, em seguida, é salvo no banco de dados:
{
{
return Page();
}
await FileHelpers.ProcessSchedule(FileUpload.UploadPublicSchedule, ModelState);
await FileHelpers.ProcessSchedule(FileUpload.UploadPrivateSchedule, ModelState);
// Perform a second check to catch ProcessSchedule method

// violations.
{
return Page();
}

{
};
}
{
{
return Page();
}
await FileHelpers.ProcessSchedule(FileUpload.UploadPublicSchedule, ModelState);
await FileHelpers.ProcessSchedule(FileUpload.UploadPrivateSchedule, ModelState);
// Perform a second check to catch ProcessSchedule method

// violations.
{
return Page();
}

{
};
}
Vincular a página do Razor de upload de arquivo

Abra Pages/Shared/_Layout.cshtml e adicione um link para a barra de navegação para acessar a página de
Agendas:
<div class="navbar-collapse collapse">

<ul class="nav navbar-nav">
<li><a asp-page="/Index">Home</a></li>
<li><a asp-page="/Schedules/Index">Schedules</a></li>
<li><a asp-page="/About">About</a></li>
<li><a asp-page="/Contact">Contact</a></li>
</ul>
</div>
Adicionar uma página para confirmar a exclusão de agendamento

Quando o usuário clica para excluir um agendamento, é oferecida uma oportunidade de cancelar a operação.
Adicione uma página de confirmação de exclusão (Delete.cshtml) à pasta Agendamentos:
@page "{id:int}"
@model RazorPagesMovie.Pages.Schedules.DeleteModel
@{
ViewData["Title"] = "Delete Schedule";
}
<h2>Delete Schedule</h2>
<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Schedule</h4>
<hr />
<dl class="dl-horizontal">
<dt>
@Html.DisplayNameFor(model => model.Schedule.Title)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.Title)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Schedule.PublicScheduleSize)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.PublicScheduleSize)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Schedule.PrivateScheduleSize)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.PrivateScheduleSize)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Schedule.UploadDT)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.UploadDT)
</dd>
</dl>
<input type="hidden" asp-for="Schedule.ID" />
<input type="submit" value="Delete" class="btn btn-default" /> |
<a asp-page="./Index">Back to List</a>
</form>
</div>
@page "{id:int}"
@model RazorPagesMovie.Pages.Schedules.DeleteModel
@{
ViewData["Title"] = "Delete Schedule";
}
<h2>Delete Schedule</h2>

<div>
<h4>Schedule</h4>
<hr />
<dt>
@Html.DisplayNameFor(model => model.Schedule.Title)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.Title)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Schedule.PublicScheduleSize)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.PublicScheduleSize)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Schedule.PrivateScheduleSize)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.PrivateScheduleSize)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Schedule.UploadDT)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.UploadDT)
</dd>
</dl>
<input type="hidden" asp-for="Schedule.ID" />
</form>
</div>
O modelo de página (Delete.cshtml.cs) carrega um único agendamento identificado por id nos dados de rota da
solicitação. Adicione o arquivo Delete.cshtml.cs à pasta Agendamentos:
{
public class DeleteModel : PageModel
{
public DeleteModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}
[BindProperty]
public Schedule Schedule { get; set; }

{
if (id == null)
{
return NotFound();
}
Schedule = await _context.Schedule.SingleOrDefaultAsync(m => m.ID == id);
if (Schedule == null)
{
return NotFound();
}
return Page();
}
public async Task<IActionResult> OnPostAsync(int? id)

{
if (id == null)
{
return NotFound();
}
Schedule = await _context.Schedule.FindAsync(id);
if (Schedule != null)
{
_context.Schedule.Remove(Schedule);
}
}
}
}
using System;
using System.Linq;
{
{
public DeleteModel(RazorPagesMovie.Models.MovieContext context)

{
_context = context;
}
[BindProperty]
public Schedule Schedule { get; set; }

{
if (id == null)
{
return NotFound();
}
Schedule = await _context.Schedule.SingleOrDefaultAsync(m => m.ID == id);
if (Schedule == null)
{
return NotFound();
}
return Page();
}

{
if (id == null)
{
return NotFound();
}
{
}
}
}
}
O método OnPostAsync lida com a exclusão do agendamento pelo seu id :

{
if (id == null)
{
return NotFound();
}
{
}
}

{
if (id == null)
{
return NotFound();
}
{
}
}
Após a exclusão com êxito do agendamento, o RedirectToPage envia o usuário para a página Index.cshtml dos
agendamentos.
A página de Razor de agendamentos de trabalho

Quando a página é carregada, os rótulos e entradas para o título do agendamento, o agendamento público e o
agendamento privado são renderizados com um botão de envio:
Selecionar o botão Upload sem preencher nenhum dos campos viola os atributos [Required] no modelo. O
ModelState é inválido. As mensagens de erro de validação são exibidas para o usuário:
Digite duas letras no campo de Título. A mensagem de validação muda para indicar que o título deve ter entre 3
e 60 caracteres:
Quando um ou mais agendamentos são carregados, a seção Agendamentos carregados renderiza os

agendamentos carregados:
O usuário pode clicar no link Excluir para chegar à exibição de confirmação de exclusão, na qual ele tem a
oportunidade de confirmar ou cancelar a operação de exclusão.
Para solucionar problemas de informações com IFormFile carregar, consulte carregamentos de arquivos no
ASP.NET Core: solução de problemas.
SDK do Razor do ASP.NET Core
Por Rick Anderson

O SDK do .NET Core 2.1 ou posteriores inclui o Microsoft.NET.Sdk.Razor MSBuild SDK (SDK do Razor). O SDK
do Razor:
Padroniza a experiência de criação, empacotamento e publicação de projetos que contêm arquivos Razor para
projetos baseados no ASP.NET Core MVC.
Inclui um conjunto de destinos, propriedades e itens predefinidos que permitem personalizar a compilação de
arquivos Razor.
Pré-requisitos
Usando o SDK do Razor

A maioria dos aplicativos web não são necessárias para referenciar explicitamente o SDK do Razor.
Para usar o SDK do Razor para criar bibliotecas de classe contendo exibições Razor ou Páginas Razor:
Use Microsoft.NET.Sdk.Razor em vez de Microsoft.NET.Sdk :
<Project SDK="Microsoft.NET.Sdk.Razor">
...
</Project>
Normalmente, uma referência de pacote para Microsoft.AspNetCore.Mvc é necessário para receber

dependências adicionais que são necessárias para criar e compilar páginas Razor e exibições do Razor. No
mínimo, seu projeto deve adicionar referências de pacote para:
Microsoft.AspNetCore.Razor.Design
Microsoft.AspNetCore.Mvc.Razor.Extensions
O Microsoft.AspNetCore.Razor.Design pacote fornece os destinos e tarefas de compilação do Razor para o
projeto.
Os pacotes anteriores são incluídos em Microsoft.AspNetCore.Mvc . A marcação a seguir mostra um arquivo
de projeto que usa o SDK do Razor para criar arquivos Razor para um aplicativo páginas Razor do
ASP.NET Core:
<Project Sdk="Microsoft.NET.Sdk.Razor">
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
</Project>
WARNING
O Microsoft.AspNetCore.Razor.Design e Microsoft.AspNetCore.Mvc.Razor.Extensions pacotes são incluídos na
metapacote Microsoft. No entanto, o menor de versão Microsoft.AspNetCore.App referência de pacote fornece um
metapacote para o aplicativo que não inclui a versão mais recente do Microsoft.AspNetCore.Razor.Design . Projetos
devem fazer referência a uma versão consistente do Microsoft.AspNetCore.Razor.Design (ou
Microsoft.AspNetCore.Mvc ) para que as correções mais recentes do tempo de compilação para Razor são incluídas. Para
obter mais informações, consulte esse problema de GitHub.
Propriedades
As seguintes propriedades controlam o comportamento do SDK do Razor como parte de um build de projeto:
RazorCompileOnBuild – Quando true , compila e emite o assembly Razor como parte da criação do projeto.
Assume o padrão de true .
RazorCompileOnPublish – Quando true , compila e emite o assembly Razor como parte da publicação do
projeto. Assume o padrão de true .
As propriedades e os itens na tabela a seguir são usados para configurar entradas e saídas para o SDK do Razor.
ITENS DESCRIÇÃO
RazorGenerate Elementos de item (arquivos .cshtml) que são entradas para

os destinos de geração de código.
RazorCompile Elementos de item (. CS arquivos) que são entradas para os

destinos de compilação do Razor. Use este ItemGroup para
especificar arquivos adicionais a serem compilados no
assembly Razor.
RazorTargetAssemblyAttribute Os elementos de item usados para a codificação geram

atributos para o assembly Razor. Por exemplo:
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource"
_Parameter2="https://docs.microsoft.com/">
RazorEmbeddedResource Elementos de item adicionados como recursos incorporados

ao assembly Razor gerado.
PROPRIEDADE DESCRIÇÃO
RazorTargetName Nome do arquivo (sem extensão) do assembly produzido pelo

Razor.
RazorOutputPath O diretório de saída do Razor.
RazorCompileToolset Usado para determinar o conjunto de ferramentas usado para

criar o assembly do Razor. Os valores válidos são Implicit ,
RazorSDK e PrecompilationTool .
EnableDefaultContentItems Quando true , inclui a determinados tipos de arquivo, como

arquivos .cshtml, como conteúdo do projeto. Quando
referenciado por meio Microsoft.NET.Sdk.Web , arquivos
sob wwwroot e arquivos de configuração também estão
incluídos.
EnableDefaultRazorGenerateItems Quando true , inclui arquivos .cshtml de itens de Content

em itens de RazorGenerate .
GenerateRazorTargetAssemblyInfo Quando true , gera uma . CS arquivo que contém atributos

especificados por RazorAssemblyAttribute e inclui o
arquivo na saída da compilação.
EnableDefaultRazorTargetAssemblyInfoAttributes Quando true , adiciona um conjunto padrão de atributos de

assembly em RazorAssemblyAttribute .
CopyRazorGenerateFilesToPublishDirectory Quando true , cópias RazorGenerate itens (. cshtml)

arquivos para o diretório de publicação. Normalmente,
arquivos do Razor não são necessários para um aplicativo
publicado se eles participam da compilação em tempo de
compilação ou tempo de publicação. Assume o padrão de
false .
CopyRefAssembliesToPublishDirectory Quando true , copia os itens do assembly de referência no

diretório de publicação. Normalmente, os assemblies de
referência não são necessários para um aplicativo publicado
se a compilação do Razor ocorre em tempo de compilação ou
tempo de publicação. Definido como true se seu aplicativo
publicado requer a compilação de tempo de execução. Por
exemplo, defina o valor como true se o aplicativo modifica .
cshtml arquivos em tempo de execução ou usa exibições
inseridas. Assume o padrão de false .
IncludeRazorContentInPack Quando true , todos os itens de conteúdo do Razor (.

cshtml arquivos) são marcados para inclusão no pacote do
NuGet gerado. Assume o padrão de false .
EmbedRazorGenerateSources Quando true , adiciona itens de RazorGenerate (.cshtml)

como arquivos incorporados ao assembly Razor gerado.
Assume o padrão de false .
UseRazorBuildServer Quando true , usa um processo de servidor de build

persistente para descarregar o trabalho de geração de código.
Seu valor padrão é UseSharedCompilation .
Destinos
O SDK do Razor define dois destinos primários:
RazorGenerate – Gera código . CS arquivos de RazorGenerate elementos de item. Use a propriedade
RazorGenerateDependsOn para especificar destinos adicionais que podem ser executados antes ou depois desse
destino.
RazorCompile – Compila gerada . CS arquivos em um assembly Razor. Use RazorCompileDependsOn para
especificar destinos adicionais que podem ser executados antes ou depois desse destino.
Compilação de tempo de execução de modos de exibição do Razor
Por padrão, o SDK do Razor não publica assemblies de referência que são necessários para realizar
compilação no tempo de execução. Isso resulta em falhas de compilação quando o modelo de aplicativo se
baseia na compilação em tempo de execução—, por exemplo, o aplicativo usa exibições inseridas ou muda
as exibições depois que o aplicativo é publicado. Defina CopyRefAssembliesToPublishDirectory como true
para continuar publicando assemblies de referência.
Para um aplicativo web, verifique se seu aplicativo for direcionado a Microsoft.NET.Sdk.Web SDK.
Visão geral do ASP.NET Core MVC
Por Steve Smith

O ASP.NET Core MVC é uma estrutura avançada para a criação de aplicativos Web e APIs usando o padrão de
design Model-View -Controller.
O que é o padrão MVC?

O padrão de arquitetura MVC (Model-View -Controller) separa um aplicativo em três grupos de componentes
principais: Modelos, Exibições e Componentes. Esse padrão ajuda a obter a separação de interesses. Usando
esse padrão, as solicitações de usuário são encaminhadas para um Controlador, que é responsável por
trabalhar com o Modelo para executar as ações do usuário e/ou recuperar os resultados de consultas. O
Controlador escolhe a Exibição a ser exibida para o usuário e fornece-a com os dados do Modelo solicitados.
O seguinte diagrama mostra os três componentes principais e quais deles referenciam os outros:
Essa descrição das responsabilidades ajuda você a dimensionar o aplicativo em termos de complexidade,
porque é mais fácil de codificar, depurar e testar algo (modelo, exibição ou controlador) que tem um único
trabalho (e que segue o Princípio da Responsabilidade Única). É mais difícil atualizar, testar e depurar um
código que tem dependências distribuídas em duas ou mais dessas três áreas. Por exemplo, a lógica da
interface do usuário tende a ser alterada com mais frequência do que a lógica de negócios. Se o código de
apresentação e a lógica de negócios forem combinados em um único objeto, um objeto que contém a lógica de
negócios precisa ser modificado sempre que a interface do usuário é alterada. Isso costuma introduzir erros e
exige um novo teste da lógica de negócios após cada alteração mínima da interface do usuário.
NOTE
A exibição e o controlador dependem do modelo. No entanto, o modelo não depende da exibição nem do controlador.
Esse é um dos principais benefícios da separação. Essa separação permite que o modelo seja criado e testado de forma
independente da apresentação visual.
Responsabilidades do Modelo
O Modelo em um aplicativo MVC representa o estado do aplicativo e qualquer lógica de negócios ou operação
que deve ser executada por ele. A lógica de negócios deve ser encapsulada no modelo, juntamente com
qualquer lógica de implementação, para persistir o estado do aplicativo. As exibições fortemente tipadas
normalmente usam tipos ViewModel criados para conter os dados a serem exibidos nessa exibição. O
controlador cria e popula essas instâncias de ViewModel com base no modelo.
NOTE
Há várias maneiras de organizar o modelo em um aplicativo que usa o padrão de arquitetura MVC. Saiba mais sobre
alguns tipos diferentes de tipos de modelo.
Responsabilidades da Exibição
As exibições são responsáveis por apresentar o conteúdo por meio da interface do usuário. Elas usam o
mecanismo de exibição do Razor para inserir o código .NET em uma marcação HTML. Deve haver uma lógica
mínima nas exibições e qualquer lógica contida nelas deve se relacionar à apresentação do conteúdo. Se você
precisar executar uma grande quantidade de lógica em arquivos de exibição para exibir dados de um modelo
complexo, considere o uso de um Componente de Exibição, ViewModel ou um modelo de exibição para
simplificar a exibição.
Responsabilidades do Controlador
Os controladores são os componentes que cuidam da interação do usuário, trabalham com o modelo e, em
última análise, selecionam uma exibição a ser renderizada. Em um aplicativo MVC, a exibição mostra apenas
informações; o controlador manipula e responde à entrada e à interação do usuário. No padrão MVC, o
controlador é o ponto de entrada inicial e é responsável por selecionar quais tipos de modelo serão usados para
o trabalho e qual exibição será renderizada (daí seu nome – ele controla como o aplicativo responde a
determinada solicitação).
NOTE
Os controladores não devem ser excessivamente complicados por muitas responsabilidades. Para evitar que a lógica do
controlador se torne excessivamente complexa, use o Princípio da Responsabilidade Única para empurrar a lógica de
negócios para fora do controlador e inseri-la no modelo de domínio.
TIP
Se você achar que as ações do controlador executam com frequência os mesmos tipos de ações, siga o Princípio Don't
Repeat Yourself movendo essas ações comuns para filtros.
O que é ASP.NET Core MVC

A estrutura do ASP.NET Core MVC é uma estrutura de apresentação leve, de software livre e altamente
testável, otimizada para uso com o ASP.NET Core.
ASP.NET Core MVC fornece uma maneira com base em padrões para criar sites dinâmicos que habilitam uma
separação limpa de preocupações. Ele lhe dá controle total sobre a marcação, dá suporte ao desenvolvimento
amigável a TDD e usa os padrões da web mais recentes.
Recursos
ASP.NET Core MVC inclui o seguinte:
Roteamento
Associação de modelos
Injeção de dependência
Filtros
Áreas
APIs Web
Capacidade de teste
Mecanismo de exibição do Razor
Exibições fortemente tipadas
Auxiliares de marcação
Componentes da exibição
Roteamento
O ASP.NET Core MVC baseia-se no roteamento do ASP.NET Core, um componente de mapeamento de URL
avançado que permite criar aplicativos que têm URLs compreensíveis e pesquisáveis. Isso permite que você
defina padrões de nomenclatura de URL do aplicativo que funcionam bem para SEO (otimização do
mecanismo de pesquisa) e para a geração de links, sem levar em consideração como os arquivos no servidor
Web estão organizados. Defina as rotas usando uma sintaxe de modelo de rota conveniente que dá suporte a
restrições de valor de rota, padrões e valores opcionais.
O roteamento baseado em convenção permite definir globalmente os formatos de URL aceitos pelo aplicativo
e como cada um desses formatos é mapeado para um método de ação específico em determinado controlador.
Quando uma solicitação de entrada é recebida, o mecanismo de roteamento analisa a URL e corresponde-a a
um dos formatos de URL definidos. Em seguida, ele chama o método de ação do controlador associado.
routes.MapRoute(name: "Default", template: "{controller=Home}/{action=Index}/{id?}");
O roteamento de atributo permite que você especifique as informações de roteamento decorando os

controladores e as ações com atributos que definem as rotas do aplicativo. Isso significa que as definições de
rota são colocadas ao lado do controlador e da ação aos quais estão associadas.
public class ProductsController : Controller
{
[HttpGet("{id}")]
public IActionResult GetProduct(int id)
{
...
}
}
Associação de modelos
ASP.NET Core MVC associação de modelo converte dados de solicitação de cliente (valores de formulário, os
dados de rota, parâmetros de cadeia de caracteres de consulta, os cabeçalhos HTTP ) em objetos que o
controlador pode manipular. Como resultado, a lógica de controlador não precisa fazer o trabalho de descobrir
os dados de solicitação de entrada; ele simplesmente tem os dados como parâmetros para os métodos de ação.
public async Task<IActionResult> Login(LoginViewModel model, string returnUrl = null) { ... }
O ASP.NET Core MVC dá suporte à validação pela decoração do objeto de modelo com atributos de validação
de anotação de dados. Os atributos de validação são verificados no lado do cliente antes que os valores sejam
postados no servidor, bem como no servidor antes que a ação do controlador seja chamada.
public class LoginViewModel
{
[Required]
[EmailAddress]
public string Email { get; set; }
[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
[Display(Name = "Remember me?")]

public bool RememberMe { get; set; }
}
Uma ação do controlador:
public async Task<IActionResult> Login(LoginViewModel model, string returnUrl = null)

{
if (ModelState.IsValid)
{
// work with the model
}
// At this point, something failed, redisplay form
return View(model);
}
A estrutura manipula a validação dos dados de solicitação no cliente e no servidor. A lógica de validação
especificada em tipos de modelo é adicionada às exibições renderizados como anotações não invasivas e é
imposta no navegador com o jQuery Validation.
O ASP.NET Core tem suporte interno para DI (injeção de dependência). No ASP.NET Core MVC, os
controladores podem solicitar serviços necessários por meio de seus construtores, possibilitando o
acompanhamento do princípio de dependências explícitas.
O aplicativo também pode usar a injeção de dependência em arquivos no exibição, usando a diretiva @inject :
@inject SomeService ServiceName

<!DOCTYPE html>
<html lang="en">
<head>
<title>@ServiceName.GetTitle</title>
</head>
<body>
<h1>@ServiceName.GetTitle</h1>
</body>
</html>
Filtros
Os filtros ajudam os desenvolvedores a encapsular interesses paralelos, como tratamento de exceção ou
autorização. Os filtros permitem a execução de uma lógica pré e pós-processamento personalizada para
métodos de ação e podem ser configurados para execução em determinados pontos no pipeline de execução de
uma solicitação específica. Os filtros podem ser aplicados a controladores ou ações como atributos (ou podem
ser executados globalmente). Vários filtros (como Authorize ) são incluídos na estrutura. [Authorize] é o
atributo usado para criar filtros de autorização do MVC.
[Authorize]
public class AccountController : Controller
{
Áreas
As áreas fornecem uma maneira de particionar um aplicativo Web ASP.NET Core MVC grande em
agrupamentos funcionais menores. Uma área é uma estrutura MVC dentro de um aplicativo. Em um projeto
MVC, componentes lógicos como Modelo, Controlador e Exibição são mantidos em pastas diferentes e o MVC
usa convenções de nomenclatura para criar a relação entre esses componentes. Para um aplicativo grande,
pode ser vantajoso particionar o aplicativo em áreas de nível alto separadas de funcionalidade. Por exemplo,
um aplicativo de comércio eletrônico com várias unidades de negócios, como check-out, cobrança e pesquisa,
etc. Cada uma dessas unidades têm suas próprias exibições de componente lógico, controladores e modelos.
APIs da Web
Além de ser uma ótima plataforma para a criação de sites, o ASP.NET Core MVC tem um excelente suporte
para a criação de APIs Web. Crie serviços que alcançam uma ampla gama de clientes, incluindo navegadores e
dispositivos móveis.
A estrutura inclui suporte para a negociação de conteúdo HTTP com suporte interno para formatar dados
como JSON ou XML. Escreva formatadores personalizados para adicionar suporte para seus próprios
formatos.
Use a geração de links para habilitar o suporte para hipermídia. Habilite o suporte para o CORS
(Compartilhamento de Recursos Entre Origens) com facilidade, de modo que as APIs Web possam ser
compartilhadas entre vários aplicativos Web.
Capacidade de teste
O uso pela estrutura da injeção de dependência e de interfaces a torna adequada para teste de unidade. Além
disso, a estrutura inclui recursos (como um provedor TestHost e InMemory para o Entity Framework) que
também agiliza e facilita a execução de testes de integração. Saiba mais sobre como testar a lógica do
controlador.
Mecanismo de exibição do Razor
As exibições do ASP.NET Core MVC usam o mecanismo de exibição do Razor para renderizar exibições. Razor
é uma linguagem de marcação de modelo compacta, expressiva e fluida para definir exibições usando um
código C# inserido. O Razor é usado para gerar o conteúdo da Web no servidor de forma dinâmica. Você pode
combinar o código do servidor com o código e o conteúdo do lado cliente de maneira limpa.
<ul>
@for (int i = 0; i < 5; i++) {
<li>List item @i</li>
}
</ul>
Usando o mecanismo de exibição do Razor, você pode definir layouts, exibições parciais e seções substituíveis.
Exibições fortemente tipadas
As exibições do Razor no MVC podem ser fortemente tipadas com base no modelo. Os controladores podem
passar um modelo fortemente tipado para as exibições, permitindo que elas tenham a verificação de tipo e o
suporte do IntelliSense.
Por exemplo, a seguinte exibição renderiza um modelo do tipo IEnumerable<Product> :
@model IEnumerable<Product>
<ul>
@foreach (Product p in Model)
{
<li>@p.Name</li>
}
</ul>
Auxiliares de Marca
Os Auxiliares de Marca permitem que o código do servidor participe da criação e renderização de elementos
HTML em arquivos do Razor. Use auxiliares de marca para definir marcas personalizadas (por exemplo,
<environment> ) ou para modificar o comportamento de marcas existentes (por exemplo, <label> ). Os
Auxiliares de Marca associam a elementos específicos com base no nome do elemento e seus atributos. Eles
oferecem os benefícios da renderização do lado do servidor, enquanto preservam uma experiência de edição de
HTML.
Há muitos Auxiliares de Marca internos para tarefas comuns – como criação de formulários, links,
carregamento de ativos e muito mais – e ainda outros disponíveis em repositórios GitHub públicos e como
NuGet. Os Auxiliares de Marca são criados no C# e são direcionados a elementos HTML de acordo com o
nome do elemento, o nome do atributo ou a marca pai. Por exemplo, o LinkTagHelper interno pode ser usado
para criar um link para a ação Login do AccountsController :
<p>
Thank you for confirming your email.
Please <a asp-controller="Account" asp-action="Login">Click here to Log in</a>.
</p>
O EnvironmentTagHelper pode ser usado para incluir scripts diferentes nas exibições (por exemplo, bruto ou
minimizado) de acordo com o ambiente de tempo de execução, como Desenvolvimento, Preparo ou Produção:
<environment names="Development">
<script src="~/lib/jquery/dist/jquery.js"></script>
</environment>
<environment names="Staging,Production">
<script src="https://ajax.aspnetcdn.com/ajax/jquery/jquery-2.1.4.min.js"
asp-fallback-src="~/lib/jquery/dist/jquery.min.js"
asp-fallback-test="window.jQuery">
</script>
</environment>
Os Auxiliares de Marca fornecem uma experiência de desenvolvimento amigável a HTML e um ambiente

avançado do IntelliSense para a criação de HTML e marcação do Razor. A maioria dos Auxiliares de Marca
internos é direcionada a elementos HTML existentes e fornece atributos do lado do servidor para o elemento.
Os Componentes de Exibição permitem que você empacote a lógica de renderização e reutilize-a em todo o
aplicativo. São semelhantes às exibições parciais, mas com a lógica associada.
Versão de compatibilidade
O método SetCompatibilityVersion permite que um aplicativo aceite ou recuse as possíveis alterações da falha
de comportamento introduzidas no ASP.NET Core MVC 2.1 ou posteriores.
Para obter mais informações, consulte Versão de compatibilidade do ASP.NET Core MVC.
no Windows com o Visual Studio
Este tutorial ensina a usar o desenvolvimento Web do ASP.NET Core MVC com controladores e exibições. O
Razor Pages é um recurso da estrutura do ASP.NET Core MVC que faz com que a criação e o teste de IU da Web
fiquem mais fáceis e produtivos. Você pode usar o Razor Pages com controladores e exibições no mesmo projeto.
Se você escolher este tutorial em vez da versão Páginas do Razor, deixe uma observação explicando o motivo
neste problema do GitHub.
Windows: esta série
macOS: Como criar um aplicativo ASP.NET Core MVC com o Visual Studio para Mac
A série de tutoriais inclui o seguinte:
1. Introdução
Introdução ao ASP.NET Core MVC e ao Visual
Studio
Por Rick Anderson

Razor Pages é um recurso da estrutura do ASP.NET Core MVC que faz com que a criação e o teste de IU da
Web fiquem mais fáceis e produtivos. Você pode usar o Razor Pages com controladores e exibições no mesmo
projeto.
macOS: Criar um aplicativo ASP.NET Core MVC com o Visual Studio para Mac
Windows: Como criar um aplicativo ASP.NET Core MVC com o Visual Studio
Como instalar o Visual Studio e o .NET Core

Como criar um aplicativo Web

No Visual Studio, selecione Arquivo > Novo > Projeto.
Complete a caixa de diálogo Novo Projeto:
No painel esquerdo, toque em .NET Core
No painel central, toque em Aplicativo Web ASP.NET Core (.NET Core)
Nomeie o projeto "MvcMovie" (é importante nomear o projeto "MvcMovie" para que, quando você copiar o
código, o namespace corresponda).
Toque em OK
Faça as configurações necessárias na caixa de diálogo Novo aplicativo Web ASP.NET Core (.NET Core) –
MvcMovie:
Na caixa suspensa do seletor de versão, selecione ASP.NET Core 2.1
Selecione Aplicativo Web (Model-View-Controller)
Toque em OK.
O Visual Studio usou um modelo padrão para o projeto MVC que você acabou de criar. Para que o aplicativo
comece a funcionar agora mesmo, digite um nome de projeto e selecione algumas opções. Este é um projeto
inicial básico e é um bom ponto de partida.
Toque em F5 para executar o aplicativo no modo de depuração ou Ctrl-F5 para executá-lo no modo de não
depuração.
O Visual Studio inicia o IIS Express e executa o aplicativo. Observe que a barra de endereços mostra
localhost:port# e não algo como example.com . Isso ocorre porque localhost é o nome do host padrão do
computador local. Quando o Visual Studio cria um projeto Web, uma porta aleatória é usada para o servidor
Web. Na imagem acima, o número da porta é 5000. A URL no navegador mostra localhost:5000 . Quando
você executar o aplicativo, verá um número de porta diferente.
Iniciar o aplicativo com Ctrl+F5 (modo de não depuração) permite que você faça alterações de código, salve
o arquivo, atualize o navegador e veja as alterações de código. Muitos desenvolvedores preferem usar modo
de não depuração para iniciar o aplicativo e exibir alterações rapidamente.
Você pode iniciar o aplicativo no modo de não depuração ou de depuração por meio do item de menu
Depurar:
Você pode depurar o aplicativo tocando no botão IIS Express
O modelo padrão fornece os links funcionais Página Inicial, Sobre e Contato. A imagem do navegador acima
não mostra esses links. Dependendo do tamanho do navegador, talvez você precise clicar no ícone de navegação
para mostrá-los.
Se você estava executando no modo de depuração, toque em Shift-F5 para interromper a depuração.
Na próxima parte deste tutorial, saberemos mais sobre o MVC e começaremos a escrever um pouco de código.
ASP.NET Core 2.x
ASP.NET Core 1.x

No Visual Studio, selecione Arquivo > Novo > Projeto.
Complete a caixa de diálogo Novo Projeto:
No painel esquerdo, toque em .NET Core
No painel central, toque em Aplicativo Web ASP.NET Core (.NET Core)
Nomeie o projeto "MvcMovie" (é importante nomear o projeto "MvcMovie" para que, quando você copiar o
código, o namespace corresponda).
Toque em OK
ASP.NET Core 2.x

ASP.NET Core 1.x
Faça as configurações necessárias na caixa de diálogo Novo aplicativo Web ASP.NET Core (.NET Core) –
MvcMovie:
Na caixa de lista suspensa do seletor de versão, selecione ASP.NET Core 2.-
Selecione Aplicativo Web (Modelo-Exibir-Controlador)
Toque em OK.
O Visual Studio usou um modelo padrão para o projeto MVC que você acabou de criar. Para que o aplicativo
comece a funcionar agora mesmo, digite um nome de projeto e selecione algumas opções. Este é um projeto
inicial básico e é um bom ponto de partida,
Toque em F5 para executar o aplicativo no modo de depuração ou Ctrl-F5 para executá-lo no modo de não
depuração.
O Visual Studio inicia o IIS Express e executa o aplicativo. Observe que a barra de endereços mostra
localhost:port# e não algo como example.com . Isso ocorre porque localhost é o nome do host padrão do
computador local. Quando o Visual Studio cria um projeto Web, uma porta aleatória é usada para o servidor
Web. Na imagem acima, o número da porta é 5000. A URL no navegador mostra localhost:5000 . Quando
você executar o aplicativo, verá um número de porta diferente.
Iniciar o aplicativo com Ctrl+F5 (modo de não depuração) permite que você faça alterações de código, salve
o arquivo, atualize o navegador e veja as alterações de código. Muitos desenvolvedores preferem usar modo
de não depuração para iniciar o aplicativo e exibir alterações rapidamente.
Você pode iniciar o aplicativo no modo de não depuração ou de depuração por meio do item de menu
Depurar:
Você pode depurar o aplicativo tocando no botão IIS Express
para mostrá-los.
Se você estava executando no modo de depuração, toque em Shift-F5 para interromper a depuração.
A VA N ÇA R
Adicionar um controlador a um aplicativo ASP.NET
Core MVC
Por Rick Anderson

O padrão de arquitetura MVC (Model-View -Controller) separa um aplicativo em três componentes principais:
Model, View e Controller. O padrão MVC ajuda a criar aplicativos que são mais testáveis e fáceis de atualizar
comparado aos aplicativos monolíticos tradicionais. Os aplicativos baseados no MVC contêm:
Models: classes que representam os dados do aplicativo. As classes de modelo usam a lógica de validação
para impor regras de negócio aos dados. Normalmente, os objetos de modelo recuperam e armazenam o
estado do modelo em um banco de dados. Neste tutorial, um modelo Movie recupera dados de filmes de
um banco de dados, fornece-os para a exibição ou atualiza-os. O dados atualizados são gravados em um
banco de dados.
Views: exibições são os componentes que exibem a interface do usuário do aplicativo. Em geral, essa
interface do usuário exibe os dados de modelo.
Controllers: classes que manipulam as solicitações do navegador. Elas recuperam dados de modelo e
chamam modelos de exibição que retornam uma resposta. Em um aplicativo MVC, a exibição mostra
apenas informações; o controlador manipula e responde à entrada e à interação do usuário. Por exemplo, o
controlador manipula os dados de rota e os valores de cadeia de consulta e passa esses valores para o
modelo. O modelo pode usar esses valores para consultar o banco de dados. Por exemplo,
http://localhost:1234/Home/About tem dados de rota de Home (o controlador ) e About (o método de ação
a ser chamado no controlador principal). http://localhost:1234/Movies/Edit/5 é uma solicitação para editar
o filme com ID=5 usando o controlador do filme. Falaremos sobre os dados de rota mais adiante no
tutorial.
O padrão MVC ajuda a criar aplicativos que separam os diferentes aspectos do aplicativo (lógica de entrada,
lógica de negócios e lógica da interface do usuário), ao mesmo tempo que fornece um acoplamento flexível entre
esses elementos. O padrão especifica o local em que cada tipo de lógica deve estar localizado no aplicativo. A
lógica da interface do usuário pertence à exibição. A lógica de entrada pertence ao controlador. A lógica de
negócios pertence ao modelo. Essa separação ajuda a gerenciar a complexidade ao criar um aplicativo, porque
permite que você trabalhe em um aspecto da implementação por vez, sem afetar o código de outro. Por exemplo,
você pode trabalhar no código de exibição sem depender do código da lógica de negócios.
Abrangemos esses conceitos nesta série de tutoriais e mostraremos como usá-los para criar um aplicativo de
filme. O projeto MVC contém pastas para os Controladores e as Exibições.
No Gerenciador de Soluções, clique com o botão direito do mouse em Controladores > Adicionar >
Novo Item
Selecionar a Classe do Controlador
Na caixa de diálogo Adicionar Novo Item, insira HelloWorldController.
Substitua o conteúdo de Controllers/HelloWorldController.cs pelo seguinte:

using System.Text.Encodings.Web;
namespace MvcMovie.Controllers
{
public class HelloWorldController : Controller
{
//
// GET: /HelloWorld/
public string Index()

{
return "This is my default action...";
}
//
// GET: /HelloWorld/Welcome/
public string Welcome()

{
return "This is the Welcome action method...";
}
}
}
Cada método public em um controlador pode ser chamado como um ponto de extremidade HTTP. Na amostra
acima, ambos os métodos retornam uma cadeia de caracteres. Observe os comentários que precedem cada
método.
Um ponto de extremidade HTTP é uma URL direcionável no aplicativo Web, como
http://localhost:1234/HelloWorld , e combina o protocolo usado HTTP , o local de rede do servidor Web (incluindo
a porta TCP ) localhost:1234 e o URI de destino HelloWorld .
O primeiro comentário indica que este é um método HTTP GET invocado por meio do acréscimo de
“/HelloWorld/” à URL base. O segundo comentário especifica um método HTTP GET invocado por meio do
acréscimo de “/HelloWorld/Welcome/” à URL. Mais adiante no tutorial, você usará o mecanismo de scaffolding
para gerar métodos HTTP POST .
Execute o aplicativo no modo sem depuração e acrescente “HelloWorld” ao caminho na barra de endereços. O
método Index retorna uma cadeia de caracteres.
O MVC invoca as classes do controlador (e os métodos de ação dentro delas), dependendo da URL de entrada. A
lógica de roteamento de URL padrão usada pelo MVC usa um formato como este para determinar o código a ser
invocado:
/[Controller]/[ActionName]/[Parameters]
Configure o formato de roteamento no método Configure do arquivo Startup.cs.

{
routes.MapRoute(
name: "default",
});
Quando você executa o aplicativo e não fornece nenhum segmento de URL, ele usa como padrão o controlador
“Home” e o método “Index” especificado na linha do modelo realçada acima.
O primeiro segmento de URL determina a classe do controlador a ser executada. Portanto,
localhost:xxxx/HelloWorld é mapeado para a classe HelloWorldController . A segunda parte do segmento de URL
determina o método de ação na classe. Portanto, localhost:xxxx/HelloWorld/Index fará com que o método Index
da classe HelloWorldController seja executado. Observe que você precisou apenas navegar para
localhost:xxxx/HelloWorld e o método Index foi chamado por padrão. Isso ocorre porque Index é o método
padrão que será chamado em um controlador se um nome de método não for especificado explicitamente. A
terceira parte do segmento de URL ( id ) refere-se aos dados de rota. Você verá os dados de rota mais adiante
neste tutorial.
Navegue para http://localhost:xxxx/HelloWorld/Welcome . O método Welcome é executado e retorna a cadeia de
caracteres “Este é o método de ação Boas-vindas...”. Para essa URL, o controlador é HelloWorld e Welcome é o
método de ação. Você ainda não usou a parte [Parameters] da URL.
Modifique o código para passar algumas informações de parâmetro da URL para o controlador. Por exemplo,
/HelloWorld/Welcome?name=Rick&numtimes=4 . Altere o método Welcome para incluir dois parâmetros, conforme
mostrado no código a seguir.
// Requires using System.Text.Encodings.Web;
public string Welcome(string name, int numTimes = 1)
{
return HtmlEncoder.Default.Encode($"Hello {name}, NumTimes is: {numTimes}");
}
O código anterior:
Usa o recurso de parâmetro opcional do C# para indicar que o parâmetro numTimes usa 1 como padrão se
nenhum valor é passado para esse parâmetro.
Usa HtmlEncoder.Default.Encode para proteger o aplicativo contra a entrada mal-intencionada (ou seja,
JavaScript).
Usa Cadeias de caracteres interpoladas.
Execute o aplicativo e navegue para:
http://localhost:xxxx/HelloWorld/Welcome?name=Rick&numtimes=4
(Substitua xxxx pelo número da porta.) Você pode tentar valores diferentes para name e numtimes na URL. O
sistema de associação de modelos MVC mapeia automaticamente os parâmetros nomeados da cadeia de consulta
na barra de endereços para os parâmetros no método. Consulte Associação de modelos para obter mais
informações.
Na imagem acima, o segmento de URL ( Parameters ) não é usado e os parâmetros name e numTimes são
transmitidos como cadeias de consulta. O ? (ponto de interrogação) na URL acima é um separador seguido
pelas cadeias de consulta. O caractere & separa as cadeias de consulta.
Substitua o método Welcome pelo seguinte código:
public string Welcome(string name, int ID = 1)

{
return HtmlEncoder.Default.Encode($"Hello {name}, ID: {ID}");
}
Execute o aplicativo e insira a seguinte URL: http://localhost:xxx/HelloWorld/Welcome/3?name=Rick
Agora, o terceiro segmento de URL corresponde ao parâmetro de rota id . O método Welcome contém um
parâmetro id que correspondeu ao modelo de URL no método MapRoute . O ? à direita (em id? ) indica que o
parâmetro id é opcional.
{
routes.MapRoute(
name: "default",
});
Nestes exemplos, o controlador faz a parte “VC” do MVC – ou seja, o trabalho da exibição e do controlador. O
controlador retorna o HTML diretamente. Em geral, você não deseja que os controladores retornem HTML
diretamente, pois isso é muito difícil de codificar e manter. Em vez disso, normalmente, você usa um arquivo de
modelo de exibição do Razor separado para ajudar a gerar a resposta HTML. Faça isso no próximo tutorial.
No Visual Studio, no modo sem depuração (Ctrl+F5), você não precisa compilar o aplicativo após a alteração do
código. Basta salvar o arquivo, atualizar o navegador e você poderá ver as alterações.
A N T E R IO R P R Ó X IM O
Adicionar uma exibição a um aplicativo ASP.NET
Core MVC
Por Rick Anderson

Nesta seção, você modifica a classe HelloWorldController para que ela use os arquivos de modelo de exibição do
Razor para encapsular corretamente o processo de geração de respostas HTML para um cliente.
Crie um arquivo de modelo de exibição usando o Razor. Os modelos de exibição baseados no Razor têm uma
extensão de arquivo .cshtml. Eles fornecem uma maneira elegante de criar a saída HTML usando o C#.
Atualmente, o método Index retorna uma cadeia de caracteres com uma mensagem que é embutida em código
na classe do controlador. Na classe HelloWorldController , substitua o método Index pelo seguinte código:

{
return View();
}
O código anterior retorna um objeto View . Ele usa um modelo de exibição para gerar uma resposta HTML para
o navegador. Métodos do controlador (também conhecidos como métodos de ação), como o método Index
acima, geralmente retornam um IActionResult (ou uma classe derivada de ActionResult ), não um tipo como
cadeia de caracteres.
Clique com o botão direito do mouse na pasta Exibições e, em seguida, Adicionar > Nova Pasta e
nomeie a pasta HelloWorld.
Clique com o botão direito do mouse na pasta Views/HelloWorld e, em seguida, clique em Adicionar >
Novo Item.
Na caixa de diálogo Adicionar Novo Item – MvcMovie
Na caixa de pesquisa no canto superior direito, insira exibição
Toque em Exibição Razor
Na caixa Nome, altere o nome, se necessário, para Index.cshtml.
Toque em Adicionar
Substitua o conteúdo do arquivo de exibição Views/HelloWorld/Index.cshtml do Razor pelo seguinte:
@{
}
<h2>Index</h2>
<p>Hello from our View Template!</p>
Navegue para http://localhost:xxxx/HelloWorld . O método Index no HelloWorldController não fez muita coisa:
ele executou a instrução return View(); , que especificou que o método deve usar um arquivo de modelo de
exibição para renderizar uma resposta para o navegador. Como você não especificou explicitamente o nome do
arquivo do modelo de exibição, o MVC usou como padrão o arquivo de exibição Index.cshtml na pasta
/Views/HelloWorld. A imagem abaixo mostra a cadeia de caracteres “Olá de nosso modelo de exibição!”
embutida em código na exibição.
Se a janela do navegador for pequena (por exemplo, em um dispositivo móvel), talvez você precise alternar
(tocar) no botão de navegação do Bootstrap no canto superior direito para ver os links Página Inicial, Sobre e
Contato.
Alterando exibições e páginas de layout
Toque os links de menu (MvcMovie, Página Inicial e Sobre). Cada página mostra o mesmo layout de menu. O
layout de menu é implementado no arquivo Views/Shared/_Layout.cshtml. Abra o arquivo
Views/Shared/_Layout.cshtml.
Os modelos de layout permitem especificar o layout de contêiner HTML do site em um lugar e, em seguida,
aplicá-lo a várias páginas do site. Localize a linha @RenderBody() . RenderBody é um espaço reservado em que
todas as páginas específicas à exibição criadas são mostradas, encapsuladas na página de layout. Por exemplo, se
você selecionar o link Sobre, a exibição Views/Home/About.cshtml será renderizada dentro do método
RenderBody .
Alterar o título e o link de menu no arquivo de layout

No elemento de título, altere MvcMovie para Movie App . Altere o texto de âncora no modelo de layout de
MvcMovie para Movie App e o controlador de Home para Movies , conforme realçado abaixo:
@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] - Movie App</title>
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</environment>
<link rel="stylesheet" href="https://ajax.aspnetcdn.com/ajax/bootstrap/3.3.7/css/bootstrap.min.css"
asp-fallback-href="~/lib/bootstrap/dist/css/bootstrap.min.css"
asp-fallback-test-class="sr-only" asp-fallback-test-property="position" asp-fallback-test-
value="absolute" />
<link rel="stylesheet" href="~/css/site.min.css" asp-append-version="true" />
</environment>
@Html.Raw(JavaScriptSnippet.FullScript)
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-
collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
</button>
<a asp-area="" asp-controller="Movies" asp-action="Index" class="navbar-brand">Movie App</a>
</div>
<li><a asp-area="" asp-controller="Home" asp-action="Index">Home</a></li>
<li><a asp-area="" asp-controller="Home" asp-action="About">About</a></li>
<li><a asp-area="" asp-controller="Home" asp-action="Contact">Contact</a></li>
</ul>
</div>
</div>
</nav>
<div class="container body-content">
@RenderBody()
<hr />
<footer>
<p>© 2017 - MvcMovie</p>
</footer>
</div>
<script src="~/lib/bootstrap/dist/js/bootstrap.js"></script>
<script src="~/js/site.js" asp-append-version="true"></script>
</environment>
asp-fallback-test="window.jQuery"
crossorigin="anonymous"
integrity="sha384-K+ctZQ+LL8q6tP7I94W+qzQsfRV2a+AfHIi9k8z8l9ggpc8X+Ytst4yBo/hH+8Fk">
</script>
<script src="https://ajax.aspnetcdn.com/ajax/bootstrap/3.3.7/bootstrap.min.js"
asp-fallback-src="~/lib/bootstrap/dist/js/bootstrap.min.js"
asp-fallback-test="window.jQuery && window.jQuery.fn && window.jQuery.fn.modal"
integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa">
</script>
<script src="~/js/site.min.js" asp-append-version="true"></script>
</environment>
@RenderSection("Scripts", required: false)

</body>
</html>
<!DOCTYPE html>
<html>
<head>
<environment include="Development">
</environment>
<environment exclude="Development">
value="absolute" />
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
</div>
</ul>
</div>
</div>
</nav>

@RenderBody()
<hr />
<footer>
</footer>
</div>
</environment>
integrity="sha384-tsQFqpEReu7ZLhBV2VZlAu7zcOV+rXbYlF2cqB8txI/8aZajjp4Bqd+V6D5IgvKT">
</script>
</script>
</environment>

</body>
</html>
WARNING
Ainda não implementamos o controlador Movies e, portanto, se você clicar nesse link, obterá um erro 404 (Não
encontrado).
Salve as alterações e toque no link Sobre. Observe como o título na guia do navegador agora exibe Sobre –
Aplicativo de Filme, em vez de Sobre – Filme Mvc:
Toque no link Contato e observe que o texto do título e de âncora também exibem Aplicativo de Filme.
Conseguimos fazer a alteração uma vez no modelo de layout e fazer com que todas as páginas no site refletissem
o novo texto do link e o novo título.
Examine o arquivo Views/_ViewStart.cshtml:
@{
Layout = "_Layout";
}
O arquivo Views/_ViewStart.cshtml mostra o arquivo Views/Shared/_Layout.cshtml em cada exibição. Use a

propriedade Layout para definir outra exibição de layout ou defina-a como null para que nenhum arquivo de
layout seja usado.
Altere o título da exibição Index .
Abra Views/HelloWorld/Index.cshtml. Há dois lugares para fazer uma alteração:
O texto que é exibido no título do navegador.
O cabeçalho secundário (elemento <h2> ).
Você os tornará ligeiramente diferentes para que possa ver qual parte do código altera qual parte do aplicativo.
@{
ViewData["Title"] = "Movie List";
}
<h2>My Movie List</h2>
ViewData["Title"] = "Movie List"; no código acima define a propriedade Title do dicionário ViewData como
“Lista de Filmes”. A propriedade Title é usada no elemento HTML <title> na página de layout:
Salve as alterações e navegue para http://localhost:xxxx/HelloWorld . Observe que o título do navegador, o

cabeçalho primário e os títulos secundários foram alterados. (Se as alterações não forem exibidas no navegador,
talvez o conteúdo armazenado em cache esteja sendo exibido. Pressione Ctrl+F5 no navegador para forçar a
resposta do servidor a ser carregada.) O título do navegador é criado com ViewData["Title"] que definimos no
modelo de exibição Index.cshtml e o “– Aplicativo de Filme” adicional adicionado no arquivo de layout.
Observe também como o conteúdo no modelo de exibição Index.cshtml foi mesclado com o modelo de exibição
Views/Shared/_Layout.cshtml e uma única resposta HTML foi enviada para o navegador. Os modelos de layout
facilitam realmente a realização de alterações que se aplicam a todas as páginas do aplicativo. Para saber mais,
consulte Layout.
Apesar disso, nossos poucos “dados” (nesse caso, a mensagem “Olá de nosso modelo de exibição!”) são
embutidos em código. O aplicativo MVC tem um “V” (exibição) e você tem um “C” (controlador), mas ainda
nenhum “M” (modelo).
Passando dados do controlador para a exibição

As ações do controlador são invocadas em resposta a uma solicitação de URL de entrada. Uma classe de
controlador é o local em que você escreve o código que manipula as solicitações recebidas do navegador. O
controlador recupera dados de uma fonte de dados e decide qual tipo de resposta será enviada novamente para o
navegador. Modelos de exibição podem ser usados em um controlador para gerar e formatar uma resposta
HTML para o navegador.
Os controladores são responsáveis por fornecer os dados necessários para que um modelo de exibição renderize
uma resposta. Uma melhor prática: modelos de exibição não devem executar a lógica de negócios nem interagir
diretamente com um banco de dados. Em vez disso, um modelo de exibição deve funcionar somente com os
dados fornecidos pelo controlador. Manter essa “separação de preocupações” ajuda a manter o código limpo,
testável e com capacidade de manutenção.
Atualmente, o método Welcome na classe HelloWorldController usa um parâmetro name e um ID e, em
seguida, gera os valores diretamente no navegador. Em vez de fazer com que o controlador renderize a resposta
como uma cadeia de caracteres, altere o controlador para que ele use um modelo de exibição. O modelo de
exibição gera uma resposta dinâmica, o que significa que é necessário passar bits de dados apropriados do
controlador para a exibição para gerar a resposta. Faça isso fazendo com que o controlador coloque os dados
dinâmicos (parâmetros) que o modelo de exibição precisa em um dicionário ViewData que pode ser acessado em
seguida pelo modelo de exibição.
Retorne ao arquivo HelloWorldController.cs e altere o método Welcome para adicionar um valor Message e
NumTimes ao dicionário ViewData . O dicionário ViewData é um objeto dinâmico, o que significa que você pode
colocar tudo o que deseja nele; o objeto ViewData não tem nenhuma propriedade definida até que você insira
algo nele. O sistema de model binding MVC mapeia automaticamente os parâmetros nomeados ( name e
numTimes ) da cadeia de consulta na barra de endereços para os parâmetros no método. O arquivo
HelloWorldController.cs completo tem esta aparência:
{
{
{
return View();
}
public IActionResult Welcome(string name, int numTimes = 1)

{
ViewData["Message"] = "Hello " + name;
ViewData["NumTimes"] = numTimes;
return View();
}
}
}
O objeto de dicionário ViewData contém dados que serão passados para a exibição.
Crie um modelo de exibição Boas-vindas chamado Views/HelloWorld/Welcome.cshtml.
Você criará um loop no modelo de exibição Welcome.cshtml que exibe “Olá” NumTimes . Substitua o conteúdo de
Views/HelloWorld/Welcome.cshtml pelo seguinte:
@{
ViewData["Title"] = "Welcome";
}
<h2>Welcome</h2>
<ul>
@for (int i = 0; i < (int)ViewData["NumTimes"]; i++)
{
<li>@ViewData["Message"]</li>
}
</ul>
Salve as alterações e navegue para a seguinte URL:
Os dados são obtidos da URL e passados para o controlador usando o associador de modelo MVC. O
controlador empacota os dados em um dicionário ViewData e passa esse objeto para a exibição. Em seguida, a
exibição renderiza os dados como HTML para o navegador.
Na amostra acima, usamos o dicionário ViewData para passar dados do controlador para uma exibição. Mais
adiante no tutorial, usaremos um modelo de exibição para passar dados de um controlador para uma exibição. A
abordagem de modelo de exibição para passar dados é geralmente a preferida em relação à abordagem do
dicionário ViewData . Consulte ViewModel vs. ViewData vs. ViewBag vs. TempData vs. Session no MVC para
obter mais informações.
Bem, isso foi um tipo de “M” de modelo, mas não o tipo de banco de dados. Vamos ver o que aprendemos e criar
um banco de dados de filmes.
Adicione um modelo a um aplicativo ASP.NET Core
MVC
Por Rick Anderson e Tom Dykstra

Nesta seção, você adicionará algumas classes para o gerenciamento de filmes em um banco de dados. Essas
classes serão a parte “Model” parte do aplicativo MVC.
Você usa essas classes com o EF Core (Entity Framework Core) para trabalhar com um banco de dados. O EF
Core é uma estrutura ORM (mapeamento relacional de objetos) que simplifica o código de acesso a dados que
você precisa escrever. O EF Core dá suporte a vários mecanismos de banco de dados.
As classes de modelo que serão criadas são conhecidas como classes POCO (de “objetos CLR básicos”) porque
elas não têm nenhuma dependência do EF Core. Elas apenas definem as propriedades dos dados que serão
Neste tutorial, você escreverá as classes de modelo primeiro e o EF Core criará o banco de dados. Uma
abordagem alternativa não abordada aqui é gerar classes de modelo com base em um banco de dados já
existente. Para obter informações sobre essa abordagem, consulte ASP.NET Core – Banco de dados existente.
Adicionar uma classe de modelo de dados

Clique com o botão direito do mouse na pasta Models > Adicionar > Classe. Nomeie a classe Movie e adicione
as seguintes propriedades:
using System;
namespace MvcMovie.Models
{
public class Movie
{
}
}

Compile o projeto para verificar se não há erros. Agora você tem um Modelo no aplicativo MVC.
Gerando um controlador por scaffolding

No Gerenciador de Soluções, clique com o botão direito do mouse na pasta Controladores > Adicionar >
Novo Item com Scaffold.
Na caixa de diálogo Adicionar Scaffold, toque em Controlador MVC com exibições, usando o Entity
Framework > Adicionar.
No Gerenciador de Soluções, clique com o botão direito do mouse na pasta Controllers > Adicionar >
Controlador.
Se a caixa de diálogo Adicionar Dependências do MVC for exibida:
Atualize o Visual Studio para a última versão. Versões do Visual Studio anteriores a 15.5 mostram essa caixa
de diálogo.
Se não puder atualizar, selecione ADICIONAR e, em seguida, siga as etapas de adição do controlador
novamente.
Na caixa de diálogo Adicionar Scaffold, toque em Controlador MVC com exibições, usando o Entity
Framework > Adicionar.
Preencha a caixa de diálogo Adicionar Controlador:

Classe de modelo: Movie (MvcMovie.Models)
Classe de contexto de dados: selecione o ícone + e adicione o MvcMovie.Models.MvcMovieContext
padrão
Exibições: mantenha o padrão de cada opção marcado

Nome do controlador: mantenha o MoviesController padrão
Toque em Adicionar
O Visual Studio cria:

Uma classe de contexto de banco de dados do Entity Framework Core (Data/MvcMovieContext.cs)
Um controlador de filmes (Controllers/MoviesController.cs)
Arquivos de exibição do Razor para as páginas Criar, Excluir, Detalhes, Editar e Índice (Views/Movies/*.cshtml)
A criação automática do contexto de banco de dados e das exibições e métodos de ação CRUD (criar, ler, atualizar
e excluir) é conhecida como scaffolding. Logo você terá um aplicativo Web totalmente funcional que permitirá
que você gerencie um banco de dados de filmes.
Se você executar o aplicativo e clicar no link Filme do MVC, receberá um erro semelhante ao seguinte:
SqlException: Cannot open database "MvcMovieContext-<GUID removed>" requested by the login. The login failed.
Login failed for user 'Rick'.
System.Data.SqlClient.SqlInternalConnectionTds..ctor(DbConnectionPoolIdentity identity, SqlConnectionString
Você precisa criar o banco de dados e usará o recurso Migrações do EF Core para fazer isso. As Migrações
permitem criar um banco de dados que corresponde ao seu modelo de dados e atualizar o esquema de banco de
dados quando o modelo de dados é alterado.
Adicionar ferramentas do EF e executar a migração inicial

Nesta seção, você usará o PMC (Console de Gerenciador de Pacotes) para:
Adicione o pacote de Ferramentas do Entity Framework Core. Esse pacote é necessário adicionar migrações e
atualizar o banco de dados.
Adicione uma migração inicial.
Update-Database
Ignore a mensagem de erro a seguir, estamos corrigindo-a no próximo tutorial:

Microsoft.EntityFrameworkCore.Model.Validation[30000 ]
Nenhum tipo foi especificado para a coluna decimal "Preço" no tipo de entidade "Filme". Isso fará com que
valores sejam truncados silenciosamente se não couberem na precisão e na escala padrão. Especifique
explicitamente o tipo de coluna do SQL Server que pode acomodar todos os valores usando
'ForHasColumnType()'.
Install-Package Microsoft.EntityFrameworkCore.Tools
Update-Database
Observação: se você receber um erro com o comando Install-Package , abra o Gerenciador de Pacotes NuGet e
pesquise pelo pacote Microsoft.EntityFrameworkCore.Tools . Isso permite que você instale o pacote ou verifique se
ele já está instalado. Observação: consulte a abordagem da CLI caso você tenha problemas com o PMC.
O comando Add-Migration cria um código para criar o esquema de banco de dados inicial. O esquema é baseado
no modelo especificado no DbContext (no arquivo Data/MvcMovieContext.cs). O argumento Initial é usado
para nomear as migrações. Você pode usar qualquer nome, mas, por convenção, escolha um nome que descreve
a migração. Consulte Introdução às migrações para obter mais informações.
O comando Update-Database executa o método Up no arquivo Migrations/<time-stamp>_Initial.cs, que cria o
banco de dados.
Execute as etapas anteriores usando a CLI (interface de linha de comando) em vez do PMC:
Adicione as ferramentas do EF Core ao arquivo .csproj.
Execute os seguintes comandos no console (no diretório do projeto):

Se você executar o aplicativo e obtiver o erro:
SqlException: Cannot open database "Movie" requested by the login.

The login failed.
Login failed for user 'user name'.
Provavelmente você não terá executado dotnet ef database update .
Testar o aplicativo
Execute o aplicativo e toque no link Filme Mvc.
Toque no link Criar Novo e crie um filme.
Talvez você não possa inserir pontos decimais ou vírgulas no campo Price . Para dar suporte à validação
do jQuery para localidades de idiomas diferentes do inglês que usam uma vírgula (“,”) para um ponto
decimal e formatos de data diferentes do inglês dos EUA, você deve tomar medidas para globalizar o
aplicativo. Veja https://github.com/aspnet/Docs/issues/4076 e Recursos adicionais para obter mais
Em algumas localidades, você precisa especificar o formato da data. Consulte o código realçado abaixo.
using System;
{
public class Movie
{
}
}
Falaremos sobre DataAnnotations posteriormente no tutorial.
Tocar em Criar faz com que o formulário seja enviado para o servidor, no qual as informações do filme são salvas
em um banco de dados. O aplicativo redireciona para a URL /Movies, em que as informações do filme recém-
criadas são exibidas.
Crie duas mais entradas de filme adicionais. Experimente os links Editar, Detalhes e Excluir, que estão todos
funcionais.

{
{
request.
});
services.AddDbContext<MvcMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("MvcMovieContext")));
}

{
services.AddMvc();
}
O código realçado acima mostra o contexto de banco de dados do filme que está sendo adicionado ao contêiner
Injeção de Dependência (No arquivo Startup.cs). services.AddDbContext<MvcMovieContext>(options => especifica o
banco de dados a ser usado e a cadeia de conexão. => é um operador lambda.
Abra o arquivo Controllers/MoviesController.cs e examine o construtor:
public class MoviesController : Controller

{
private readonly MvcMovieContext _context;
public MoviesController(MvcMovieContext context)

{
_context = context;
}
O construtor usa a Injeção de Dependência para injetar o contexto de banco de dados ( MvcMovieContext ) no
controlador. O contexto de banco de dados é usado em cada um dos métodos CRUD no controlador.
Modelos fortemente tipados e a palavra-chave @model

Anteriormente neste tutorial, você viu como um controlador pode passar dados ou objetos para uma exibição
usando o dicionário ViewData . O dicionário ViewData é um objeto dinâmico que fornece uma maneira
conveniente de associação tardia para passar informações para uma exibição.
O MVC também fornece a capacidade de passar objetos de modelo fortemente tipados para uma exibição. Essa
abordagem fortemente tipada permite uma melhor verificação em tempo de compilação do código. O
mecanismo de scaffolding usou essa abordagem (ou seja, passando um modelo fortemente tipado) com a classe
MoviesController e as exibições quando ele criou os métodos e as exibições.
Examine o método Details gerado no arquivo Controllers/MoviesController.cs:
// GET: Movies/Details/5
public async Task<IActionResult> Details(int? id)
{
if (id == null)
{
return NotFound();
}
var movie = await _context.Movie

.FirstOrDefaultAsync(m => m.ID == id);
if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

.SingleOrDefaultAsync(m => m.ID == id);
if (movie == null)
{
return NotFound();
}
return View(movie);
}
O parâmetro id geralmente é passado como dados de rota. Por exemplo,

http://localhost:5000/movies/details/1 define:
O controlador para o controlador movies (o primeiro segmento de URL ).

A ação para details (o segundo segmento de URL ).
A ID como 1 (o último segmento de URL ).
Você também pode passar a id com uma cadeia de consulta da seguinte maneira:
http://localhost:1234/movies/details?id=1
O parâmetro id é definido como um tipo que permite valor nulo ( int? ), caso um valor de ID não seja
fornecido.
Um expressão lambda é passada para FirstOrDefaultAsync para selecionar as entidades de filmes que
correspondem ao valor da cadeia de consulta ou de dados da rota.

Um expressão lambda é passada para SingleOrDefaultAsync para selecionar as entidades de filmes que
correspondem ao valor da cadeia de consulta ou de dados da rota.

Se for encontrado um filme, uma instância do modelo Movie será passada para a exibição Details :
return View(movie);
Examine o conteúdo do arquivo Views/Movies/Details.cshtml:

@model MvcMovie.Models.Movie
@{
ViewData["Title"] = "Details";
}
<h2>Details</h2>
<div>
<h4>Movie</h4>
<hr />
<dt>
@Html.DisplayNameFor(model => model.Title)
</dt>
<dd>
@Html.DisplayFor(model => model.Title)
</dd>
<dt>
@Html.DisplayNameFor(model => model.ReleaseDate)
</dt>
<dd>
@Html.DisplayFor(model => model.ReleaseDate)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Genre)
</dt>
<dd>
@Html.DisplayFor(model => model.Genre)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Price)
</dt>
<dd>
@Html.DisplayFor(model => model.Price)
</dd>
</dl>
</div>
<div>
<a asp-action="Edit" asp-route-id="@Model.ID">Edit</a> |
<a asp-action="Index">Back to List</a>
</div>
Incluindo uma instrução @model na parte superior do arquivo de exibição, você pode especificar o tipo de objeto
esperado pela exibição. Quando você criou o controlador de filmes, o Visual Studio incluiu automaticamente a
seguinte instrução @model na parte superior do arquivo Details.cshtml:
Esta diretiva @model permite acessar o filme que o controlador passou para a exibição usando um objeto Model
fortemente tipado. Por exemplo, na exibição Details.cshtml, o código passa cada campo de filme para os Auxiliares
de HTML DisplayNameFor e DisplayFor com o objeto Model fortemente tipado. Os métodos Create e Edit e
as exibições também passam um objeto de modelo Movie .
Examine a exibição Index.cshtml e o método Index no controlador Movies. Observe como o código cria um
objeto List quando ele chama o método View . O código passa esta lista Movies do método de ação Index
para a exibição:
// GET: Movies
{
return View(await _context.Movie.ToListAsync());
}
Quando você criou o controlador de filmes, o scaffolding incluiu automaticamente a seguinte instrução @model
na parte superior do arquivo Index.cshtml:
@model IEnumerable<MvcMovie.Models.Movie>
A diretiva @model permite acessar a lista de filmes que o controlador passou para a exibição usando um objeto
Model fortemente tipado. Por exemplo, na exibição Index.cshtml, o código executa um loop pelos filmes com uma
instrução foreach no objeto Model fortemente tipado:
@model IEnumerable<MvcMovie.Models.Movie>
@{
}
<h2>Index</h2>
<p>
<a asp-action="Create">Create New</a>
</p>
<thead>
<tr>
<th>
</th>
<th>
@Html.DisplayNameFor(model => model.ReleaseDate)
</th>
<th>
@Html.DisplayNameFor(model => model.Genre)
</th>
<th>
@Html.DisplayNameFor(model => model.Price)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model) {
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
<a asp-action="Edit" asp-route-id="@item.ID">Edit</a> |
<a asp-action="Details" asp-route-id="@item.ID">Details</a> |
<a asp-action="Delete" asp-route-id="@item.ID">Delete</a>
</td>
</tr>
}
</tbody>
</table>
Como o objeto Model é fortemente tipado (como um objeto IEnumerable<Movie> ), cada item no loop é tipado
como Movie . Entre outros benefícios, isso significa que você obtém a verificação em tempo de compilação do
código:
Recursos adicionais
A N T E R IO R – A D IC IO N A N D O U M A P R Ó X IM O – T R A B A L H A N D O C O M O
E X IB IÇ Ã O SQL
Trabalhar com o LocalDB do SQL Server no ASP.NET
Core
Por Rick Anderson

O objeto MvcMovieContext cuida da tarefa de se conectar ao banco de dados e mapear objetos Movie para
registros do banco de dados. O contexto de banco de dados é registrado com o contêiner Injeção de Dependência
no método ConfigureServices no arquivo Startup.cs:

{
{
request.
});
}

{
services.AddMvc();
}
O sistema de Configuração do ASP.NET Core lê a ConnectionString . Para o desenvolvimento local, ele obtém a
cadeia de conexão do arquivo appsettings.json:
"MvcMovieContext": "Server=(localdb)\\mssqllocaldb;Database=MvcMovieContext-
}
Quando você implanta o aplicativo em um servidor de teste ou de produção, você pode usar uma variável de
ambiente ou outra abordagem para definir a cadeia de conexão como um SQL Server real. Consulte
Configuração para obter mais informações.

O LocalDB é uma versão leve do Mecanismo de Banco de Dados do SQL Server Express, que é direcionado para
o desenvolvimento de programas. O LocalDB é iniciado sob demanda e executado no modo de usuário e,
portanto, não há nenhuma configuração complexa. Por padrão, o banco de dados LocalDB cria arquivos “*.mdf”
no diretório C:/Users/<user>.
No menu Exibir, abra SSOX (Pesquisador de Objetos do SQL Server).
Clique com o botão direito do mouse na tabela Movie > Designer de Exibição
Observe o ícone de chave ao lado de ID . Por padrão, o EF tornará uma propriedade chamada ID a chave
primária.
Clique com o botão direito do mouse na tabela Movie > Dados de Exibição
using System;
using System.Linq;
{
{
{
using (var context = new MvcMovieContext(
serviceProvider.GetRequiredService<DbContextOptions<MvcMovieContext>>()))
{
{
}
new Movie
{
Price = 7.99M
},
new Movie
{
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Genre = "Western",
Price = 3.99M
}
);
}
}
}
}
Se houver um filme no BD, o inicializador de semeadura será retornado e nenhum filme será adicionado.
{
}

Substitua o conteúdo de Program.cs pelo código a seguir:
using System;
using MvcMovie.Models;
using MvcMovie;
namespace MvcMovie
{
{
{

{
try
{
var context = services.GetRequiredService<MvcMovieContext>();
}
{
}
}
host.Run();
}

}
}
ASP.NET Core 2.x

ASP.NET Core 1.x
using System;
namespace MvcMovie
{
{
{

{
try
{
// Requires using MvcMovie.Models;
}
{
}
}
host.Run();
}

.Build();
}
}
Testar o aplicativo
Exclua todos os registros no BD. Faça isso com os links Excluir no navegador ou no SSOX.
Force o aplicativo a ser inicializado (chame os métodos na classe Startup ) para que o método de
semeadura seja executado. Para forçar a inicialização, o IIS Express deve ser interrompido e reiniciado. Faça
isso com uma das seguintes abordagens:
Clique com botão direito do mouse no ícone de bandeja do sistema do IIS Express na área de
notificação e toque em Sair ou Parar Site
Se você estiver executando o VS no modo sem depuração, pressione F5 para executar no modo
de depuração
Se você estiver executando o VS no modo de depuração, pare o depurador e pressione F5
Os métodos e as exibições do controlador no
ASP.NET Core
Por Rick Anderson

(12:00:00 AM na imagem abaixo) e ReleaseDate deve ser escrito em duas palavras.
Abra o arquivo Models/Movie.cs e adicione as linhas realçadas mostradas abaixo:

using System;
{
public class Movie
{


}
}
using System;
using System.Linq;
{
public class Movie
{

}
}
de Dados.
Procure o controlador Movies e mantenha o ponteiro do mouse pressionado sobre um link Editar para ver a
URL de destino.
Os links Editar, Detalhes e Excluir são gerados pelo Auxiliar de Marcação de Âncora do MVC Core no arquivo
Views/Movies/Index.cshtml.

</td>
</tr>
HTML em arquivos do Razor. No código acima, o AnchorTagHelper gera dinamicamente o valor do atributo href
HTML com base na ID de rota e no método de ação do controlador. Use a opção Exibir Código-fonte em seu
navegador favorito ou as ferramentas do desenvolvedor para examinar a marcação gerada. Uma parte do HTML
<td>
<a href="/Movies/Edit/4"> Edit </a> |
<a href="/Movies/Details/4"> Details </a> |
<a href="/Movies/Delete/4"> Delete </a>
</td>
Lembre-se do formato do roteamento definido no arquivo Startup.cs:
{
routes.MapRoute(
name: "default",
});
O ASP.NET Core converte http://localhost:1234/Movies/Edit/4 de uma solicitação no método de ação Edit do

controlador Movies com o parâmetro Id igual a 4. (Os métodos do controlador também são conhecidos como
métodos de ação.)
Os Auxiliares de Marcação são um dos novos recursos mais populares do ASP.NET Core. Consulte Recursos
adicionais para obter mais informações.
Abra o controlador Movies e examine os dois métodos de ação Edit . O código a seguir mostra o método
HTTP GET Edit , que busca o filme e popula o formato de edição gerado pelo arquivo Edit.cshtml do Razor.
// GET: Movies/Edit/5
public async Task<IActionResult> Edit(int? id)
{
if (id == null)
{
return NotFound();
}
var movie = await _context.Movie.FindAsync(id);

if (movie == null)
{
return NotFound();
}
return View(movie);
}
O código a seguir mostra o método HTTP POST Edit , que processa os valores de filmes postados:
// POST: Movies/Edit/5
// To protect from overposting attacks, please enable the specific properties you want to bind to, for
// more details see http://go.microsoft.com/fwlink/?LinkId=317598.
[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Edit(int id, [Bind("ID,Title,ReleaseDate,Genre,Price")] Movie movie)
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
_context.Update(movie);
}
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction("Index");
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}
var movie = await _context.Movie.SingleOrDefaultAsync(m => m.ID == id);

if (movie == null)
{
return NotFound();
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
O atributo [Bind] é uma maneira de proteger contra o excesso de postagem. Você somente deve incluir as
propriedades do atributo [Bind] que deseja alterar. Consulte Proteger o controlador contra o excesso de
postagem para obter mais informações. ViewModels fornece uma abordagem alternativa para prevenir o excesso
de postagem.
Observe se o segundo método de ação Edit é precedido pelo atributo [HttpPost] .
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction(nameof(Index));
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
O atributo HttpPost especifica que esse método Edit pode ser invocado somente para solicitações POST. Você
pode aplicar o atributo [HttpGet] ao primeiro método de edição, mas isso não é necessário porque [HttpGet] é
o padrão.
O atributo ValidateAntiForgeryToken é usado para prevenir a falsificação de uma solicitação e é associado a um
token antifalsificação gerado no arquivo de exibição de edição (Views/Movies/Edit.cshtml). O arquivo de exibição
de edição gera o token antifalsificação com o Auxiliar de Marcação de Formulário.
<form asp-action="Edit">
O Auxiliar de Marcação de Formulário gera um token antifalsificação oculto que deve corresponder ao token
antifalsificação gerado [ValidateAntiForgeryToken] no método Edit do controlador Movies. Para obter mais
informações, consulte Falsificação de antissolicitação.
O método HttpGet Edit usa o parâmetro ID de filme, pesquisa o filme usando o método SingleOrDefaultAsync
do Entity Framework e retorna o filme selecionado para a exibição de Edição. Se um filme não for encontrado,
NotFound ( HTTP 404 ) será retornado.
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
Quando o sistema de scaffolding criou a exibição de Edição, ele examinou a classe Movie e o código criado para
renderizar os elementos <label> e <input> de cada propriedade da classe. O seguinte exemplo mostra a
exibição de Edição que foi gerada pelo sistema de scaffolding do Visual Studio:
@{
ViewData["Title"] = "Edit";
}
<h2>Edit</h2>
<div class="form-horizontal">
<h4>Movie</h4>
<hr />
<input type="hidden" asp-for="ID" />
<label asp-for="Title" class="col-md-2 control-label"></label>
<input asp-for="Title" class="form-control" />
<span asp-validation-for="Title" class="text-danger"></span>
</div>
</div>
<label asp-for="ReleaseDate" class="col-md-2 control-label"></label>
<input asp-for="ReleaseDate" class="form-control" />
<span asp-validation-for="ReleaseDate" class="text-danger"></span>
</div>
</div>
<label asp-for="Genre" class="col-md-2 control-label"></label>
<input asp-for="Genre" class="form-control" />
<span asp-validation-for="Genre" class="text-danger"></span>
</div>
</div>
<label asp-for="Price" class="col-md-2 control-label"></label>
<input asp-for="Price" class="form-control" />
<span asp-validation-for="Price" class="text-danger"></span>
</div>
</div>
<div class="col-md-offset-2 col-md-10">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</div>
</div>
</form>
<div>
</div>
@section Scripts {
}
Observe como o modelo de exibição tem uma instrução @model MvcMovie.Models.Movie na parte superior do
arquivo. @model MvcMovie.Models.Movie especifica que a exibição espera que o modelo de exibição seja do tipo
Movie .
O código com scaffolding usa vários métodos de Auxiliares de Marcação para simplificar a marcação HTML. O –
Auxiliar de Marcação de Rótulo exibe o nome do campo (“Title”, “ReleaseDate”, “Genre” ou “Price”). O Auxiliar de
Marcação de Entrada renderiza um elemento <input> HTML. O Auxiliar de Marcação de Validação exibe todas as
mensagens de validação associadas a essa propriedade.
Execute o aplicativo e navegue para a URL /Movies . Clique em um link Editar. No navegador, exiba a origem da
página. O HTML gerado para o elemento <form> é mostrado abaixo.
<form action="/Movies/Edit/7" method="post">

<h4>Movie</h4>
<hr />
<div class="text-danger" />
<input type="hidden" data-val="true" data-val-required="The ID field is required." id="ID" name="ID"
value="7" />
<label class="control-label col-md-2" for="Genre" />
<input class="form-control" type="text" id="Genre" name="Genre" value="Western" />
<span class="text-danger field-validation-valid" data-valmsg-for="Genre" data-valmsg-
replace="true"></span>
</div>
</div>
<label class="control-label col-md-2" for="Price" />
<input class="form-control" type="text" data-val="true" data-val-number="The field Price must
be a number." data-val-required="The Price field is required." id="Price" name="Price" value="3.99" />
<span class="text-danger field-validation-valid" data-valmsg-for="Price" data-valmsg-
</div>
</div>

</div>
</div>
</div>
<input name="__RequestVerificationToken" type="hidden"
value="CfDJ8Inyxgp63fRFqUePGvuI5jGZsloJu1L7X9le1gy7NCIlSduCRx9jDQClrV9pOTTmqUyXnJBXhmrjcUVDJyDUMm7-
MF_9rK8aAZdRdlOri7FmKVkRe_2v5LIHGKFcTjPrWPYnc9AdSbomkiOSaTEg7RU" />
</form>
Os elementos <input> estão em um elemento HTML <form> cujo atributo action está definido para ser postado
para a URL /Movies/Edit/id . Os dados de formulário serão postados com o servidor quando o botão Save
receber um clique. A última linha antes do elemento </form> de fechamento mostra o token XSRF oculto gerado
pelo Auxiliar de Marcação de Formulário.
Processando a solicitação POST

A lista a seguir mostra a versão [HttpPost] do método de ação Edit .
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
O atributo [ValidateAntiForgeryToken] valida o token XSRF oculto gerado pelo gerador de tokens antifalsificação
no Auxiliar de Marcação de Formulário
O sistema de model binding usa os valores de formulário postados e cria um objeto Movie que é passado como
o parâmetro movie . O método ModelState.IsValid verifica se os dados enviados no formulário podem ser
usados para modificar (editar ou atualizar) um objeto Movie . Se os dados forem válidos, eles serão salvos. Os
dados de filmes atualizados (editados) são salvos no banco de dados chamando o método SaveChangesAsync do
contexto de banco de dados. Depois de salvar os dados, o código redireciona o usuário para o método de ação
Index da classe MoviesController , que exibe a coleção de filmes, incluindo as alterações feitas recentemente.
Antes que o formulário seja postado no servidor, a validação do lado do cliente verifica as regras de validação nos
campos. Se houver erros de validação, será exibida uma mensagem de erro e o formulário não será postado. Se o
JavaScript estiver desabilitado, você não terá a validação do lado do cliente, mas o servidor detectará os valores
postados que não são válidos e os valores de formulário serão exibidos novamente com mensagens de erro. Mais
adiante no tutorial, examinamos a Validação de Modelos mais detalhadamente. O Auxiliar de Marcação de
Validação no modelo de exibição Views/Movies/Edit.cshtml é responsável por exibir as mensagens de erro
apropriadas.
Todos os métodos HttpGet no controlador de filme seguem um padrão semelhante. Eles obtêm um objeto de
filme (ou uma lista de objetos, no caso de Index ) e passam o objeto (modelo) para a exibição. O método Create
passa um objeto de filme vazio para a exibição Create . Todos os métodos que criam, editam, excluem ou, de
outro modo, modificam dados fazem isso na sobrecarga [HttpPost] do método. A modificação de dados em um
método HTTP GET é um risco de segurança. A modificação de dados em um método HTTP GET também viola as
melhores práticas de HTTP e o padrão REST de arquitetura, que especifica que as solicitações GET não devem
alterar o estado do aplicativo. Em outras palavras, a execução de uma operação GET deve ser uma operação
segura que não tem efeitos colaterais e não modifica os dados persistentes.
Recursos adicionais
Introdução aos auxiliares de marcação
Auxiliares de marca de autor
Falsificação anti-solicitação
Proteger o controlador contra o excesso de postagem
ViewModels
Auxiliar de marcação de formulário
Auxiliar de marcação de entrada
Auxiliar de marcação de rótulo
Selecionar o auxiliar de marcação
Auxiliar de marcação de validação
Adicionar a pesquisa a um aplicativo ASP.NET Core
MVC
Por Rick Anderson

Nesta seção, você adiciona a funcionalidade de pesquisa ao método de ação Index que permite pesquisar filmes
por gênero ou nome.
Atualize o método Index pelo seguinte código:
public async Task<IActionResult> Index(string searchString)

{
select m;
{
}
return View(await movies.ToListAsync());

}
A primeira linha do método de ação Index cria uma consulta LINQ para selecionar os filmes:

select m;
o valor da cadeia de caracteres de pesquisa:
{
}
O código s => s.Title.Contains() acima é uma Expressão Lambda. Lambdas são usados em consultas LINQ
baseadas em método como argumentos para métodos de operadores de consulta padrão, como o método Where
ou Contains (usado no código acima). As consultas LINQ não são executadas quando são definidas ou no
momento em que são modificadas com uma chamada a um método, como Where , Contains ou OrderBy . Em
vez disso, a execução da consulta é adiada. Isso significa que a avaliação de uma expressão é atrasada até que seu
valor realizado seja, de fato, iterado ou o método ToListAsync seja chamado. Para obter mais informações sobre
a execução de consulta adiada, consulte Execução da consulta.
Observação: o método Contains é executado no banco de dados, não no código C# mostrado acima. A
diferenciação de maiúsculas e minúsculas na consulta depende do banco de dados e do agrupamento. No SQL
Server, Contains é mapeado para SQL LIKE, que não diferencia maiúsculas de minúsculas. No SQLite, com o
agrupamento padrão, ele diferencia maiúsculas de minúsculas.
Navegue para /Movies/Index . Acrescente uma cadeia de consulta, como ?searchString=Ghost , à URL. Os filmes
filtrados são exibidos.
Se você alterar a assinatura do método Index para que ele tenha um parâmetro chamado id , o parâmetro id
corresponderá o espaço reservado {id} opcional com as rotas padrão definidas em Startup.cs.
{
routes.MapRoute(
name: "default",
});
Renomeie rapidamente o parâmetro searchString para id com o comando rename. Clique com o botão direito
do mouse em searchString > Renomear.
Os destinos de renomeação são realçados.
Altere o parâmetro para id e todas as ocorrências de searchString altere para id .
O método Index anterior:

{
select m;
{
}

}
O método Index atualizado com o parâmetro id :
public async Task<IActionResult> Index(string id)

{
select m;
if (!String.IsNullOrEmpty(id))
{
movies = movies.Where(s => s.Title.Contains(id));
}

}
Agora você pode passar o título de pesquisa como dados de rota (um segmento de URL ), em vez de como um
valor de cadeia de consulta.
No entanto, você não pode esperar que os usuários modifiquem a URL sempre que desejarem pesquisar um
filme. Agora você adicionará os elementos da interface do usuário para ajudá-los a filtrar filmes. Se você tiver
alterado a assinatura do método Index para testar como passar o parâmetro ID associado à rota, altere-o
novamente para que ele use um parâmetro chamado searchString :
{
select m;
{
}

}
Abra o arquivo Views/Movies/Index.cshtml e, em seguida, adicione a marcação <form> realçada abaixo:
}
<h2>Index</h2>
<p>
</p>
<form asp-controller="Movies" asp-action="Index">

<p>
</p>
</form>
<thead>
A marcação <form> HTML usa o Auxiliar de Marcação de Formulário. Portanto, quando você enviar o formulário,
a cadeia de caracteres de filtro será enviada para a ação Index do controlador de filmes. Salve as alterações e, em
seguida, teste o filtro.
Não há nenhuma sobrecarga [HttpPost] do método Index que poderia ser esperada. Isso não é necessário,
porque o método não está alterando o estado do aplicativo, apenas filtrando os dados.
Você poderá adicionar o método [HttpPost] Index a seguir.
[HttpPost]
public string Index(string searchString, bool notUsed)
{
return "From [HttpPost]Index: filter on " + searchString;
}
O parâmetro notUsed é usado para criar uma sobrecarga para o método Index . Falaremos sobre isso mais
adiante no tutorial.
Se você adicionar esse método, o chamador de ação fará uma correspondência com o método [HttpPost] Index
e o método [HttpPost] Index será executado conforme mostrado na imagem abaixo.
No entanto, mesmo se você adicionar esta versão [HttpPost] do método Index , haverá uma limitação na forma
de como isso tudo foi implementado. Imagine que você deseja adicionar uma pesquisa específica como Favoritos
ou enviar um link para seus amigos para que eles possam clicar para ver a mesma lista filtrada de filmes. Observe
que a URL da solicitação HTTP POST é a mesma que a URL da solicitação GET (localhost:xxxxx/Movies/Index) –
não há nenhuma informação de pesquisa na URL. As informações de cadeia de caracteres de pesquisa são
enviadas ao servidor como um valor de campo de formulário. Verifique isso com as ferramentas do
Desenvolvedor do navegador ou a excelente ferramenta Fiddler. A imagem abaixo mostra as ferramentas do
Desenvolvedor do navegador Chrome:
Veja o parâmetro de pesquisa e o token XSRF no corpo da solicitação. Observe, conforme mencionado no tutorial
anterior, que o Auxiliar de Marcação de Formulário gera um token antifalsificação XSRF. Não modificaremos os
dados e, portanto, não precisamos validar o token no método do controlador.
Como o parâmetro de pesquisa está no corpo da solicitação e não na URL, não é possível capturar essas
informações de pesquisa para adicionar como Favoritos ou compartilhar com outras pessoas. Corrigiremos isso
especificando que a solicitação deve ser HTTP GET .
Observe como o IntelliSense nos ajuda a atualizar a marcação.
Observe a fonte diferenciada na marcação <form> . Essa fonte diferenciada indica que a marcação tem o suporte
de Auxiliares de Marcação.
Agora, quando você enviar uma pesquisa, a URL conterá a cadeia de consulta da pesquisa. A pesquisa também
irá para o método de ação HttpGet Index , mesmo se você tiver um método HttpPost Index .
A seguinte marcação mostra a alteração para a marcação form :
<form asp-controller="Movies" asp-action="Index" method="get">

Adicione a seguinte classe MovieGenreViewModel à pasta Models:
using Microsoft.AspNetCore.Mvc.Rendering;
{
public class MovieGenreViewModel
{
public List<Movie> Movies;
public SelectList Genres;
}
}
O modelo de exibição do gênero de filme conterá:

Uma lista de filmes.
Uma SelectList que contém a lista de gêneros. Isso permite que o usuário selecione um gênero na lista.
MovieGenre , que contém o gênero selecionado.
SearchString , que contém o texto que os usuários inserem na caixa de texto de pesquisa.
Substitua o método Index em MoviesController.cs pelo seguinte código:

public async Task<IActionResult> Index(string movieGenre, string searchString)
{
orderby m.Genre
select m.Genre;

select m;
{
}
{
}
var movieGenreVM = new MovieGenreViewModel();

movieGenreVM.Genres = new SelectList(await genreQuery.Distinct().ToListAsync());
movieGenreVM.Movies = await movies.ToListAsync();
movieGenreVM.SearchString = searchString;
return View(movieGenreVM);
}

orderby m.Genre
select m.Genre;
A SelectList de gêneros é criada com a projeção dos gêneros distintos (não desejamos que nossa lista de
seleção tenha gêneros duplicados).
Quando o usuário pesquisa o item, o valor de pesquisa é mantido na caixa de pesquisa. Para reter o valor de
pesquisa, preencha a propriedade SearchString com o valor de pesquisa. O valor de pesquisa é o parâmetro
searchString para a ação do controlador Index .
movieGenreVM.genres = new SelectList(await genreQuery.Distinct().ToListAsync())
Adicionando uma pesquisa por gênero à exibição Índice

@model MvcMovie.Models.MovieGenreViewModel
@{
}
<h2>Index</h2>
<p>
</p>

<p>
</select>

</p>
</form>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Movies[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Movies[0].ReleaseDate)
</th>
<th>
@Html.DisplayNameFor(model => model.Movies[0].Genre)
</th>
<th>
@Html.DisplayNameFor(model => model.Movies[0].Price)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Movies)
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
Examine a expressão lambda usada no seguinte Auxiliar de HTML:
No código anterior, o Auxiliar de HTML DisplayNameFor inspeciona a propriedade Title referenciada na

expressão lambda para determinar o nome de exibição. Como a expressão lambda é inspecionada em vez de
avaliada, você não recebe uma violação de acesso quando model , model.Movies ou model.Movies[0] é null ou
vazio. Quando a expressão lambda é avaliada (por exemplo, @Html.DisplayFor(modelItem => item.Title) ), os
valores da propriedade do modelo são avaliados.
Adicionar um novo campo a um aplicativo ASP.NET
Core MVC
Por Rick Anderson

Nesta seção, você usará as Migrações do Entity Framework Code First para adicionar um novo campo ao modelo
e migrar essa alteração ao banco de dados.
Ao usar o EF Code First para criar um banco de dados automaticamente, o Code First adiciona uma tabela ao
banco de dados para ajudar a acompanhar se o esquema do banco de dados está sincronizado com as classes de
modelo com base nas quais ele foi gerado. Se ele não estiver sincronizado, o EF gerará uma exceção. Isso facilita a
descoberta de problemas de código/banco de dados inconsistente.

public class Movie

{


}
public class Movie

{

}
Compile o aplicativo (Ctrl+Shift+B ).

Como você adicionou um novo campo à classe Movie , você também precisa atualizar a lista de permissões de
associação para que essa nova propriedade seja incluída. Em MoviesController.cs, atualize o atributo [Bind] dos
métodos de ação Create e Edit para incluir a propriedade Rating :
[Bind("ID,Title,ReleaseDate,Genre,Price,Rating")]
Você também precisa atualizar os modelos de exibição para exibir, criar e editar a nova propriedade Rating na
exibição do navegador.
Edite o arquivo /Views/Movies/Index.cshtml e adicione um campo Rating :
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.movies[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.movies[0].ReleaseDate)
</th>
<th>
@Html.DisplayNameFor(model => model.movies[0].Genre)
</th>
<th>
@Html.DisplayNameFor(model => model.movies[0].Price)
</th>
<th>
@Html.DisplayNameFor(model => model.movies[0].Rating)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.movies)
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
Atualize /Views/Movies/Create.cshtml com um campo Rating . Copie/cole o “grupo de formulário” anterior e

permita que o IntelliSense ajude você a atualizar os campos. O IntelliSense funciona com os Auxiliares de
Marcação. Observação: na versão RTM do Visual Studio 2017, você precisa instalar o Razor Language Services
para o IntelliSense do Razor. Isso será corrigido na próxima versão.
O aplicativo não funcionará até que atualizemos o BD para incluir o novo campo. Se você executá-lo agora,
obterá o seguinte SqlException :
SqlException: Invalid column name 'Rating'.
Você está vendo este erro porque a classe de modelo Movie atualizada é diferente do esquema da tabela Movie
do banco de dados existente. (Não há nenhuma coluna Classificação na tabela de banco de dados.)
1. Faça com que o Entity Framework remova automaticamente e recrie o banco de dados com base no novo
esquema de classe de modelo. Essa abordagem é muito conveniente no início do ciclo de desenvolvimento,
quando você está fazendo o desenvolvimento ativo em um banco de dados de teste; ela permite que você
desenvolva rapidamente o modelo e o esquema de banco de dados juntos. No entanto, a desvantagem é
que você perde os dados existentes no banco de dados – portanto, você não deseja usar essa abordagem
em um banco de dados de produção! Muitas vezes, o uso de um inicializador para propagar um banco de
dados com os dados de teste automaticamente é uma maneira produtiva de desenvolver um aplicativo.
2. Modifique explicitamente o esquema do banco de dados existente para que ele corresponda às classes de
modelo. A vantagem dessa abordagem é que você mantém os dados. Faça essa alteração manualmente ou
criando um script de alteração de banco de dados.
Para este tutorial, usaremos as Migrações do Code First.
mostrada abaixo, mas é recomendável fazer essa alteração em cada new Movie .
new Movie
{
Rating = "R",
Price = 7.99M
},
Compile a solução.
Add-Migration Rating
Update-Database
O comando Add-Migration informa a estrutura de migração para examinar o atual modelo Movie com o atual
esquema de BD Movie e criar o código necessário para migrar o BD para o novo modelo. O nome “Classificação”
é arbitrário e é usado para nomear o arquivo de migração. É útil usar um nome significativo para o arquivo de
migração.
Se você excluir todos os registros do BD, o inicializador propagará o BD e incluirá o campo Rating . Faça isso
com os links Excluir no navegador ou no SSOX.
Execute o aplicativo e verifique se você pode criar/editar/exibir filmes com um campo Rating . Você também deve
adicionar o campo Rating aos modelos de exibição Edit , Details e Delete .
Adicionar a validação a um aplicativo ASP.NET Core
MVC
Por Rick Anderson

Nesta seção, você adicionará a lógica de validação ao modelo Movie e garantirá que as regras de validação são
impostas sempre que um usuário criar ou editar um filme.
Mantendo o processo DRY

Um dos princípios de design do MVC é o DRY (“Don't Repeat Yourself”). O ASP.NET Core MVC incentiva você a
especificar a funcionalidade ou o comportamento somente uma vez e, em seguida, refleti-lo em qualquer lugar de
um aplicativo. Isso reduz a quantidade de código que você precisa escrever e faz com que o código escrito seja
menos propenso a erros e mais fácil de testar e manter.
O suporte de validação fornecido pelo MVC e pelo Entity Framework Core Code First é um bom exemplo do
princípio DRY em ação. Especifique as regras de validação de forma declarativa em um único lugar (na classe de
modelo) e as regras são impostas em qualquer lugar no aplicativo.

Abra o arquivo Movie.cs. DataAnnotations fornece um conjunto interno de atributos de validação que são
aplicados de forma declarativa a qualquer classe ou propriedade. (Também contém atributos de formatação como
DataType , que ajudam com a formatação e não fornecem nenhuma validação.)
Range internos.
public class Movie
{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}
public class Movie

{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}
Os atributos de validação especificam o comportamento que você deseja impor nas propriedades de modelo às
quais eles são aplicados. Os atributos Required e MinimumLength indicam que uma propriedade deve ter um
valor; porém, nada impede que um usuário insira um espaço em branco para atender a essa validação. O atributo
RegularExpression é usado para limitar quais caracteres podem ser inseridos. No código acima, Genre e Rating
devem usar apenas letras (primeira letra maiúscula, espaço em branco, números e caracteres especiais não são
permitidos). O atributo Range restringe um valor a um intervalo especificado. O atributo StringLength permite
definir o tamanho máximo de uma propriedade de cadeia de caracteres e, opcionalmente, seu tamanho mínimo.
Os tipos de valor (como decimal , int , float , DateTime ) são inerentemente necessários e não precisam do
atributo [Required] .
Ter as regras de validação automaticamente impostas pelo ASP.NET Core ajuda a tornar seu aplicativo mais
robusto. Também garante que você não se esqueça de validar algo e inadvertidamente permita dados incorretos
no banco de dados.
Interface do usuário do erro de validação no MVC

Execute o aplicativo e navegue para o controlador Movies.
Toque no link Criar Novo para adicionar um novo filme. Preencha o formulário com alguns valores inválidos.
Assim que a validação do lado do cliente do jQuery detecta o erro, ela exibe uma mensagem de erro.
NOTE
Observe como o formulário renderizou automaticamente uma mensagem de erro de validação apropriada em
cada campo que contém um valor inválido. Os erros são impostos no lado do cliente (usando o JavaScript e o
jQuery) e no lado do servidor (caso um usuário tenha o JavaScript desabilitado).
Uma vantagem significativa é que você não precisa alterar uma única linha de código na classe MoviesController
ou na exibição Create.cshtml para habilitar essa interface do usuário de validação. O controlador e as exibições
criados anteriormente neste tutorial selecionaram automaticamente as regras de validação especificadas com
atributos de validação nas propriedades da classe de modelo Movie . Teste a validação usando o método de ação
Edit e a mesma validação é aplicada.
Os dados de formulário não serão enviados para o servidor enquanto houver erros de validação do lado do
cliente. Verifique isso colocando um ponto de interrupção no método HTTP Post usando a ferramenta Fiddler ou
as ferramentas do Desenvolvedor F12.
Como funciona a validação

Talvez você esteja se perguntando como a interface do usuário de validação foi gerada sem atualizações do
código no controlador ou nas exibições. O código a seguir mostra os dois métodos Create .
// GET: Movies/Create
public IActionResult Create()
{
return View();
}
// POST: Movies/Create
[HttpPost]
public async Task<IActionResult> Create(
[Bind("ID,Title,ReleaseDate,Genre,Price, Rating")] Movie movie)
{
{
_context.Add(movie);
}
return View(movie);
}
O primeiro método de ação (HTTP GET) Create exibe o formulário Criar inicial. A segunda versão ( [HttpPost] )
manipula a postagem de formulário. O segundo método Create (a versão [HttpPost] ) chama
ModelState.IsValid para verificar se o filme tem erros de validação. A chamada a esse método avalia os atributos
de validação que foram aplicados ao objeto. Se o objeto tiver erros de validação, o método Create exibirá o
formulário novamente. Se não houver erros, o método salvará o novo filme no banco de dados. Em nosso
exemplo de filme, o formulário não é postado no servidor quando há erros de validação detectados no lado do
cliente; o segundo método Create nunca é chamado quando há erros de validação do lado do cliente. Se você
desabilitar o JavaScript no navegador, a validação do cliente será desabilitada e você poderá testar o método
Create HTTP POST ModelState.IsValid detectando erros de validação.
Defina um ponto de interrupção no método [HttpPost] Create e verifique se o método nunca é chamado; a
validação do lado do cliente não enviará os dados de formulário quando forem detectados erros de validação. Se
você desabilitar o JavaScript no navegador e, em seguida, enviar o formulário com erros, o ponto de interrupção
será atingido. Você ainda pode obter uma validação completa sem o JavaScript.
A imagem a seguir mostra como desabilitar o JavaScript no navegador FireFox.
A imagem a seguir mostra como desabilitar o JavaScript no navegador Chrome.
Depois de desabilitar o JavaScript, poste os dados inválidos e execute o depurador em etapas.

Veja abaixo uma parte do modelo de exibição Create.cshtml gerada por scaffolding anteriormente no tutorial. Ela
é usada pelos métodos de ação mostrados acima para exibir o formulário inicial e exibi-lo novamente em caso de
erro.
<form asp-action="Create">
<h4>Movie</h4>
<hr />

</div>
</div>

</div>
</form>
O que é realmente interessante nessa abordagem é que o controlador nem o modelo de exibição Create sabem
nada sobre as regras de validação reais que estão sendo impostas ou as mensagens de erro específicas exibidas.
As regras de validação e as cadeias de caracteres de erro são especificadas somente na classe Movie . Essas
mesmas regras de validação são aplicadas automaticamente à exibição Edit e a outros modelos de exibição que
podem ser criados e que editam o modelo.
Quando você precisar alterar a lógica de validação, faça isso exatamente em um lugar, adicionando atributos de
validação ao modelo (neste exemplo, a classe Movie ). Você não precisa se preocupar se diferentes partes do
aplicativo estão inconsistentes com a forma como as regras são impostas – toda a lógica de validação será
definida em um lugar e usada em todos os lugares. Isso mantém o código muito limpo e torna-o mais fácil de
manter e desenvolver. Além disso, isso significa que você respeitará totalmente o princípio DRY.

Abra o arquivo Movie.cs e examine a classe Movie . O namespace System.ComponentModel.DataAnnotations fornece
atributos de formatação, além do conjunto interno de atributos de validação. Já aplicamos um valor de
enumeração DataType à data de lançamento e aos campos de preço. O código a seguir mostra as propriedades
ReleaseDate e Price com o atributo DataType apropriado.

[Range(1, 100)]
Os atributos DataType fornecem dicas apenas para que o mecanismo de exibição formate os dados (e fornece
dados mais específico do que o tipo intrínseco de banco de dados; eles não são atributos de validação. Nesse
caso, apenas desejamos acompanhar a data, não a hora. A Enumeração DataType fornece muitos tipos de dados,
como Date, Time, PhoneNumber, Currency, EmailAddress e muito mais. O atributo DataType também pode
permitir que o aplicativo forneça automaticamente recursos específicos a um tipo. Por exemplo, um link mailto:
pode ser criado para DataType.EmailAddress e um seletor de data pode ser fornecido para DataType.Date em
navegadores que dão suporte a HTML5. Os atributos DataType emitem atributos data- HTML 5 (ou "data
dash") que são reconhecidos pelos navegadores HTML 5. Os atributos DataType não fornecem nenhuma
validação.

A configuração ApplyFormatInEditMode especifica que a formatação também deve ser aplicada quando o valor é
exibido em uma caixa de texto para edição. (Talvez você não deseje isso em alguns campos – por exemplo, para
valores de moeda, provavelmente, você não deseja exibir o símbolo de moeda na caixa de texto para edição.)
Você pode usar o atributo DisplayFormat por si só, mas geralmente é uma boa ideia usar o atributo DataType . O
O atributo DataType pode permitir que o MVC escolha o modelo de campo correto para renderizar os
dados (o DisplayFormat , se usado por si só, usa o modelo de cadeia de caracteres).
NOTE
A validação do jQuery não funciona com os atributos Range e DateTime . Por exemplo, o seguinte código sempre exibirá
um erro de validação do lado do cliente, mesmo quando a data estiver no intervalo especificado:

Você precisará desabilitar a validação de data do jQuery para usar o atributo Range com DateTime . Geralmente,
não é uma boa prática compilar datas rígidas nos modelos e, portanto, o uso do atributo Range e de DateTime
não é recomendado.
public class Movie

{




}
public class Movie

{
[StringLength(60, MinimumLength = 3), Required]




[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$"), Required, StringLength(5)]

}
Na próxima parte da série, examinaremos o aplicativo e faremos algumas melhorias nos métodos Details e
Delete gerados automaticamente.
Recursos adicionais
Trabalhando com formulários
Examine os métodos Details e Delete de um
aplicativo ASP.NET Core
Por Rick Anderson

Abra o controlador Movie e examine o método Details :
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
O mecanismo de scaffolding MVC que criou este método de ação adiciona um comentário mostrando uma
solicitação HTTP que invoca o método. Nesse caso, é uma solicitação GET com três segmentos de URL, o
controlador Movies , o método Details e um valor id . Lembre-se que esses segmentos são definidos em
Startup.cs.
{
routes.MapRoute(
name: "default",
});
O EF facilita a pesquisa de dados usando o método SingleOrDefaultAsync . Um recurso de segurança importante
interno do método é que o código verifica se o método de pesquisa encontrou um filme antes de tentar fazer algo
com ele. Por exemplo, um hacker pode introduzir erros no site alterando a URL criada pelos links de
http://localhost:xxxx/Movies/Details/1 para algo como http://localhost:xxxx/Movies/Details/12345 (ou algum
outro valor que não representa um filme real). Se você não marcou um filme nulo, o aplicativo gerará uma exceção.
Examine os métodos Delete e DeleteConfirmed .
// GET: Movies/Delete/5
public async Task<IActionResult> Delete(int? id)
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
// POST: Movies/Delete/5
[HttpPost, ActionName("Delete")]
public async Task<IActionResult> DeleteConfirmed(int id)
{
_context.Movie.Remove(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
}
Observe que o método HTTP GET Delete não exclui o filme especificado, mas retorna uma exibição do filme em que
você pode enviar (HttpPost) a exclusão. A execução de uma operação de exclusão em resposta a uma solicitação
GET (ou, de fato, a execução de uma operação de edição, criação ou qualquer outra operação que altera dados)
abre uma falha de segurança.
O método [HttpPost] que exclui os dados é chamado DeleteConfirmed para fornecer ao método HTTP POST um
nome ou uma assinatura exclusiva. As duas assinaturas de método são mostradas abaixo:
{
{
O CLR (Common Language Runtime) exige que os métodos sobrecarregados tenham uma assinatura de
parâmetro exclusiva (mesmo nome de método, mas uma lista diferente de parâmetros). No entanto, aqui você
precisa de dois métodos Delete – um para GET e outro para POST – que têm a mesma assinatura de parâmetro.
(Ambos precisam aceitar um único inteiro como parâmetro.)
Há duas abordagens para esse problema e uma delas é fornecer aos métodos nomes diferentes. Foi isso o que o
mecanismo de scaffolding fez no exemplo anterior. No entanto, isso apresenta um pequeno problema: o ASP.NET
mapeia os segmentos de URL para os métodos de ação por nome e se você renomear um método, o roteamento
normalmente não conseguirá encontrar esse método. A solução é o que você vê no exemplo, que é adicionar o
atributo ActionName("Delete") ao método DeleteConfirmed . Esse atributo executa o mapeamento para o sistema de
roteamento, de modo que uma URL que inclui /Delete/ para uma solicitação POST encontre o método
DeleteConfirmed .
Outra solução alternativa comum para métodos que têm nomes e assinaturas idênticos é alterar artificialmente a
assinatura do método POST para incluir um parâmetro extra (não utilizado). Foi isso o que fizemos em uma
postagem anterior quando adicionamos o parâmetro notUsed . Você pode fazer o mesmo aqui para o método
[HttpPost] Delete :
public async Task<IActionResult> Delete(int id, bool notUsed)
Publicar no Azure
Para obter informações de como implantar no Azure, confira Tutorial: Criar um aplicativo Web .NET Core e do
Banco de Dados SQL no Serviço de Aplicativo do Azure.
A N T E R IO R
Criar um aplicativo ASP.NET Core MVC com o Visual
Studio Code
Visual Studio Code.
1. Introdução
Introdução ao ASP.NET Core MVC no Mac, no Linux
ou no Windows
Por Rick Anderson

Este tutorial ensinará os conceitos básicos da criação de um aplicativo Web ASP.NET Core MVC usando o VS
Code (Visual Studio Code). O tutorial pressupõe que você já tenha familiaridade com o VS Code. Consulte
Introdução ao VS Code e Ajuda do Visual Studio Code para obter mais informações.
projeto.
macOS: Criar um aplicativo ASP.NET Core MVC com o Visual Studio para Mac
Windows: Como criar um aplicativo ASP.NET Core MVC com o Visual Studio
Pré-requisitos
Instale o seguinte:
Visual Studio Code
Visual Studio Code
Criar um aplicativo Web com o dotnet

mkdir MvcMovie
cd MvcMovie
dotnet new mvc
Abra a pasta MvcMovie no Visual Studio Code (VS Code) e selecione o arquivo Startup.cs.
Selecione Sim para a mensagem de Aviso – Os ativos necessários para compilar e depurar estão ausentes
em “MvcMovie”. Deseja adicioná-los?”
Pressione Depurar (F5) para compilar e executar o programa.

O VS Code inicia o servidor Web Kestrel e executa o aplicativo. Observe que a barra de endereços mostra
localhost:5000 e não algo como example.com . Isso ocorre porque localhost é o nome do host padrão do
computador local.
para mostrá-los.

Introdução
Depuração
Terminal integrado
Atalhos de teclado
P R Ó X IM O – A D IC IO N A R U M
C ON TROL A D OR
Core
Por Rick Anderson

banco de dados.
tutorial.
No VS Code, selecione o ícone EXPLORER e, em seguida, pressione Control (clique com o botão direito
do mouse) Controladores > Novo Arquivo e nomeie o novo arquivo HelloWorldController.cs.
{
{
//

{
}
//

{
}
}
}
método.
invocado:
{
routes.MapRoute(
name: "default",
});
neste tutorial.
{
}
O código anterior:
JavaScript).
informações.

{
}
{
routes.MapRoute(
name: "default",
});
A N T E R IO R – A D IC IO N A R U M P R Ó X IM O – A D IC IO N A R U M A
C ON TROL A D OR E X IB IÇ Ã O
Core MVC
Por Rick Anderson


{
return View();
}
Adicione uma exibição Index ao HelloWorldController .
Adicione uma nova pasta chamada Views/HelloWorld.
Adicione um novo arquivo à pasta Views/HelloWorld chamada Index.cshtml.
@{
}
<h2>Index</h2>
Contato.

RenderBody .


<!DOCTYPE html>
<!DOCTYPE html>
<html>
<head>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
</div>
</ul>
</div>
</div>
</nav>
@RenderBody()
<hr />
<footer>
</footer>
</div>
</environment>
</script>
</script>
</environment>
</environment>

</body>
</html>
<!DOCTYPE html>
<html>
<head>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
</div>
</ul>
</div>
</div>
</nav>

@RenderBody()
<hr />
<footer>
</footer>
</div>
</environment>
</script>
</script>
</script>
</environment>

</body>
</html>
WARNING
encontrado).
@{
Layout = "_Layout";
}

layout seja usado.
@{
}

consulte Layout.
{
{
{
return View();
}

{
return View();
}
}
}
@{
}
<h2>Welcome</h2>
<ul>
{
}
</ul>

A N T E R IO R – A D IC IO N A R U M P R Ó X IM O – A D IC IO N A R U M
C ON TROL A D OR M ODELO
MVC


Adicionar uma classe denominada Movie.cs à pasta Modelos.
Adicione o código a seguir ao arquivo Models/Movie.cs:
using System;
{
public class Movie
{
}
}

Compile o aplicativo para verificar se você não tem nenhum erro e, por fim, você adicionou um Modelo ao seu
aplicativo MVC.
Preparar o projeto para scaffolding

Adicione os pacotes NuGet realçados a seguir ao arquivo MvcMovie.csproj:
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.0" />
</ItemGroup>
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.0" />
<DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0"
/>
</ItemGroup>
</Project>
Salve o arquivo e selecione Restaurar para a mensagem Informativa "Há dependências não resolvidas".
Crie um arquivo Models/MvcMovieContext.cs e adicione a seguinte classe MvcMovieContext :
{
public class MvcMovieContext : DbContext
{
public MvcMovieContext (DbContextOptions<MvcMovieContext> options)
: base(options)
{
}
public DbSet<MvcMovie.Models.Movie> Movie { get; set; }

}
}
Abra o arquivo Startup.cs e adicione dois usings:
namespace MvcMovie
{
{
Adicione o contexto do banco de dados para o arquivo Startup.cs:

{
services.AddMvc();
options.UseSqlite("Data Source=MvcMovie.db"));
Isso informa ao Entity Framework quais classes de modelo estão incluídas no modelo de dados. Você está
definindo um conjunto de entidades de objetos Movie, que serão representados no banco de dados como
uma tabela Movie.
Crie o projeto para verificar se não existem erros.
Faça o scaffolding do MovieController

Abra uma janela de terminal na pasta do projeto e execute os seguintes comandos:
dotnet restore
dotnet aspnet-codegenerator controller -name MoviesController -m Movie -dc MvcMovieContext --
relativeFolderPath Controllers --useDefaultLayout --referenceScriptLibraries
O mecanismo de scaffolding cria o seguinte:

A criação automática das exibições e métodos de ação CRUD (criar, ler, atualizar e excluir) é conhecida como
scaffolding. Logo você terá um aplicativo Web totalmente funcional que permitirá que você gerencie um banco de
dados de filmes.


O comando dotnet ef migrations add InitialCreate gera código para criar o esquema de banco de dados inicial.
O esquema é baseado no modelo especificado no DbContext (no arquivo Models/MvcMovieContext.cs). O
argumento Initial é usado para nomear as migrações. Você pode usar qualquer nome, mas, por convenção,
escolha um nome que descreve a migração. Consulte Introdução às migrações para obter mais informações.
O comando dotnet ef database update executa o método Up no arquivo Migrations/<time-
stamp>_InitialCreate.cs, que cria o banco de dados.
Testar o aplicativo
using System;
{
public class Movie
{
}
}
funcionais.
Agora você tem um banco de dados e páginas para exibir, editar, atualizar e excluir dados.No próximo tutorial,
trabalharemos com o banco de dados.
Recursos adicionais
A N T E R IO R – A D IC IO N A R U M A P R Ó X IM O – T R A B A L H A N D O C O M
E X IB IÇ Ã O S Q L IT E
Trabalhar com o SQLite em um aplicativo ASP.NET
Core MVC
Por Rick Anderson


{
services.AddMvc();
SQLite
using System;
using System.Linq;
{
{
{
{
{
}
new Movie
{
Price = 7.99M
},
new Movie
{
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Genre = "Western",
Price = 3.99M
}
);
}
}
}
}

{
}

using System;
using MvcMovie;
namespace MvcMovie
{
{
{

{
try
{
}
{
}
}
host.Run();
}

}
}
using System;
namespace MvcMovie
{
{
{

{
try
{
}
{
}
}
host.Run();
}

.Build();
}
}
Testar o aplicativo
A N T E R IO R – A D IC IO N A R U M P R Ó X IM O – E X IB IÇ Õ E S E M É T O D O S D O
M ODELO C ON TROL A D OR
Os métodos e as exibições do controlador no
ASP.NET Core
Por Rick Anderson

(12:00:00 AM na imagem abaixo) e ReleaseDate deve ser escrito em duas palavras.
using System;
{
public class Movie
{

}
}
Compile e execute o aplicativo.

de Dados.
URL de destino.

</td>
</tr>
<td>
</td>

{
routes.MapRoute(
name: "default",
});

{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
de postagem.
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
o padrão.
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
@{
}
<h2>Edit</h2>
<h4>Movie</h4>
<hr />
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</form>
<div>
</div>
@section Scripts {
}
Movie .

<h4>Movie</h4>
<hr />
value="7" />
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</form>

[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
apropriadas.
Recursos adicionais
ViewModels
A N T E R IO R – T R A B A L H A N D O C O M O P R Ó X IM O – A D IC IO N A R U M A
S Q L IT E P E S Q U IS A
MVC
Por Rick Anderson


{
select m;
{
}

}

select m;
{
}
{
routes.MapRoute(
name: "default",
});
Observação: o SQLlite diferencia maiúsculas de minúsculas e, portanto, você precisará pesquisar “Ghost” e não
“ghost”.

{
select m;
{
}

}

{
select m;
{
}

}

{
select m;
{
}

}

}
<h2>Index</h2>
<p>
</p>

<p>
</p>
</form>
<thead>
[HttpPost]
{
}
Altere a marcação <form> na exibição Views\movie\Index.cshtml do Razor para especificar method="get" :

{
{
}
}


{
orderby m.Genre
select m.Genre;

select m;
{
}
{
}

}

orderby m.Genre
select m.Genre;

@{
}
<h2>Index</h2>
<p>
</p>

<p>
</select>

</p>
</form>
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>

A N T E R IO R – E X IB IÇ Õ E S E M É T O D O S D O P R Ó X IM O – A D IC IO N A R U M
C ON TROL A D OR CAM PO
Core MVC
Por Rick Anderson

Este tutorial adicionará um novo campo à tabela Movies . Removeremos o banco de dados e criaremos um novo
ao alterar o esquema (adicionar um novo campo). Este fluxo de trabalho funciona bem no início do
desenvolvimento quando não temos nenhum dado de produção para preservar.
Depois que o aplicativo for implantado e você tiver dados que precisa preservar, não poderá remover o BD
quando precisar alterar o esquema. As Migrações do Entity Framework Code First permitem atualizar o esquema
e migrar o banco de dados sem perder dados. As Migrações são um recurso popular ao usar o SQL Server, mas o
SQLite não dá suporte a muitas operações de esquema de migração e, portanto, apenas migrações muito simples
são possíveis. Consulte Limitações do SQLite para obter mais informações.

public class Movie

{


}
public class Movie

{

}
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
Atualize /Views/Movies/Create.cshtml com um campo Rating .

obterá o seguinte SqliteException :
SqliteException: SQLite Error 1: 'no such column: m.Rating'.
do banco de dados existente. (Não há nenhuma coluna Rating na tabela de banco de dados.)
1. Remova o banco de dados e faça com que o Entity Framework recrie automaticamente o banco de dados
com base no novo esquema de classe de modelo. Com essa abordagem, você perde os dados existentes no
banco de dados – portanto, não é possível fazer isso com um banco de dados de produção! Muitas vezes, o
uso de um inicializador para propagar um banco de dados com os dados de teste automaticamente é uma
maneira produtiva de desenvolver um aplicativo.
2. Modifique manualmente o esquema do banco de dados existente para que ele corresponda às classes de
Para este tutorial, removeremos e recriaremos o banco de dados quando o esquema for alterado. Execute o
seguinte comando em um terminal para remover o BD:
dotnet ef database drop
new Movie
{
Rating = "R",
Price = 7.99M
},
Adicione o campo Rating às exibições Edit , Details e Delete .

Execute o aplicativo e verifique se você pode criar/editar/exibir filmes com um campo Rating . modelos.
A N T E R IO R – A D IC IO N A R U M A P R Ó X IM O – A D IC IO N A R
MVC
Por Rick Anderson



Range internos.
public class Movie
{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}
public class Movie

{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}
no banco de dados.

NOTE

Talvez você esteja se perguntando como a interface do usuário de validação foi gerada sem atualizações do código
no controlador ou nas exibições. O código a seguir mostra os dois métodos Create .
{
return View();
}
[HttpPost]
{
{
}
return View(movie);
}

erro.
<h4>Movie</h4>
<hr />

</div>
</div>

</div>
</form>


[Range(1, 100)]
dados mais específico do que o tipo intrínseco de banco de dados; eles não são atributos de validação. Nesse caso,
apenas desejamos acompanhar a data, não a hora. A Enumeração DataType fornece muitos tipos de dados, como
Date, Time, PhoneNumber, Currency, EmailAddress e muito mais. O atributo DataType também pode permitir
que o aplicativo forneça automaticamente recursos específicos a um tipo. Por exemplo, um link mailto: pode ser
criado para DataType.EmailAddress e um seletor de data pode ser fornecido para DataType.Date em navegadores
que dão suporte a HTML5. Os atributos DataType emitem atributos data- HTML 5 (ou "data dash") que são
reconhecidos pelos navegadores HTML 5. Os atributos DataType não fornecem nenhuma validação.

NOTE
public class Movie

{




}
public class Movie

{





}
Recursos adicionais
A N T E R IO R – A D IC IO N A R U M P R Ó X IM O – E X A M IN A R O S M É T O D O S D E T A IL S E
CAM PO D E L E TE
Por Rick Anderson

{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
Startup.cs.
{
routes.MapRoute(
name: "default",
});
O EF facilita a pesquisa de dados usando o método SingleOrDefaultAsync . Um recurso de segurança importante
interno do método é que o código verifica se o método de pesquisa encontrou um filme antes de tentar fazer algo
com ele. Por exemplo, um hacker pode introduzir erros no site alterando a URL criada pelos links de
http://localhost:xxxx/Movies/Details/1 para algo como http://localhost:xxxx/Movies/Details/12345 (ou algum
outro valor que não representa um filme real). Se você não marcou um filme nulo, o aplicativo gerará uma exceção.
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
}
Observe que o método HTTP GET Delete não exclui o filme especificado, mas retorna uma exibição do filme em que
você pode enviar (HttpPost) a exclusão. A execução de uma operação de exclusão em resposta a uma solicitação
GET (ou, de fato, a execução de uma operação de edição, criação ou qualquer outra operação que altera dados)
abre uma falha de segurança.
O método [HttpPost] que exclui os dados é chamado DeleteConfirmed para fornecer ao método HTTP POST um
nome ou uma assinatura exclusiva. As duas assinaturas de método são mostradas abaixo:
{
{
precisa de dois métodos Delete – um para GET e outro para POST – que têm a mesma assinatura de parâmetro.
(Ambos precisam aceitar um único inteiro como parâmetro.)
Há duas abordagens para esse problema e uma delas é fornecer aos métodos nomes diferentes. Foi isso o que o
mecanismo de scaffolding fez no exemplo anterior. No entanto, isso apresenta um pequeno problema: o ASP.NET
mapeia os segmentos de URL para os métodos de ação por nome e se você renomear um método, o roteamento
normalmente não conseguirá encontrar esse método. A solução é o que você vê no exemplo, que é adicionar o
atributo ActionName("Delete") ao método DeleteConfirmed . Esse atributo executa o mapeamento para o sistema de
roteamento, de modo que uma URL que inclui /Delete/ para uma solicitação POST encontre o método
DeleteConfirmed .
Outra solução alternativa comum para métodos que têm nomes e assinaturas idênticos é alterar artificialmente a
assinatura do método POST para incluir um parâmetro extra (não utilizado). Foi isso o que fizemos em uma
[HttpPost] Delete :
Publicar no Azure
A N T E R IO R
no macOS com o Visual Studio para Mac
Visual Studio para Mac.
1. Introdução
5. SQLite
Introdução ao ASP.NET Core MVC e ao Visual
Studio para Mac
Por Rick Anderson

Este tutorial ensina os conceitos básicos da criação de um aplicativo Web ASP.NET Core MVC usando o Visual
Studio para Mac.
projeto.
macOS: Compilar um aplicativo ASP.NET Core MVC com o Visual Studio para Mac
Windows: Compilar um aplicativo ASP.NET Core MVC com o Visual Studio
Linux, macOS e Windows: Compilar um aplicativo ASP.NET Core MVC com o Visual Studio Code
Pré-requisitos

Selecione Aplicativo .NET Core > ASP.NET Core > Aplicativo Web > Avançar.
Nomeie o projeto MvcMovie e, em seguida, selecione Criar.

No Visual Studio, selecione Executar > Iniciar Sem Depuração para iniciar o aplicativo. O Visual Studio inicia
o Kestrel, inicia um navegador e navega para http://localhost:port , em que porta é um número da porta
escolhido aleatoriamente.
A barra de endereços mostra localhost:port# e não algo como example.com . Isso ocorre porque localhost
é o nome do host padrão do computador local. Quando o Visual Studio cria um projeto Web, uma porta
aleatória é usada para o servidor Web. Quando você executar o aplicativo, verá um número da porta
diferente.
Você pode iniciar o aplicativo no modo de depuração ou sem depuração no item de menu Executar.
O modelo padrão fornece os links Página Inicial, Sobre e Contato. A imagem do navegador acima não
mostra esses links. Dependendo do tamanho do navegador, talvez você precise clicar no ícone de navegação
para mostrá-los.
Na próxima parte deste tutorial, você saberá mais sobre o MVC e começará a escrever um pouco de código.
A VA N ÇA R
Core MVC com o Visual Studio para Mac
Por Rick Anderson

banco de dados.
tutorial.
No Gerenciador de Soluções, clique com o botão direito do mouse em Controladores > Adicionar > Novo
Arquivo.
Selecione ASP.NET Core e Classe do Controlador MVC.
Nomeie o controlador HelloWorldController.

{
{
//

{
}
//

{
}
}
}
método.
invocado:

{
routes.MapRoute(
name: "default",
});
neste tutorial.
{
}
O código anterior:
JavaScript).
informações.

{
}
{
routes.MapRoute(
name: "default",
});
Core MVC
Por Rick Anderson


{
return View();
}

Clique com o botão direito do mouse na pasta Exibições e, em seguida, Adicionar > Nova Pasta e
nomeie a pasta HelloWorld.
Clique com o botão direito do mouse na pasta Views/HelloWorld e, em seguida, clique em Adicionar >
Novo Arquivo.
Selecione Web no painel esquerdo.
Selecione Arquivo HTML vazio no painel central.
Digite Index.cshtml na caixa Nome.
Selecione Novo.
@{
}
<h2>Index</h2>
Contato.
RenderBody .


<!DOCTYPE html>
<html>
<head>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
</div>
</ul>
</div>
</div>
</nav>
@RenderBody()
<hr />
<footer>
</footer>
</div>
</environment>
</script>
</script>
</environment>

</body>
</html>
<!DOCTYPE html>
<html>
<head>
</environment>
value="absolute" />
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
</div>
</ul>
</div>
</div>
</nav>

@RenderBody()
<hr />
<footer>
</footer>
</div>
</environment>
</script>
</script>
</environment>

</body>
</html>
WARNING
encontrado).
@{
Layout = "_Layout";
}

layout seja usado.
@{
}

consulte Layout.

{
{
{
return View();
}

{
return View();
}
}
}
@{
}
<h2>Welcome</h2>
<ul>
{
}
</ul>
MVC


Clique com o botão direito do mouse na pasta Modelos e, em seguida, selecione Adicionar > Novo
Arquivo.
Selecione Geral no painel esquerdo.
Selecione Classe Vazia no painel central.
Nomeie a classe Movie e selecione Novo.
using System;
{
public class Movie
{
}
}

Compile o projeto para verificar se não há erros. Agora você tem um Modelo no seu aplicativo MVC.
Preparar o projeto para scaffolding

Clique com o botão direito do mouse no arquivo de projeto e, em seguida, selecione Ferramentas >
Editar Arquivo.
Adicione os pacotes NuGet realçados a seguir ao arquivo MvcMovie.csproj:
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0"
/>
</ItemGroup>
</Project>
Salve o arquivo.
Crie um arquivo Models/MvcMovieContext.cs e adicione a seguinte classe MvcMovieContext : [!code-csharp]
Abra o arquivo Startup.cs e adicione dois usings: [!code-csharp]
Adicione o contexto do banco de dados para o arquivo Startup.cs:
{
services.AddMvc();
Isso informa ao Entity Framework quais classes de modelo estão incluídas no modelo de dados. Você está
definindo um conjunto de entidades de objetos Movie, que serão representados no banco de dados como
uma tabela Movie.
Crie o projeto para verificar se não existem erros.
Faça o scaffolding do MovieController

Abra uma janela de terminal na pasta do projeto e execute os seguintes comandos:
dotnet restore
dotnet aspnet-codegenerator controller -name MoviesController -m Movie -dc MvcMovieContext --
relativeFolderPath Controllers --useDefaultLayout --referenceScriptLibraries
Se você obtiver o erro No executable found matching command "dotnet-aspnet-codegenerator", verify :

Você está no diretório do projeto. O diretório do projeto tem os arquivos Program.cs, Startup.cs e .csproj.
Sua versão do dotnet é 1.1 ou posterior. Execute dotnet para obter a versão.
Você adicionou o elemento <DotNetCliToolReference> ao arquivo MvcMovie.csproj.
O mecanismo de scaffolding cria o seguinte:
A criação automática das exibições e métodos de ação CRUD (criar, ler, atualizar e excluir) é conhecida como
scaffolding. Logo você terá um aplicativo Web totalmente funcional que permitirá que você gerencie um banco de
dados de filmes.
Adicionar os arquivos ao Visual Studio
Adicione o arquivo MovieController.cs ao projeto do Visual Studio:
Clique com o botão direito do mouse na pasta Controladores e selecione Adicionar > Adicionar
Arquivos.
Selecione o arquivo MovieController.cs.
Adicione a pasta Filmes e as exibições:
Clique com o botão direito do mouse na pasta Exibições e selecione Adicionar > Adicionar Pasta
Existente.
Navegue até a pasta Exibições, selecione Exibições\Filmes e, em seguida, selecione Abrir.
Na caixa de diálogo Selecionar arquivos para adicionar de Filmes, selecione Incluir Todos e, em
seguida, OK.

O comando dotnet ef migrations add InitialCreate gera código para criar o esquema de banco de dados inicial.
O esquema é baseado no modelo especificado no DbContext (no arquivo Models/MvcMovieContext.cs). O
argumento Initial é usado para nomear as migrações. Você pode usar qualquer nome, mas, por convenção,
escolha um nome que descreve a migração. Consulte Introdução às migrações para obter mais informações.
O comando dotnet ef database update executa o método Up no arquivo Migrations/<time-
stamp>_InitialCreate.cs, que cria o banco de dados.
Testar o aplicativo
using System;
{
public class Movie
{
}
}

funcionais.
Agora você tem um banco de dados e páginas para exibir, editar, atualizar e excluir dados.No próximo tutorial,
trabalharemos com o banco de dados.
Recursos adicionais
A N T E R IO R – A D IC IO N A N D O U M A P R Ó X IM O – T R A B A L H A N D O C O M O
E X IB IÇ Ã O SQL
Trabalhar com o SQLite em um aplicativo ASP.NET
Core MVC
Por Rick Anderson


{
services.AddMvc();
SQLite
using System;
using System.Linq;
{
{
{
{
{
}
new Movie
{
Price = 7.99M
},
new Movie
{
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Genre = "Western",
Price = 3.99M
}
);
}
}
}
}

{
}

using System;
using MvcMovie;
namespace MvcMovie
{
{
{

{
try
{
}
{
}
}
host.Run();
}

}
}
using System;
namespace MvcMovie
{
{
{

{
try
{
}
{
}
}
host.Run();
}

.Build();
}
}
Testar o aplicativo
A N T E R IO R – A D IC IO N A R U M P R Ó X IM O – E X IB IÇ Õ E S E M É T O D O S D O
M ODELO C ON TROL A D OR
Exibições e métodos do controlador em um
aplicativo ASP.NET Core MVC
Por Rick Anderson

(12:00:00 AM na imagem a seguir) e ReleaseDate deve ser escrito em duas palavras.
using System;
{
public class Movie
{

}
}
Compile e execute o aplicativo.

de Dados.
URL de destino.

</td>
</tr>
<td>
</td>

{
routes.MapRoute(
name: "default",
});

{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
de postagem.
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
o padrão.
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
@{
}
<h2>Edit</h2>
<h4>Movie</h4>
<hr />
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</form>
<div>
</div>
@section Scripts {
}
Movie .

<h4>Movie</h4>
<hr />
value="7" />
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</form>

[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
apropriadas.
Recursos adicionais
ViewModels
A N T E R IO R – T R A B A L H A N D O C O M O P R Ó X IM O – A D IC IO N A R U M A
S Q L IT E P E S Q U IS A
MVC
Por Rick Anderson


{
select m;
{
}

}

select m;
{
}
{
routes.MapRoute(
name: "default",
});
Observação: o SQLlite diferencia maiúsculas de minúsculas e, portanto, você precisará pesquisar “Ghost” e não
“ghost”.

{
select m;
{
}

}

{
select m;
{
}

}

{
select m;
{
}

}

}
<h2>Index</h2>
<p>
</p>

<p>
</p>
</form>
<thead>
[HttpPost]
{
}
Altere a marcação <form> na exibição Views\movie\Index.cshtml do Razor para especificar method="get" :

{
{
}
}


{
orderby m.Genre
select m.Genre;

select m;
{
}
{
}

}

orderby m.Genre
select m.Genre;

@{
}
<h2>Index</h2>
<p>
</p>

<p>
</select>

</p>
</form>
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>

A N T E R IO R – E X IB IÇ Õ E S E M É T O D O S D O P R Ó X IM O – A D IC IO N A R U M
C ON TROL A D OR CAM PO
Core MVC
Por Rick Anderson

Este tutorial adicionará um novo campo à tabela Movies . Removeremos o banco de dados e criaremos um novo
ao alterar o esquema (adicionar um novo campo). Este fluxo de trabalho funciona bem no início do
desenvolvimento quando não temos nenhum dado de produção para preservar.
Depois que o aplicativo for implantado e você tiver dados que precisa preservar, não poderá remover o BD
quando precisar alterar o esquema. As Migrações do Entity Framework Code First permitem atualizar o esquema
e migrar o banco de dados sem perder dados. As Migrações são um recurso popular ao usar o SQL Server, mas o
SQLite não dá suporte a muitas operações de esquema de migração e, portanto, apenas migrações muito simples
são possíveis. Consulte Limitações do SQLite para obter mais informações.

public class Movie

{


}
public class Movie

{

}
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
Atualize /Views/Movies/Create.cshtml com um campo Rating .

obterá o seguinte SqliteException :
SqliteException: SQLite Error 1: 'no such column: m.Rating'.
do banco de dados existente. (Não há nenhuma coluna Rating na tabela de banco de dados.)
1. Remova o banco de dados e faça com que o Entity Framework recrie automaticamente o banco de dados
com base no novo esquema de classe de modelo. Com essa abordagem, você perde os dados existentes no
banco de dados – portanto, não é possível fazer isso com um banco de dados de produção! Muitas vezes, o
uso de um inicializador para propagar um banco de dados com os dados de teste automaticamente é uma
maneira produtiva de desenvolver um aplicativo.
2. Modifique manualmente o esquema do banco de dados existente para que ele corresponda às classes de
Para este tutorial, removeremos e recriaremos o banco de dados quando o esquema for alterado. Execute o
seguinte comando em um terminal para remover o BD:
new Movie
{
Rating = "R",
Price = 7.99M
},
Adicione o campo Rating às exibições Edit , Details e Delete .

Execute o aplicativo e verifique se você pode criar/editar/exibir filmes com um campo Rating . modelos.
A N T E R IO R – A D IC IO N A R U M A P R Ó X IM O – A D IC IO N A R
MVC
Por Rick Anderson



Range internos.
public class Movie
{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}
public class Movie

{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}
no banco de dados.

NOTE

Talvez você esteja se perguntando como a interface do usuário de validação foi gerada sem atualizações do código
no controlador ou nas exibições. O código a seguir mostra os dois métodos Create .
{
return View();
}
[HttpPost]
{
{
}
return View(movie);
}

erro.
<h4>Movie</h4>
<hr />

</div>
</div>

</div>
</form>


[Range(1, 100)]
dados mais específico do que o tipo intrínseco de banco de dados; eles não são atributos de validação. Nesse caso,
apenas desejamos acompanhar a data, não a hora. A Enumeração DataType fornece muitos tipos de dados, como
Date, Time, PhoneNumber, Currency, EmailAddress e muito mais. O atributo DataType também pode permitir
que o aplicativo forneça automaticamente recursos específicos a um tipo. Por exemplo, um link mailto: pode ser
criado para DataType.EmailAddress e um seletor de data pode ser fornecido para DataType.Date em navegadores
que dão suporte a HTML5. Os atributos DataType emitem atributos data- HTML 5 (ou "data dash") que são
reconhecidos pelos navegadores HTML 5. Os atributos DataType não fornecem nenhuma validação.

NOTE
public class Movie

{




}
public class Movie

{





}
Recursos adicionais
A N T E R IO R – A D IC IO N A R U M P R Ó X IM O – E X A M IN A R O S M É T O D O S D E T A IL S E
CAM PO D E L E TE
Por Rick Anderson

{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
Startup.cs.
{
routes.MapRoute(
name: "default",
});
O EF facilita a pesquisa de dados usando o método SingleOrDefaultAsync . Um recurso de segurança
importante interno do método é que o código verifica se o método de pesquisa encontrou um filme antes de
tentar fazer algo com ele. Por exemplo, um hacker pode introduzir erros no site alterando a URL criada pelos
links de http://localhost:xxxx/Movies/Details/1 para algo como http://localhost:xxxx/Movies/Details/12345
(ou algum outro valor que não representa um filme real). Se você não marcou um filme nulo, o aplicativo
gerará uma exceção.
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
}
Observe que o método HTTP GET Delete não exclui o filme especificado, mas retorna uma exibição do filme em
que você pode enviar (HttpPost) a exclusão. A execução de uma operação de exclusão em resposta a uma
solicitação GET (ou, de fato, a execução de uma operação de edição, criação ou qualquer outra operação que
altera dados) abre uma falha de segurança.
O método [HttpPost] que exclui os dados é chamado DeleteConfirmed para fornecer ao método HTTP POST
um nome ou uma assinatura exclusiva. As duas assinaturas de método são mostradas abaixo:
{
{
precisa de dois métodos Delete – um para GET e outro para POST – que têm a mesma assinatura de
parâmetro. (Ambos precisam aceitar um único inteiro como parâmetro.)
Há duas abordagens para esse problema e uma delas é fornecer aos métodos nomes diferentes. Foi isso o que
o mecanismo de scaffolding fez no exemplo anterior. No entanto, isso apresenta um pequeno problema: o
ASP.NET mapeia os segmentos de URL para os métodos de ação por nome e se você renomear um método, o
roteamento normalmente não conseguirá encontrar esse método. A solução é o que você vê no exemplo, que é
adicionar o atributo ActionName("Delete") ao método DeleteConfirmed . Esse atributo executa o mapeamento
para o sistema de roteamento, de modo que uma URL que inclui /Delete/ para uma solicitação POST encontre
o método DeleteConfirmed .
Outra solução alternativa comum para métodos que têm nomes e assinaturas idênticos é alterar artificialmente
a assinatura do método POST para incluir um parâmetro extra (não utilizado). Foi isso o que fizemos em uma
[HttpPost] Delete :
Publicar no Azure
A N T E R IO R
Exibições no ASP.NET Core MVC
Por Steve Smith e Luke Latham

Este documento explica as exibições usadas em aplicativos do ASP.NET Core MVC. Para obter informações
sobre páginas do Razor, consulte Introdução a Páginas do Razor.
No padrão MVC (Modelo-Exibição-Controlador), a exibição cuida da apresentação de dados do aplicativo e da
interação com o usuário. Uma exibição é um modelo HTML com marcação Razor inserida. A marcação Razor é
um código que interage com a marcação HTML para produzir uma página da Web que é enviada ao cliente.
No ASP.NET Core MVC, as exibições são arquivos .cshtml que usam a linguagem de programação C# na
marcação Razor. Geralmente, arquivos de exibição são agrupados em pastas nomeadas para cada um dos
controladores do aplicativo. As pastas são armazenadas em uma pasta chamada Views na raiz do aplicativo:
O controlador Home é representado por uma pasta Home dentro da pasta Views. A pasta Home contém as
exibições das páginas da Web About, Contact e Index (home page). Quando um usuário solicita uma dessas três
páginas da Web, ações do controlador Home determinam qual das três exibições é usada para compilar e
retornar uma página da Web para o usuário.
Use layouts para fornecer seções de páginas da Web consistentes e reduzir repetições de código. Layouts
geralmente contêm o cabeçalho, elementos de navegação e menu e o rodapé. O cabeçalho e o rodapé
geralmente contêm marcações repetitivas para muitos elementos de metadados, bem como links para ativos de
script e estilo. Layouts ajudam a evitar essa marcação repetitiva em suas exibições.
Exibições parciais reduzem a duplicação de código gerenciando as partes reutilizáveis das exibições. Por
exemplo, uma exibição parcial é útil para uma biografia do autor que aparece em várias exibições em um site de
blog. Uma biografia do autor é um conteúdo de exibição comum e não requer que um código seja executado
para produzi-lo para a página da Web. O conteúdo da biografia do autor é disponibilizado para a exibição
usando somente a associação de modelos, de modo que usar uma exibição parcial para esse tipo de conteúdo é
ideal.
Componentes de exibição são semelhantes a exibições parciais no sentido em que permitem reduzir códigos
repetitivos, mas são adequados para conteúdos de exibição que requerem que um código seja executado no
servidor para renderizar a página da Web. Componentes de exibição são úteis quando o conteúdo renderizado
requer uma interação com o banco de dados, como para o carrinho de compras de um site. Os componentes de
exibição não ficam limitados à associação de modelos para produzir a saída da página da Web.
Benefícios do uso de exibições

As exibições ajudam a estabelecer um design SoC (Separação de Interesses) dentro de um aplicativo MVC,
separando a marcação da interface do usuário de outras partes do aplicativo. Seguir um design de SoC faz com
que seu aplicativo seja modular, o que fornece vários benefícios:
A manutenção do aplicativo é mais fácil, porque ele é melhor organizado. Geralmente, as exibições são
agrupadas segundo os recursos do aplicativo. Isso facilita encontrar exibições relacionadas ao trabalhar em
um recurso.
As partes do aplicativo ficam acopladas de forma flexível. Você pode compilar e atualizar as exibições do
aplicativo separadamente da lógica de negócios e dos componentes de acesso a dados. É possível modificar
os modos de exibição do aplicativo sem precisar necessariamente atualizar outras partes do aplicativo.
É mais fácil testar as partes da interface do usuário do aplicativo porque as exibições são unidades separadas.
Devido à melhor organização, é menos provável que você repita acidentalmente seções da interface do
usuário.
Criando uma exibição

Exibições que são específicas de um controlador são criadas na pasta Views/ [NomeDoControlador ]. Exibições
que são compartilhadas entre controladores são colocadas na pasta Views/Shared. Para criar uma exibição,
adicione um novo arquivo e dê a ele o mesmo nome que o da ação de seu controlador associado, com a
extensão de arquivo .cshtml. Para criar uma exibição correspondente à ação About no controlador Home, crie um
arquivo About.cshtml na pasta Views/Home:
@{
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>
<p>Use this area to provide additional information.</p>
A marcação Razor começa com o símbolo @ . Execute instruções em C# colocando o código C# dentro de
blocos de código Razor entre chaves ( { ... } ). Por exemplo, consulte a atribuição de "About" para
ViewData["Title"] mostrado acima. É possível exibir valores em HTML simplesmente referenciando o valor
com o símbolo @ . Veja o conteúdo dos elementos <h2> e <h3> acima.
O conteúdo da exibição mostrado acima é apenas uma parte da página da Web inteira que é renderizada para o
usuário. O restante do layout da página e outros aspectos comuns da exibição são especificados em outros
arquivos de exibição. Para saber mais, consulte o tópico sobre Layout.
Como controladores especificam exibições

Normalmente, as exibições são retornadas de ações como um ViewResult, que é um tipo de ActionResult. O
método de ação pode criar e retornar um ViewResult diretamente, mas normalmente isso não é feito. Como a
maioria dos controladores herdam de Controller, basta usar o método auxiliar View para retornar o ViewResult
:
HomeController.cs
public IActionResult About()

{
ViewData["Message"] = "Your application description page.";
return View();
}
Quando essa ação é retornada, a exibição About.cshtml mostrada na seção anterior é renderizada como a
seguinte página da Web:
O método auxiliar View tem várias sobrecargas. Opcionalmente, você pode especificar:
Uma exibição explícita a ser retornada:
return View("Orders");
Um modelo a ser passado para a exibição:
return View(Orders);
Um modo de exibição e um modelo:
return View("Orders", Orders);
Descoberta de exibição
Quando uma ação retorna uma exibição, um processo chamado descoberta de exibição ocorre. Esse processo
determina qual arquivo de exibição é usado com base no nome da exibição.
O comportamento padrão do método View ( return View(); ) é retornar uma exibição com o mesmo nome que
o método de ação do qual ela é chamada. Por exemplo, o nome do método ActionResult de About do
controlador é usado para pesquisar um arquivo de exibição chamado About.cshtml. Primeiro, o tempo de
execução pesquisa pela exibição na pasta Views/[NomeDoControlador ]. Se não encontrar uma exibição
correspondente nela, ele procura pela exibição na pasta Shared.
Não importa se você retornar implicitamente o ViewResult com return View(); ou se passar explicitamente o
nome de exibição para o método View com return View("<ViewName>"); . Nos dois casos, a descoberta de
exibição pesquisa por um arquivo de exibição correspondente nesta ordem:
1. Views/[ControllerName]/[ViewName].cshtml
2. Views/Shared/[NomeDaExibição ].cshtml
Um caminho de arquivo de exibição pode ser fornecido em vez de um nome de exibição. Se um caminho
absoluto que começa na raiz do aplicativo (ou é iniciado por "/" ou "~ /") estiver sendo usado, a extensão .cshtml
deverá ser especificada:
return View("Views/Home/About.cshtml");
Você também pode usar um caminho relativo para especificar exibições em diretórios diferentes sem a extensão
.cshtml. Dentro do HomeController , você pode retornar a exibição Index de suas exibições Manage com um
caminho relativo:
return View("../Manage/Index");
De forma semelhante, você pode indicar o atual diretório específico do controlador com o prefixo ". /":
return View("./About");
Exibições parciais e componentes de exibição usam mecanismos de descoberta semelhantes (mas não idênticos).
É possível personalizar a convenção padrão de como as exibições ficam localizadas dentro do aplicativo usando
um IViewLocationExpander personalizado.
A descoberta de exibição depende da localização de arquivos de exibição pelo nome do arquivo. Se o sistema de
arquivos subjacente diferenciar maiúsculas de minúsculas, os nomes de exibição provavelmente diferenciarão
maiúsculas de minúsculas. Para fins de compatibilidade de sistemas operacionais, padronize as maiúsculas e
minúsculas dos nomes de controladores e de ações e dos nomes de arquivos e pastas de exibição. Se encontrar
um erro indicando que não é possível encontrar um arquivo de exibição ao trabalhar com um sistema de
arquivos que diferencia maiúsculas de minúsculas, confirme que o uso de maiúsculas e minúsculas é
correspondente entre o arquivo de exibição solicitado e o nome do arquivo de exibição real.
Siga a melhor prática de organizar a estrutura de arquivos de suas exibições de forma a refletir as relações entre
controladores, ações e exibições para facilidade de manutenção e clareza.
Passando dados para exibições

Passe dados para exibições usando várias abordagens:
Dados fortemente tipados: viewmodel
Dados fracamente tipados
ViewData ( ViewDataAttribute )
ViewBag
Dados fortemente tipados (viewmodel)

A abordagem mais robusta é especificar um tipo de modelo na exibição. Esse modelo é conhecido como
viewmodel. Você passa uma instância do tipo viewmodel para a exibição da ação.
Usar um viewmodel para passar dados para uma exibição permite que a exibição tire proveito da verificação de
tipo forte. Tipagem forte (ou fortemente tipado) significa que cada variável e constante têm um tipo definido
explicitamente (por exemplo, string , int ou DateTime ). A validade dos tipos usados em uma exibição é
verificada em tempo de compilação.
O Visual Studio e o Visual Studio Code listam membros de classe fortemente tipados usando um recurso
chamado IntelliSense. Quando quiser ver as propriedades de um viewmodel, digite o nome da variável para o
viewmodel, seguido por um ponto final ( . ). Isso ajuda você a escrever código mais rapidamente e com menos
erros.
Especifique um modelo usando a diretiva @model . Use o modelo com @Model :
@model WebApplication1.ViewModels.Address
<h2>Contact</h2>
<address>
@Model.Street<br>
@Model.City, @Model.State @Model.PostalCode<br>
<abbr title="Phone">P:</abbr> 425.555.0100
</address>
Para fornecer o modelo à exibição, o controlador o passa como um parâmetro:
public IActionResult Contact()

{
ViewData["Message"] = "Your contact page.";
var viewModel = new Address()

{
Name = "Microsoft",
Street = "One Microsoft Way",
City = "Redmond",
State = "WA",
PostalCode = "98052-6399"
};
return View(viewModel);
}
Não há restrições quanto aos tipos de modelo que você pode fornecer a uma exibição. Recomendamos o uso de
viewmodels do tipo POCO (objeto CRL básico) com pouco ou nenhum comportamento (métodos) definido.
Geralmente, classes de viewmodel são armazenadas na pasta Models ou em uma pasta ViewModels separada na
raiz do aplicativo. O viewmodel Address usado no exemplo acima é um viewmodel POCO armazenado em um
arquivo chamado Address.cs:
namespace WebApplication1.ViewModels
{
public class Address
{
public string Street { get; set; }
public string City { get; set; }
public string State { get; set; }
public string PostalCode { get; set; }
}
}
Nada impede que você use as mesmas classes para seus tipos de viewmodel e seus tipos de modelo de
negócios. No entanto, o uso de modelos separados permite que suas exibições variem independentemente das
partes de lógica de negócios e de acesso a dados do aplicativo. A separação de modelos e viewmodels também
oferece benefícios de segurança quando os modelos usam associação de modelos e validação para dados
enviados ao aplicativo pelo usuário.
Dados fracamente tipados (ViewData, atributo ViewData e ViewBag)
ViewBag não está disponível nas Páginas do Razor.
Além de exibições fortemente tipadas, as exibições têm acesso a uma coleção de dados fracamente tipados
(também chamada de tipagem flexível). Diferente dos tipos fortes, ter tipos fracos (ou tipos flexíveis) significa
que você não declara explicitamente o tipo dos dados que está usando. Você pode usar a coleção de dados
fracamente tipados para transmitir pequenas quantidades de dados para dentro e para fora dos controladores e
das exibições.
PASSAR DADOS ENTRE... EXEMPLO
Um controlador e uma exibição Preencher uma lista suspensa com os dados.
Uma exibição e uma exibição de layout Definir o conteúdo do elemento <title> na exibição de
layout de um arquivo de exibição.
Uma exibição parcial e uma exibição Um widget que exibe dados com base na página da Web que
o usuário solicitou.
Essa coleção pode ser referenciada por meio das propriedades ViewData ou ViewBag em controladores e
exibições. A propriedade ViewData é um dicionário de objetos fracamente tipados. A propriedade ViewBag é um
wrapper em torno de ViewData que fornece propriedades dinâmicas à coleção de ViewData subjacente.
ViewData e ViewBag são resolvidos dinamicamente em tempo de execução. Uma vez que não oferecem
verificação de tipo em tempo de compilação, geralmente ambos são mais propensos a erros do que quando um
viewmodel é usado. Por esse motivo, alguns desenvolvedores preferem nunca usar ViewData e ViewBag ou usá-
los o mínimo possível.
ViewData
ViewData é um objeto ViewDataDictionary acessado por meio de chaves string . Dados de cadeias de
caracteres podem ser armazenados e usados diretamente, sem a necessidade de conversão, mas você precisa
converter os valores de outros objetos ViewData em tipos específicos quando extraí-los. Você pode usar
ViewData para passar dados de controladores para exibições e dentro das exibições, incluindo exibições parciais
e layouts.
A seguir, temos um exemplo que define valores para uma saudação e um endereço usando ViewData em uma
ação:
public IActionResult SomeAction()

{
ViewData["Greeting"] = "Hello";
ViewData["Address"] = new Address()
{
Name = "Steve",
Street = "123 Main St",
City = "Hudson",
State = "OH",
PostalCode = "44236"
};
return View();
}
Trabalhar com os dados em uma exibição:

@{
// Since Address isn't a string, it requires a cast.
var address = ViewData["Address"] as Address;
}
@ViewData["Greeting"] World!
<address>
@address.Name<br>
@address.Street<br>
@address.City, @address.State @address.PostalCode
</address>
Atributo ViewData
Outra abordagem que usa o ViewDataDictionary é ViewDataAttribute. As propriedades nos controladores ou
nos modelos da Página do Razor decoradas com [ViewData] têm seus valores armazenados e carregados do
dicionário.
No exemplo a seguir, o controlador Home contém uma propriedade Title decorada com [ViewData] .O
método About define o título para a exibição About:

{
[ViewData]

{
Title = "About Us";
ViewData["Message"] = "Your application description page.";
return View();
}
}
Na exibição About, acesse a propriedade Title como uma propriedade de modelo:
No layout, o título é lido a partir do dicionário ViewData:
<!DOCTYPE html>
<html lang="en">
<head>
<title>@ViewData["Title"] - WebApplication</title>
...
ViewBag
ViewBag é um objeto DynamicViewData que fornece acesso dinâmico aos objetos armazenados em ViewData .
Pode ser mais conveniente trabalhar com ViewBag , pois ele não requer uma conversão. O exemplo a seguir
mostra como usar ViewBag com o mesmo resultado que o uso de ViewData acima:
public IActionResult SomeAction()
{
ViewBag.Greeting = "Hello";
ViewBag.Address = new Address()
{
Name = "Steve",
Street = "123 Main St",
City = "Hudson",
State = "OH",
PostalCode = "44236"
};
return View();
}
@ViewBag.Greeting World!
<address>
@ViewBag.Address.Name<br>
@ViewBag.Address.Street<br>
@ViewBag.Address.City, @ViewBag.Address.State @ViewBag.Address.PostalCode
</address>
Usando ViewData e ViewBag simultaneamente

Como ViewDatae ViewBag fazem referência à mesma coleção ViewData subjacente, você pode usar ViewData e
ViewBag , além de misturá-los e combiná-los ao ler e gravar valores.
Defina o título usando ViewBag e a descrição usando ViewData na parte superior de uma exibição About.cshtml:
@{
Layout = "/Views/Shared/_Layout.cshtml";
ViewBag.Title = "About Contoso";
ViewData["Description"] = "Let us tell you about Contoso's philosophy and mission.";
}
Leia as propriedades, mas inverta o uso de ViewData e ViewBag . No arquivo _Layout.cshtml, obtenha o título
usando ViewData e a descrição usando ViewBag :
<!DOCTYPE html>
<html lang="en">
<head>
<title>@ViewData["Title"]</title>
<meta name="description" content="@ViewBag.Description">
...
Lembre-se de que cadeias de caracteres não exigem uma conversão para ViewData . Você pode usar
@ViewData["Title"] sem converter.
Usar ViewData e ViewBag ao mesmo tempo funciona, assim como misturar e combinar e leitura e a gravação
das propriedades. A seguinte marcação é renderizada:
<!DOCTYPE html>
<html lang="en">
<head>
<title>About Contoso</title>
<meta name="description" content="Let us tell you about Contoso's philosophy and mission.">
...
Resumo das diferenças entre ViewData e ViewBag

ViewBag não está disponível em páginas Razor.
ViewData
Deriva de ViewDataDictionary, de forma que tem propriedades de dicionário que podem ser úteis,
como ContainsKey , Add , Remove e Clear .
Chaves no dicionário são cadeias de caracteres, de forma que espaços em branco são permitidos.
Exemplo: ViewData["Some Key With Whitespace"]
Qualquer tipo diferente de string deve ser convertido na exibição para usar ViewData .
ViewBag
Deriva de DynamicViewData, de forma que permite a criação de propriedades dinâmicas usando a
notação de ponto ( @ViewBag.SomeKey = <value or object> ) e nenhuma conversão é necessária. A
sintaxe de ViewBag torna mais rápido adicioná-lo a controladores e exibições.
Mais simples de verificar quanto à presença de valores nulos. Exemplo: @ViewBag.Person?.Name
Quando usar ViewData ou ViewBag

ViewData e ViewBag são abordagens igualmente válidas para passar pequenas quantidades de dados entre
controladores e exibições. A escolha de qual delas usar é baseada na preferência. Você pode misturar e combinar
objetos ViewData e ViewBag , mas é mais fácil ler e manter o código quando uma abordagem é usada de
maneira consistente. Ambas as abordagens são resolvidas dinamicamente em tempo de execução e, portanto,
são propensas a causar erros de tempo de execução. Algumas equipes de desenvolvimento as evitam.
Exibições dinâmicas
Exibições que não declaram um tipo de modelo usando @model , mas que têm uma instância de modelo passada
a elas (por exemplo, return View(Address); ) podem referenciar as propriedades da instância dinamicamente:
<address>
@Model.Street<br>
@Model.City, @Model.State @Model.PostalCode<br>
<abbr title="Phone">P:</abbr> 425.555.0100
</address>
Esse recurso oferece flexibilidade, mas não oferece proteção de compilação ou IntelliSense. Se a propriedade
não existir, a geração da página da Web falhará em tempo de execução.
Mais recursos das exibições

Auxiliares de Marca facilitam a adição do comportamento do lado do servidor às marcações HTML existentes. O
uso de Auxiliares de marca evita a necessidade de escrever código personalizado ou auxiliares em suas exibições.
Auxiliares de marca são aplicados como atributos a elementos HTML e são ignorados por editores que não
podem processá-los. Isso permite editar e renderizar a marcação da exibição em várias ferramentas.
É possível gerar uma marcação HTML personalizada com muitos auxiliares HTML internos. Uma lógica de
interface do usuário mais complexa pode ser tratada por Componentes de exibição. Componentes de exibição
fornecem o mesmo SoC oferecido por controladores e exibições. Eles podem eliminar a necessidade de ações e
exibições que lidam com os dados usados por elementos comuns da interface do usuário.
Como muitos outros aspectos do ASP.NET Core, as exibições dão suporte à injeção de dependência, permitindo
que serviços sejam injetados em exibições.
Por Steve Smith, Luke Latham, Maher JENDOUBI, Rick Anderson e Scott Sauber
Uma exibição parcial é um arquivo de marcação Razor (.cshtml) que renderiza a saída HTML dentro da saída
processada de outro arquivo de marcação.
O termo exibição parcial é usado durante o desenvolvimento de um aplicativo MVC, no qual os arquivos de
marcação são chamados de exibições, ou de um aplicativo Razor Pages, no qual os arquivos de marcação são
chamados de páginas. Este tópico refere-se genericamente a exibições do MVC e a páginas do Razor Pages
como arquivos de marcação.
Quando usar exibições parciais

Exibições parciais são uma maneira eficaz de:
Dividir arquivos de marcação grandes em componentes menores.
Aproveitar a vantagem de trabalhar com cada parte isolada em uma exibição parcial em um arquivo de
marcação grande e complexo, composto por diversas partes lógicas. O código no arquivo de marcação
é gerenciável porque a marcação contém somente a estrutura de página geral e as referências a
exibições parciais.
Reduzir a duplicação de conteúdo de marcação comum em arquivos de marcação.
Quando os mesmos elementos de marcação são usados nos arquivos de marcação, uma exibição
parcial remove a duplicação de conteúdo de marcação em um arquivo de exibição parcial. Quando a
marcação é alterada na exibição parcial, ela atualiza a saída renderizada dos arquivos de marcação que
usam a exibição parcial.
As exibições parciais não podem ser usadas para manter os elementos de layout comuns. Os elementos de
layout comuns precisam ser especificados nos arquivos _Layout.cshtml.
Não use uma exibição parcial em que a lógica de renderização complexa ou a execução de código são
necessárias para renderizar a marcação. Em vez de uma exibição parcial, use um componente de exibição.
Declarar exibições parciais

Uma exibição parcial é um arquivo de marcação .cshtml mantido dentro da pasta Exibições (MVC ) ou Páginas
(Razor Pages).
No ASP.NET Core MVC, um ViewResult do controlador é capaz de retornar uma exibição ou uma exibição
parcial. Uma funcionalidade semelhante está planejada para o Razor Pages no ASP.NET Core 2.2. No Razor
Pages, um PageModel pode retornar um PartialViewResult. A referência e a renderização de exibições parciais
são descritas na seção Referenciar uma exibição parcial.
Ao contrário da exibição do MVC ou renderização de página, uma exibição parcial não executa
_ViewStart.cshtml. Para obter mais informações sobre _ViewStart.cshtml, consulte Layout no ASP.NET Core.
Nomes de arquivos de exibição parcial geralmente começam com um sublinhado ( _ ). Essa convenção de
nomenclatura não é obrigatória, mas ajuda a diferenciar visualmente as exibições parciais das exibições e das
páginas.
Uma exibição parcial é um arquivo de marcação .cshtml mantido dentro da pasta Exibições.
Um ViewResult do controlador é capaz de retornar uma exibição ou uma exibição parcial.
Ao contrário da renderização de exibição do MVC, uma exibição parcial não executa _ViewStart.cshtml. Para
obter mais informações sobre _ViewStart.cshtml, consulte Layout no ASP.NET Core.
Nomes de arquivos de exibição parcial geralmente começam com um sublinhado ( _ ). Essa convenção de
nomenclatura não é obrigatória, mas ajuda a diferenciar visualmente as exibições parciais das exibições.
Referenciar uma exibição parcial

Há várias maneiras de referenciar uma exibição parcial em um arquivo de marcação. É recomendável que os
aplicativos usem uma das seguintes abordagens de renderização assíncrona:
Auxiliar de marcação parcial
Auxiliar de HTML assíncrono
Há duas maneiras de referenciar uma exibição parcial em um arquivo de marcação:
Auxiliar de HTML síncrono
É recomendável que os aplicativos usem o Auxiliar de HTML assíncrono.
Auxiliar de marca parcial
O Auxiliar de Marca Parcial exige o ASP.NET Core 2.1 ou posterior.
O Auxiliar de Marca Parcial renderiza o conteúdo de forma assíncrona e usa uma sintaxe semelhante a HTML:
<partial name="_PartialName" />
Quando houver uma extensão de arquivo, o Auxiliar de Marca fará referência a uma exibição parcial que
precisa estar na mesma pasta que o arquivo de marcação que chama a exibição parcial:
<partial name="_PartialName.cshtml" />
O exemplo a seguir faz referência a uma exibição parcial da raiz do aplicativo. Caminhos que começam com
um til-barra ( ~/ ) ou uma barra ( / ) referem-se à raiz do aplicativo:
Páginas do Razor
<partial name="~/Pages/Folder/_PartialName.cshtml" />

<partial name="/Pages/Folder/_PartialName.cshtml" />
MVC
<partial name="~/Views/Folder/_PartialName.cshtml" />

<partial name="/Views/Folder/_PartialName.cshtml" />
O exemplo a seguir faz referência a uma exibição parcial com um caminho relativo:
<partial name="../Account/_PartialName.cshtml" />
Para obter mais informações, consulte Auxiliar de marca parcial no ASP.NET Core.
Auxiliar HTML assíncrono
Ao usar um Auxiliar HTML, a melhor prática é usar PartialAsync. PartialAsync retorna um tipo IHtmlContent
encapsulado em um Task<TResult>. O método é referenciado prefixando a chamada em espera com um
caractere @ :
@await Html.PartialAsync("_PartialName")
Quando houver a extensão de arquivo, o Auxiliar de HTML fará referência a uma exibição parcial que precisa
estar na mesma pasta que o arquivo de marcação que chama a exibição parcial:
@await Html.PartialAsync("_PartialName.cshtml")
O exemplo a seguir faz referência a uma exibição parcial da raiz do aplicativo. Caminhos que começam com
um til-barra ( ~/ ) ou uma barra ( / ) referem-se à raiz do aplicativo:
Páginas do Razor
@await Html.PartialAsync("~/Pages/Folder/_PartialName.cshtml")
@await Html.PartialAsync("/Pages/Folder/_PartialName.cshtml")
MVC
@await Html.PartialAsync("~/Views/Folder/_PartialName.cshtml")
@await Html.PartialAsync("/Views/Folder/_PartialName.cshtml")
O exemplo a seguir faz referência a uma exibição parcial com um caminho relativo:
@await Html.PartialAsync("../Account/_LoginPartial.cshtml")
Como alternativa, é possível renderizar uma exibição parcial com RenderPartialAsync. Esse método não
retorna um IHtmlContent. Ele transmite a saída renderizada diretamente para a resposta. Como o método não
retorna nenhum resultado, ele precisa ser chamado dentro de um bloco de código Razor:
@{
await Html.RenderPartialAsync("_AuthorPartial");
}
Como RenderPartialAsync transmite conteúdo renderizado, ele apresenta melhor desempenho em alguns
cenários. Em situações cruciais para o desempenho, submeta a página a benchmark usando ambas as
abordagens e use aquela que gera uma resposta mais rápida.
Partial e RenderPartial são os equivalentes síncronos de PartialAsync e RenderPartialAsync , respectivamente.
Os equivalentes síncronos não são recomendados porque há cenários em que eles realizam deadlock. Os
métodos síncronos estão programados para serem removidos em uma versão futura.
IMPORTANT
Se for necessário executar código, use um componente de exibição em vez de uma exibição parcial.
Chamar Partial ou RenderPartial resulta em um aviso do analisador do Visual Studio. Por exemplo, a
presença de Partial produz a seguinte mensagem de aviso:
Uso de IHtmlHelper.Partial pode resultar em deadlocks de aplicativo. Considere usar o Auxiliar de Marca
<parcial> ou IHtmlHelper.PartialAsync.
Substitua as chamadas para @Html.Partial por @await Html.PartialAsync ou o Auxiliar de Marca Parcial. Para
obter mais informações sobre a migração do auxiliar de marca parcial, consulte Migrar de um auxiliar HTML.
Descoberta de exibição parcial

Quando uma exibição parcial é referenciada pelo nome sem uma extensão de arquivo, os seguintes locais são
pesquisados na ordem indicada:
Páginas do Razor
1. Pasta da página em execução no momento
2. Grafo do diretório acima da pasta da página
3. /Shared
4. /Pages/Shared
5. /Views/Shared
MVC
1. /Areas/<Area-Name>/Views/<Controller-Name>
2. /Areas/<Area-Name>/Views/Shared
3. /Views/Shared
4. /Pages/Shared
1. /Areas/<Area-Name>/Views/<Controller-Name>
2. /Areas/<Area-Name>/Views/Shared
3. /Views/Shared
As convenções a seguir se aplicam à descoberta de exibição parcial:

Diferentes exibições parciais com o mesmo nome de arquivo são permitidos quando as exibições parciais
estão em pastas diferentes.
Ao referenciar uma exibição parcial pelo nome sem uma extensão de arquivo e a exibição parcial está
presente na pasta do chamador e na pasta Compartilhada, a exibição parcial na pasta do chamador fornece
a exibição parcial. Se a exibição parcial não existir na pasta do chamador, ela será fornecida pela pasta
Compartilhada. Exibições parciais na pasta Compartilhada são chamadas de exibições parciais
compartilhadas ou exibições parciais padrão.
Exibições parciais podem ser encadeadas—uma exibição parcial pode chamar outra se uma referência
circular não tiver sido formada por chamadas. Caminhos relativos sempre são relativos ao arquivo atual,
não à raiz ou ao pai do arquivo.
NOTE
Um Razor section definido em uma exibição parcial é invisível para arquivos de marcação pai. A section só é visível
para a exibição parcial na qual ela está definida.
Acessar dados de exibições parciais

Quando uma exibição parcial é instanciada, ela recebe uma cópia do dicionário ViewData do pai. As
atualizações feitas nos dados dentro da exibição parcial não são persistidas na exibição pai. Alterações a
ViewData em uma exibição parcial são perdidas quando a exibição parcial retorna.
O exemplo a seguir demonstra como passar uma instância de ViewDataDictionary para uma exibição parcial:
@await Html.PartialAsync("_PartialName", customViewData)
Você pode passar um modelo para uma exibição parcial. O modelo pode ser um objeto personalizado. Você
pode passar um modelo com PartialAsync (renderiza um bloco de conteúdo para o chamador) ou
RenderPartialAsync (transmite o conteúdo para a saída):
@await Html.PartialAsync("_PartialName", model)
Páginas do Razor
A marcação a seguir no aplicativo de exemplo é da página Pages/ArticlesRP/ReadRP.cshtml. A página contém
duas exibições parciais. A segunda exibição parcial passa um modelo e ViewData para a exibição parcial. A
sobrecarga do construtor ViewDataDictionary é usada para passar um novo dicionário ViewData , retendo
ainda o dicionário ViewData existente.
@model ReadRPModel
<h2>@Model.Article.Title</h2>
@* Pass the author's name to Pages\Shared\_AuthorPartialRP.cshtml *@
@await Html.PartialAsync("../Shared/_AuthorPartialRP", Model.Article.AuthorName)
@Model.Article.PublicationDate
@* Loop over the Sections and pass in a section and additional ViewData to
the strongly typed Pages\ArticlesRP\_ArticleSectionRP.cshtml partial view. *@
@{
var index = 0;
@foreach (var section in Model.Article.Sections)

{
@await Html.PartialAsync("_ArticleSectionRP", section,
new ViewDataDictionary(ViewData)
{
{ "index", index }
})
index++;
}
}
Pages/Shared/_AuthorPartialRP.cshtml é a primeira exibição parcial referenciada pelo arquivo de marcação

ReadRP.cshtml:
@model string
<div>
<h3>@Model</h3>
This partial view from /Pages/Shared/_AuthorPartialRP.cshtml.
</div>
Pages/ArticlesRP/_ArticleSectionRP.cshtml é a segunda exibição parcial referenciada pelo arquivo de marcação

ReadRP.cshtml:
@using PartialViewsSample.ViewModels
@model ArticleSection
<h3>@Model.Title Index: @ViewData["index"]</h3>

<div>
@Model.Content
</div>
MVC
A marcação a seguir no aplicativo de exemplo mostra a exibição Views/Articles/Read.cshtml. A exibição
contém duas exibições parciais. A segunda exibição parcial passa um modelo e ViewData para a exibição
parcial. A sobrecarga do construtor ViewDataDictionary é usada para passar um novo dicionário ViewData ,
retendo ainda o dicionário ViewData existente.
@model PartialViewsSample.ViewModels.Article
@* Pass the author's name to Views\Shared\_AuthorPartial.cshtml *@
@await Html.PartialAsync("_AuthorPartial", Model.AuthorName)
@Model.PublicationDate
@* Loop over the Sections and pass in a section and additional ViewData to
the strongly typed Views\Articles\_ArticleSection.cshtml partial view. *@
@{
var index = 0;
@foreach (var section in Model.Sections)

{
@await Html.PartialAsync("_ArticleSection", section,
new ViewDataDictionary(ViewData)
{
{ "index", index }
})
index++;
}
}
Views/Shared/_AuthorPartial.cshtml é a primeira exibição parcial referenciada pelo arquivo de marcação

ReadRP.cshtml:
@model string
<div>
<h3>@Model</h3>
This partial view from /Views/Shared/_AuthorPartial.cshtml.
</div>
Views/Articles/_ArticleSection.cshtml é a segunda exibição parcial referenciada pelo arquivo de marcação

Read.cshtml:
@using PartialViewsSample.ViewModels
@model ArticleSection
<h3>@Model.Title Index: @ViewData["index"]</h3>

<div>
@Model.Content
</div>
No tempo de execução, as parciais são renderizadas para a saída renderizada do arquivo de marcação pai que,
por sua vez, é renderizada dentro do _Layout.cshtml compartilhado. A primeira exibição parcial renderiza a
data de publicação e o nome do autor do artigo:
Abraham Lincoln
Esta exibição parcial do <caminho do arquivo de exibição parcial compartilhada>. 19/11/1863 12:00:00
AM
A segunda exibição parcial renderiza as seções do artigo:
Índice da seção um: 0

Pontuação de quatro e há sete anos...
Índice da seção dois: 1
Agora estamos envolvidos em uma grande guerra civil, testando...
Índice da seção três: 2
Mas, em um sentido mais amplo, não podemos dedicar...
Recursos adicionais
Auxiliar de marca parcial no ASP.NET Core
Componentes de exibição no ASP.NET Core
Áreas no ASP.NET Core
Tratar solicitações com controladores no ASP.NET
Core MVC
Por Steve Smith e Scott Addie

Controladores, ações e resultados da ação são uma parte fundamental de como os desenvolvedores criam
aplicativos usando o ASP.NET Core MVC.
O que é um controlador?
Um controlador é usado para definir e agrupar um conjunto de ações. Uma ação (ou método de ação) é um
método em um controlador que manipula solicitações. Os controladores agrupam ações semelhantes de forma
lógica. Essa agregação de ações permite que conjuntos de regras comuns, como roteamento, cache e autorização,
sejam aplicados em conjunto. As solicitações são mapeadas para ações por meio de roteamento.
Por convenção, as classes do controlador:
Residem na pasta Controllers no nível raiz do projeto
Herdam de Microsoft.AspNetCore.Mvc.Controller
Um controlador é uma classe que pode ser instanciada, em que, pelo menos, uma das seguintes condições é
verdadeira:
O nome da classe tem "Controller" como sufixo
A classe herda de uma classe cujo nome tem "Controller" como sufixo
A classe está decorada com o atributo [Controller]
Uma classe de controlador não deve ter um atributo [NonController] associado.
Os controladores devem seguir o Princípio de Dependências Explícitas. Há duas abordagens para implementar
esse princípio. Se várias ações do controlador exigem o mesmo serviço, considere o uso da injeção de construtor
para solicitar essas dependências. Se o serviço é necessário para um único método de ação, considere o uso da
Injeção de Ação para solicitar a dependência.
Dentro do padrão Model-View -Controller, um controlador é responsável pelo processamento inicial da
solicitação e criação de uma instância do modelo. Em geral, as decisões de negócios devem ser tomadas dentro
do modelo.
O controlador usa o resultado do processamento do modelo (se houver) e retorna a exibição correta e seus
dados da exibição associada ou o resultado da chamada à API. Saiba mais em Visão geral do ASP.NET Core
MVC e em Introdução ao ASP.NET Core MVC e ao Visual Studio.
O controlador é uma abstração no nível da interface do usuário. Suas responsabilidades são garantir que os
dados de solicitação sejam válidos e escolher qual exibição (ou resultado de uma API) deve ser retornada. Em
aplicativos bem fatorados, ele não inclui diretamente o acesso a dados ou a lógica de negócios. Em vez disso, o
controlador delega essas responsabilidades a serviços.
Definindo ações
Métodos públicos em um controlador, exceto aqueles decorados com o atributo [NonAction] , são ações.
Parâmetros em ações são associados aos dados de solicitação e validados usando a associação de modelos. A
validação de modelo ocorre em tudo o que é associado ao modelo. O valor da propriedade ModelState.IsValid
indica se a associação de modelos e a validação foram bem-sucedidas.
Métodos de ação devem conter uma lógica para mapear uma solicitação para um interesse de negócios.
Normalmente, interesses de negócios devem ser representados como serviços acessados pelo controlador por
meio da injeção de dependência. Em seguida, as ações mapeiam o resultado da ação de negócios para um estado
do aplicativo.
As ações podem retornar qualquer coisa, mas frequentemente retornam uma instância de IActionResult (ou
Task<IActionResult> para métodos assíncronos) que produz uma resposta. O método de ação é responsável por
escolher o tipo de resposta. O resultado da ação é responsável pela resposta.
Métodos auxiliares do controlador
Os controladores geralmente herdam de Controller, embora isso não seja necessário. A derivação de Controller
fornece acesso a três categorias de métodos auxiliares:
1. Métodos que resultam em um corpo de resposta vazio
Nenhum cabeçalho de resposta HTTP Content-Type é incluído, pois o corpo da resposta não tem nenhum
conteúdo a ser descrito.
Há dois tipos de resultado nessa categoria: Redirecionamento e Código de Status HTTP.
Código de Status HTTP
Esse tipo retorna um código de status HTTP. Alguns métodos auxiliares desse tipo são BadRequest ,
NotFound e Ok . Por exemplo, return BadRequest(); produz um código de status 400 quando executado.
Quando métodos como BadRequest , NotFound e Ok estão sobrecarregados, eles deixam de se qualificar
como respondentes do Código de Status HTTP, pois a negociação de conteúdo está em andamento.
Redirecionamento
Esse tipo retorna um redirecionamento para uma ação ou um destino (usando Redirect , LocalRedirect ,
RedirectToAction ou RedirectToRoute ). Por exemplo,
return RedirectToAction("Complete", new {id = 123}); redireciona para Complete , passando um objeto
anônimo.
O tipo de resultado do Redirecionamento é diferente do tipo do Código de Status HTTP, principalmente
na adição de um cabeçalho de resposta HTTP Location .
2. Métodos que resultam em um corpo de resposta não vazio com um tipo de conteúdo predefinido
A maioria dos métodos auxiliares desta categoria inclui uma propriedade ContentType , permitindo que você
defina o cabeçalho de resposta Content-Type para descrever o corpo da resposta.
Há dois tipos de resultado nessa categoria: Exibição e Resposta Formatada.
Exibir
Esse tipo retorna uma exibição que usa um modelo para renderizar HTML. Por exemplo,
return View(customer); passa um modelo para a exibição para associação de dados.
Resposta Formatada
Esse tipo retorna JSON ou um formato de troca de dados semelhante para representar um objeto de uma
maneira específica. Por exemplo, return Json(customer); serializa o objeto fornecido no formato JSON.
Outros métodos comuns desse tipo incluem File , e VirtualFile . Por exemplo,
PhysicalFile
return PhysicalFile(customerFilePath, "text/xml"); retorna um arquivo XML descrito por um valor do
cabeçalho de resposta Content-Type igual a "text/xml".
3. Métodos que resultam em um corpo de resposta não vazio formatado em um tipo de conteúdo negociado com o cliente
Essa categoria é mais conhecida como Negociação de Conteúdo. A Negociação de conteúdo aplica-se sempre
que uma ação retorna um tipo ObjectResult ou algo diferente de uma implementação IActionResult. Uma ação
que retorna uma implementação não IActionResult (por exemplo, object ) também retorna uma Resposta
Formatada.
Alguns métodos auxiliares desse tipo incluem BadRequest , CreatedAtRoute e Ok . Exemplos desses métodos
incluem return BadRequest(modelState); , return CreatedAtRoute("routename", values, newobject); e
return Ok(value); , respectivamente. Observe que BadRequest e Ok fazem a negociação de conteúdo apenas
quando um valor é passado; sem que um valor seja passado, eles atuam como tipos de resultado do Código de
Status HTTP. Por outro lado, o método CreatedAtRoute sempre faz a negociação de conteúdo, pois todas as suas
sobrecargas exigem que um valor seja passado.
Interesses paralelos
Normalmente, os aplicativos compartilham partes de seu fluxo de trabalho. Exemplos incluem um aplicativo que
exige autenticação para acessar o carrinho de compras ou um aplicativo que armazena dados em cache em
algumas páginas. Para executar a lógica antes ou depois de um método de ação, use um filtro. O uso de Filtros
em interesses paralelos pode reduzir a duplicação, possibilitando que elas sigam o princípio DRY (Don't Repeat
Yourself).
A maioria dos atributos de filtro, como [Authorize] , pode ser aplicada no nível do controlador ou da ação,
dependendo do nível desejado de granularidade.
O tratamento de erro e o cache de resposta costumam ser interesses paralelos:
Tratar erros
Cache de resposta
Muitos interesses paralelos podem ser abordados com filtros ou um middleware personalizado.
Roteamento para ações do controlador no
ASP.NET Core
Por Ryan Nowak e Rick Anderson

O ASP.NET Core MVC usa o middleware de Roteamento para fazer as correspondências das URLs de
solicitações de entrada e mapeá-las para ações. As rotas são definidas em atributos ou no código de
inicialização. Elas descrevem como deve ser feita a correspondência entre caminhos de URL e ações. As
rotas também são usadas para gerar URLs (para links) enviados em resposta.
As ações são roteadas convencionalmente ou segundo os atributos. Colocar uma rota no controlador ou
na ação faz com que ela seja roteada segundo o atributo. Para obter mais informações, consulte
Roteamento misto.
Este documento explicará as interações entre o MVC e o roteamento e como aplicativos MVC comuns
usam recursos de roteamento. Consulte Roteamento para obter detalhes sobre o roteamento avançado.
Configurando o middleware de Roteamento

No método Configurar, você poderá ver código semelhante a:
{
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});
Dentro da chamada para UseMvc , MapRoute é usado para criar uma única rota, que chamaremos de rota
default . A maioria dos aplicativos MVC usa uma rota com um modelo semelhante à rota default .
O modelo de rota "{controller=Home}/{action=Index}/{id?}" pode corresponder a um caminho de URL

como /Products/Details/5 e extrai os valores de rota
{ controller = Products, action = Details, id = 5 } gerando tokens para o caminho. O MVC tentará
localizar um controlador chamado ProductsController e executar a ação Details :

{
public IActionResult Details(int id) { ... }
}
Observe que, neste exemplo, o model binding usaria o valor de id = 5 para definir o parâmetro id
como 5 ao invocar essa ação. Consulte Model binding para obter mais detalhes.
Usando a rota default :
O modelo da rota:
{controller=Home} define Home como o controller padrão
{action=Index} define Index como o action padrão
{id?} define id como opcional
Parâmetros de rota opcionais e padrão não precisam estar presentes no caminho da URL para que haja
uma correspondência. Consulte Referência de modelo de rota para obter uma descrição detalhada da
sintaxe do modelo de rota.
"{controller=Home}/{action=Index}/{id?}" pode corresponder ao caminho da URL / e produzirá os
valores de rota { controller = Home, action = Index } . Os valores de controller e action usam os
valores padrão, id não produz um valor, uma vez que não há nenhum segmento correspondente no
caminho da URL. O MVC usaria esses valores de rota para selecionar a ação HomeController e Index :

{
public IActionResult Index() { ... }
}
Usando essa definição de controlador e modelo de rota, a ação HomeController.Index seria executada
para qualquer um dos caminhos de URL a seguir:
/Home/Index/17
/Home/Index
/Home
O método de conveniência UseMvcWithDefaultRoute :
Pode ser usado para substituir:
{
});
UseMvc e UseMvcWithDefaultRoute adicionam uma instância de RouterMiddleware ao pipeline de

middleware. O MVC não interage diretamente com o middleware e usa o roteamento para tratar das
solicitações. O MVC é conectado às rotas por meio de uma instância de MvcRouteHandler . O código
dentro de UseMvc é semelhante ao seguinte:
var routes = new RouteBuilder(app);
// Add connection to MVC, will be hooked up by calls to MapRoute.

routes.DefaultHandler = new MvcRouteHandler(...);
// Execute callback to register routes.

// routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
// Create route collection and add the middleware.

app.UseRouter(routes.Build());
UseMvc não define diretamente nenhuma rota, ele adiciona um espaço reservado à coleção de rotas para
a rota attribute . A sobrecarga UseMvc(Action<IRouteBuilder>) permite adicionar suas próprias rotas e
também dá suporte ao roteamento de atributos. UseMvc e todas as suas variações adicionam um espaço
reservado à rota do atributo – o roteamento de atributos sempre está disponível, independentemente de
como você configura UseMvc . UseMvcWithDefaultRoute define uma rota padrão e dá suporte ao
roteamento de atributos. A seção Roteamento de atributos inclui mais detalhes sobre o roteamento de
atributos.
Roteamento convencional
A rota default :
é um exemplo de roteamento convencional. Nós chamamos esse estilo de roteamento convencional

porque ele estabelece uma convenção para caminhos de URL:
o primeiro segmento do caminho é mapeado para o nome do controlador,
o segundo é mapeado para o nome da ação,
o terceiro segmento é usado para uma id opcional usado para mapear para uma entidade de
modelo.
Usando essa rota , o caminho da URL /Products/List é mapeado para a ação
default
ProductsController.List e /Blog/Article/17 é mapeado para BlogController.Article . Esse mapeamento
é baseado somente nos nomes do controlador e da ação e não é baseado em namespaces, locais de
arquivos de origem ou parâmetros de método.
TIP
Usar o roteamento convencional com a rota padrão permite compilar o aplicativo rapidamente sem precisar criar
um novo padrão de URL para cada ação que você definir. Para um aplicativo com ações de estilo CRUD, ter
consistência para as URLs em seus controladores pode ajudar a simplificar seu código e a tornar sua interface do
usuário mais previsível.
WARNING
O id é definido como opcional pelo modelo de rota, o que significa que suas ações podem ser executadas sem a
ID fornecida como parte da URL. Normalmente, o que acontecerá se id for omitido da URL é que ele será
definido como 0 pelo model binding e, dessa forma, não será encontrada no banco de dados nenhuma entidade
correspondente a id == 0 . O roteamento de atributos pode lhe proporcionar controle refinado para tornar a ID
obrigatória para algumas ações e não para outras. Por convenção, a documentação incluirá parâmetros opcionais,
como id , quando for provável que eles apareçam no uso correto.
Várias rotas
É possível adicionar várias rotas dentro de UseMvc adicionando mais chamadas para MapRoute . Fazer isso
permite que você defina várias convenções ou que adicione rotas convencionais dedicadas a uma ação
específica, como:
{
routes.MapRoute("blog", "blog/{*article}",
defaults: new { controller = "Blog", action = "Article" });
});
A rota blog aqui é uma rota convencional dedicada, o que significa que ela usa o sistema de roteamento
convencional, mas é dedicada a uma ação específica. Como controller e action não aparecem no
modelo de rota como parâmetros, eles só podem ter os valores padrão e, portanto, essa rota sempre será
mapeada para a ação BlogController.Article .
As rotas na coleção de rotas são ordenadas e serão processadas na ordem em que forem adicionadas.
Portanto, neste exemplo, a rota blog será tentada antes da rota default .
NOTE
Rotas convencionais dedicadas geralmente usam parâmetros de rota que capturam tudo, como {*article} ,
para capturar a parte restante do caminho da URL. Isso pode fazer com que uma rota fique "muito ambiciosa", ou
seja, que faça a correspondência com URLs que deveriam ser correspondidas com outras rotas. Coloque as rotas
"ambiciosas" mais adiante na tabela de rotas para solucionar esse problema.
Fallback
Como parte do processamento de solicitações, o MVC verificará se o valores das rotas podem ser usados
para encontrar um controlador e uma ação em seu aplicativo. Se os valores das rotas não
corresponderem a uma ação, a rota não será considerada correspondente e a próxima rota será tentada.
Isso é chamado de fallback e sua finalidade é simplificar casos em que rotas convencionais se sobrepõem.
Desambiguação de ações
Quando duas ações correspondem por meio do roteamento, o MVC precisa resolver a ambiguidade para
escolher a "melhor" candidata ou lançar uma exceção. Por exemplo:

{
public IActionResult Edit(int id) { ... }
[HttpPost]
public IActionResult Edit(int id, Product product) { ... }
}
Esse controlador define duas ações que fariam a correspondência entre caminho da URL
/Products/Edit/17 e a os dados da rota { controller = Products, action = Edit, id = 17 } . Este é um
padrão comum para controladores MVC em que Edit(int) mostra um formulário para editar um
produto e Edit(int, Product) processa o formulário postado. Para que isso seja possível, o MVC precisa
escolher Edit(int, Product) quando a solicitação é um POST HTTP e Edit(int) quando o verbo HTTP é
qualquer outra coisa.
O HttpPostAttribute ( [HttpPost] ) é uma implementação de IActionConstraint que só permite que a
ação seja selecionada quando o verbo HTTP é POST . A presença de um IActionConstraint faz do
Edit(int, Product) uma "melhor" correspondência do que Edit(int) , portanto, Edit(int, Product)
será tentado primeiro.
Você só precisará gravar implementações personalizadas de IActionConstraint em cenários
especializados, mas é importante compreender a função de atributos como HttpPostAttribute – atributos
semelhantes são definidos para outros verbos HTTP. No roteamento convencional, é comum que ações
usem o mesmo nome de ação quando fazem parte de um fluxo de trabalho de show form -> submit form .
A conveniência desse padrão ficará mais aparente após você revisar a seção Noções básicas sobre
IActionConstraint.
Se várias rotas corresponderem e o MVC não puder encontrar uma rota "melhor", ele gerará um
AmbiguousActionException .
Nomes de rotas
As cadeias de caracteres "blog" e "default" nos exemplos a seguir são nomes de rotas:
{
});
Os nomes de rotas dão a uma rota um nome lógico, de modo que a rota nomeada possa ser usada para
geração de URL. Isso simplifica muito a criação de URLs quando a ordenação de rotas poderia complicá-
la. Nomes de rotas devem ser exclusivos no nível do aplicativo.
Os nomes de rotas não têm impacto sobre a correspondência de URLs ou o tratamento de solicitações;
eles são usados apenas para a geração de URLs. Roteamento tem informações mais detalhadas sobre
geração de URLs, incluindo a geração de URLs em auxiliares específicos do MVC.
Roteamento de atributo
O roteamento de atributo usa um conjunto de atributos para mapear ações diretamente para modelos de
rota. No exemplo a seguir, app.UseMvc(); é usado no método Configure e nenhuma rota é passada. O
HomeController corresponderá a um conjunto de URLs semelhantes ao que a rota padrão
{controller=Home}/{action=Index}/{id?} corresponderia:

{
[Route("")]
[Route("Home")]
[Route("Home/Index")]
{
return View();
}
[Route("Home/About")]
{
return View();
}
[Route("Home/Contact")]
{
return View();
}
}
A ação HomeController.Index() será executada para qualquer um dos caminhos de URL / , /Home ou
/Home/Index .
NOTE
Este exemplo destaca uma diferença importante de programação entre o roteamento de atributo e o roteamento
convencional. O roteamento de atributo requer mais entradas para especificar uma rota; a rota padrão
convencional manipula as rotas de forma mais sucinta. No entanto, o roteamento de atributo permite (e exige) o
controle preciso de quais modelos de rota se aplicam a cada ação.
Com o roteamento de atributo, o nome do controlador e os nomes de ação não desempenham nenhuma
função quanto a qual ação é selecionada. Este exemplo corresponderá as mesmas URLs que o exemplo
anterior.
public class MyDemoController : Controller

{
[Route("")]
[Route("Home")]
[Route("Home/Index")]
public IActionResult MyIndex()
{
return View("Index");
}
[Route("Home/About")]
public IActionResult MyAbout()
{
return View("About");
}
[Route("Home/Contact")]
public IActionResult MyContact()
{
return View("Contact");
}
}
NOTE
Os modelos de rota acima não definem parâmetros de rota para action , area e controller . Na verdade,
esses parâmetros de rota não são permitidos em rotas de atributo. Uma vez que o modelo de rota já está
associado a uma ação, não faria sentido analisar o nome da ação da URL.
Roteamento de atributo com atributos Http[Verb]

O roteamento de atributo também pode usar atributos Http[Verb] , como HttpPostAttribute . Todos
esses atributos podem aceitar um modelo de rota. Este exemplo mostra duas ações que correspondem ao
mesmo modelo de rota:
[HttpGet("/products")]
public IActionResult ListProducts()
{
// ...
}
[HttpPost("/products")]
public IActionResult CreateProduct(...)
{
// ...
}
Para um caminho de URL como /products , a ação ProductsApi.ListProducts será executada quando o
verbo HTTP for GET e ProductsApi.CreateProduct será executado quando o verbo HTTP for POST .
Primeiro, o roteamento de atributo faz a correspondência da URL com o conjunto de modelos de rota
definidos por atributos de rota. Quando um modelo de rota for correspondente, restrições de
IActionConstraint serão aplicadas para determinar quais ações podem ser executadas.
TIP
Ao compilar uma API REST, é raro que você queira usar [Route(...)] em um método de ação. É melhor usar o
Http*Verb*Attributes mais específico para ser preciso quanto ao que tem suporte de sua API. Espera-se que
clientes de APIs REST saibam quais caminhos e verbos HTTP são mapeados para operações lógicas específicas.
Como uma rota de atributo se aplica a uma ação específica, é fácil fazer com que parâmetros sejam
obrigatórios como parte da definição do modelo de rota. Neste exemplo, id é obrigatório como parte do
caminho da URL.
public class ProductsApiController : Controller

{
[HttpGet("/products/{id}", Name = "Products_List")]
public IActionResult GetProduct(int id) { ... }
}
A ação ProductsApi.GetProduct(int) será executada para um caminho de URL como /products/3 , mas
não para um caminho de URL como /products . Consulte Roteamento para obter uma descrição
completa de modelos de rota e as opções relacionadas.
Nome da rota
O código a seguir define um nome da rota como Products_List :

{
[HttpGet("/products/{id}", Name = "Products_List")]
public IActionResult GetProduct(int id) { ... }
}
Nomes de rota podem ser usados para gerar uma URL com base em uma rota específica. Nomes de rota
não têm impacto sobre o comportamento de correspondência da URL e são usados somente para
geração de URLs. Nomes de rotas devem ser exclusivos no nível do aplicativo.
NOTE
Compare isso com a rota padrão convencional, que define o parâmetro id como opcional ( {id?} ). Essa
capacidade de especificar APIs de forma específica tem vantagens, como permitir que /products e /products/5
sejam expedidos para ações diferentes.
Combinando rotas
Para tornar o roteamento de atributo menos repetitivo, os atributos de rota no controlador são
combinados com atributos de rota nas ações individuais. Modelos de rota definidos no controlador
precedem modelos de rota nas ações. Colocar um atributo de rota no controlador foz com que todas as
ações no controlador usem o roteamento de atributo.
[Route("products")]
{
[HttpGet]
public IActionResult ListProducts() { ... }
[HttpGet("{id}")]
public ActionResult GetProduct(int id) { ... }
}
Neste exemplo, o caminho de URL /products pode corresponder a ProductsApi.ListProducts e o

caminho de URL /products/5 pode corresponder a ProductsApi.GetProduct(int) . Essas duas ações são
correspondentes somente ao GET HTTP porque são decoradas com o HttpGetAttribute .
Modelos de rota aplicados a uma ação que começam com um / não são combinados com modelos de
rota aplicados ao controlador. Este exemplo corresponde a um conjunto de caminhos de URL semelhante
à rota padrão.
[Route("Home")]
{
[Route("")] // Combines to define the route template "Home"
[Route("Index")] // Combines to define the route template "Home/Index"
[Route("/")] // Doesn't combine, defines the route template ""
{
ViewData["Message"] = "Home index";
var url = Url.Action("Index", "Home");
ViewData["Message"] = "Home index" + "var url = Url.Action; = " + url;
return View();
}
[Route("About")] // Combines to define the route template "Home/About"

{
return View();
}
}
Ordenando rotas de atributos

Diferente de rotas convencionais, que são executadas em uma ordem definida, o roteamento de atributo
cria uma árvore e faz a correspondência de todas as rotas simultaneamente. O comportamento é como se
as entradas de rota fossem colocadas em uma ordem ideal; as rotas mais específicas têm uma chance de
ser executadas antes das rotas mais gerais.
Por exemplo, uma rota como blog/search/{topic} é mais específica que uma rota como blog/{*article} .
Em termos da lógica, a rota blog/search/{topic} é "executada" primeiro, por padrão, porque essa é a
única ordem que faz sentido. Usando o roteamento convencional, o desenvolvedor é responsável por
colocar as rotas na ordem desejada.
Rotas de atributos podem configurar uma ordem, usando a propriedade Order de todos os atributos de
rota fornecidos pela estrutura. As rotas são processadas segundo uma classificação crescente da
propriedade Order . A ordem padrão é 0 . Uma rota definida usando Order = -1 será executada antes
de rotas que não definem uma ordem. Uma rota definida usando Order = 1 será executada após a
ordem das rotas padrão.
TIP
Evite depender de Order . Se o seu espaço de URL exigir valores de ordem explícita para fazer o roteamento
corretamente, provavelmente ele também será confuso para os clientes. De modo geral, o roteamento de atributos
selecionará a rota correta com a correspondência de URL. Se a ordem padrão usada para a geração de URL não
estiver funcionando, usar o nome da rota como uma substituição geralmente será mais simples do que aplicar a
propriedade Order .
Roteamento do Razor Pages e do controlador do MVC compartilham uma implementação. Informações

sobre a ordem de rota nos tópicos do Razor Pages estão disponíveis em Convenções de rota e aplicativo
do Razor Pages: ordem de rota.
Substituição de token em modelos de rota ([controlador] [ação]

[área])
Para conveniência, as rotas de atributo dão suporte à substituição de token colocando um token entre
chaves quadradas ( [ , ] ). Os tokens [action] , [area] e [controller] são substituídos pelos valores
do nome da ação, do nome da área e do nome do controlador da ação em que a rota é definida. No
exemplo a seguir, as ações correspondem a caminhos de URL conforme descrito nos comentários:
[Route("[controller]/[action]")]
{
[HttpGet] // Matches '/Products/List'
public IActionResult List() {
// ...
}
[HttpGet("{id}")] // Matches '/Products/Edit/{id}'

public IActionResult Edit(int id) {
// ...
}
}
A substituição de token ocorre como a última etapa da criação das rotas de atributo. O exemplo acima se
comportará da mesma forma que o código a seguir:

{
[HttpGet("[controller]/[action]")] // Matches '/Products/List'
public IActionResult List() {
// ...
}
[HttpGet("[controller]/[action]/{id}")] // Matches '/Products/Edit/{id}'

public IActionResult Edit(int id) {
// ...
}
}
Rotas de atributo também podem ser combinadas com herança. Isso é especialmente eficiente em
combinação com a substituição de token.
public abstract class MyBaseController : Controller { ... }
public class ProductsController : MyBaseController

{
[HttpGet] // Matches '/api/Products'
public IActionResult List() { ... }
[HttpPut("{id}")] // Matches '/api/Products/{id}'

public IActionResult Edit(int id) { ... }
}
A substituição de token também se aplica a nomes de rota definidos por rotas de atributo.
[Route("[controller]/[action]", Name="[controller]_[action]")] gera um nome de rota exclusivo para
cada ação.
Para corresponder ao delimitador de substituição de token literal [ ou ] , faça seu escape repetindo o
caractere ( [[ ou ]] ).
Usar um transformador de parâmetro para personalizar a substituição de token
A substituição do token pode ser personalizada usando um transformador de parâmetro. Um
transformador de parâmetro implementa IOutboundParameterTransformer e transforma o valor dos
parâmetros. Por exemplo, um transformador de parâmetro SlugifyParameterTransformer personalizado
muda o valor de rota SubscriptionManagement para subscription-management .
O RouteTokenTransformerConvention é uma convenção de modelo de aplicativo que:
Aplica um transformador de parâmetro a todas as rotas de atributo em um aplicativo.
Personaliza os valores de token de rota de atributo conforme eles são substituídos.
public class SubscriptionManagementController : Controller

{
[HttpGet("[controller]/[action]")] // Matches '/subscription-management/list-all'
public IActionResult ListAll() { ... }
}
O RouteTokenTransformerConvention está registrado como uma opção em ConfigureServices .

{
{
options.Conventions.Add(new RouteTokenTransformerConvention(
new SlugifyParameterTransformer()));
});
}
public class SlugifyParameterTransformer : IOutboundParameterTransformer

{
public string TransformOutbound(object value)
{
if (value == null) { return null; }
// Slugify value
return Regex.Replace(value.ToString(), "([a-z])([A-Z])", "$1-$2").ToLower();
}
}
Várias rotas
O roteamento de atributo dá suporte à definição de várias rotas que atingem a mesma ação. O uso mais
comum desse recurso é para simular o comportamento da rota convencional padrão, conforme
mostrado no exemplo a seguir:
[Route("[controller]")]
{
[Route("")] // Matches 'Products'
[Route("Index")] // Matches 'Products/Index'
}
Colocar vários atributos de rota no controlador significa que cada um deles será combinado com cada um
dos atributos de rota nos métodos de ação.
[Route("Store")]
[Route("[controller]")]
{
[HttpPost("Buy")] // Matches 'Products/Buy' and 'Store/Buy'
[HttpPost("Checkout")] // Matches 'Products/Checkout' and 'Store/Checkout'
public IActionResult Buy()
}
Quando vários atributos de rota (que implementam IActionConstraint ) são colocados em uma ação,
cada restrição da ação combina com o modelo de rota do atributo que a definiu.
{
[HttpPut("Buy")] // Matches PUT 'api/Products/Buy'
[HttpPost("Checkout")] // Matches POST 'api/Products/Checkout'
public IActionResult Buy()
}
TIP
Embora o uso de várias rotas em ações possa parecer eficaz, é melhor manter o espaço de URL de seu aplicativo
simples e bem definido. Use várias rotas em ações somente quando for necessário; por exemplo, para dar suporte
a clientes existentes.
Especificando parâmetros opcionais, valores padrão e restrições da rota de atributo

Rotas de atributo dão suporte à mesma sintaxe embutida que as rotas convencionais para especificar
parâmetros opcionais, valores padrão e restrições.
[HttpPost("product/{id:int}")]
public IActionResult ShowProduct(int id)
{
// ...
}
Consulte Referência de modelo de rota para obter uma descrição detalhada da sintaxe do modelo de rota.
Atributos de rota personalizados usando IRouteTemplateProvider
Todos os atributos de rota fornecidos na estrutura ( [Route(...)] , [HttpGet(...)] etc.) implementam a

interface IRouteTemplateProvider . O MVC procura atributos em classes de controlador e métodos de ação
quando o aplicativo é iniciado e usa aqueles que implementam IRouteTemplateProvider para criar o
conjunto inicial de rotas.
Você pode implementar IRouteTemplateProvider para definir seus próprios atributos de rota. Cada
IRouteTemplateProvider permite definir uma única rota com um nome, uma ordem e um modelo de rota
personalizado:
public class MyApiControllerAttribute : Attribute, IRouteTemplateProvider

{
public string Template => "api/[controller]";
public int? Order { get; set; }

}
O atributo do exemplo acima configura automaticamente o Template como "api/[controller]" quando

[MyApiController] é aplicado.
Usando o Modelo de Aplicativo para personalizar rotas de atributo

O modelo de aplicativo é um modelo de objeto criado durante a inicialização com todos os metadados
usados pelo MVC para rotear e executar suas ações. O modelo de aplicativo inclui todos os dados
reunidos dos atributos de rota (por meio de IRouteTemplateProvider ). Você pode escrever convenções
para modificar o modelo do aplicativo no momento da inicialização para personalizar o comportamento
do roteamento. Esta seção mostra um exemplo simples de personalização de roteamento usando o
modelo de aplicativo.
using Microsoft.AspNetCore.Mvc.ApplicationModels;
using System.Linq;
using System.Text;
public class NamespaceRoutingConvention : IControllerModelConvention
{
private readonly string _baseNamespace;
public NamespaceRoutingConvention(string baseNamespace)

{
_baseNamespace = baseNamespace;
}
public void Apply(ControllerModel controller)

{
var hasRouteAttributes = controller.Selectors.Any(selector =>
selector.AttributeRouteModel != null);
if (hasRouteAttributes)
{
// This controller manually defined some routes, so treat this
// as an override and not apply the convention here.
return;
}
// Use the namespace and controller name to infer a route for the controller.
//
// Example:
//
// controller.ControllerTypeInfo -> "My.Application.Admin.UsersController"
// baseNamespace -> "My.Application"
//
// template => "Admin/[controller]"
//
// This makes your routes roughly line up with the folder structure of your project.
//
var namespc = controller.ControllerType.Namespace;
if (namespc == null)
return;
var template = new StringBuilder();
template.Append(namespc, _baseNamespace.Length + 1,
namespc.Length - _baseNamespace.Length - 1);
template.Replace('.', '/');
template.Append("/[controller]");
foreach (var selector in controller.Selectors)

{
selector.AttributeRouteModel = new AttributeRouteModel()
{
Template = template.ToString()
};
}
}
}
Roteamento misto: roteamento de atributo versus roteamento

convencional
Aplicativos MVC podem combinar o uso do roteamento convencional e do roteamento de atributo. É
comum usar rotas convencionais para controladores que servem páginas HTML para navegadores e usar
o roteamento de atributo para controladores que servem APIs REST.
As ações são roteadas convencionalmente ou segundo os atributos. Colocar uma rota no controlador ou
na ação faz com que ela seja roteada segundo o atributo. Ações que definem rotas de atributo não podem
ser acessadas por meio das rotas convencionais e vice-versa. Qualquer atributo de rota no controlador
faz com que todas as ações no atributo de controlador sejam roteadas.
NOTE
O que diferencia os dois tipos de sistemas de roteamento é o processo aplicado após uma URL corresponder a um
modelo de rota. No roteamento convencional, os valores de rota da correspondência são usados para escolher a
ação e o controlador em uma tabela de pesquisa com todas as ações roteadas convencionais. No roteamento de
atributo, cada modelo já está associado a uma ação e nenhuma pesquisa adicional é necessária.
Segmentos complexos
Segmentos complexos (por exemplo, [Route("/dog{token}cat")] ), são processados combinando literais
da direita para a esquerda de uma maneira não Greedy. Veja o código-fonte para obter uma descrição.
Para obter mais informações, confira esta edição.
Geração de URL
Aplicativos MVC podem usar os recursos de geração de URL do roteamento para gerar links de URL
para ações. Gerar URLs elimina a necessidade de codificar URLs, tornando seu código mais robusto e
sustentável. Esta seção tem como foco os recursos de geração de URL fornecidos pelo MVC e só aborda
as noções básicas de como a geração de URL funciona. Consulte Roteamento para obter uma descrição
detalhada da geração de URL.
A interface IUrlHelper é a parte subjacente da infraestrutura entre o MVC e o roteamento para geração
de URL. Você encontrará uma instância de IUrlHelper disponível por meio da propriedade Url em
controladores, exibições e componentes de exibição.
Neste exemplo, a interface IUrlHelper é usada por meio a propriedade Controller.Url para gerar uma
URL para outra ação.
public class UrlGenerationController : Controller

{
public IActionResult Source()
{
// Generates /UrlGeneration/Destination
var url = Url.Action("Destination");
return Content($"Go check out {url}, it's really great.");
}
public IActionResult Destination()

{
return View();
}
}
Se o aplicativo estiver usando a rota convencional padrão, o valor da variável url será a cadeia de
caracteres do caminho de URL /UrlGeneration/Destination . Esse caminho de URL é criado pelo
roteamento combinando os valores de rota da solicitação atual (valores de ambiente) com os valores
passados para Url.Action e substituindo esses valores no modelo de rota:
ambient values: { controller = "UrlGeneration", action = "Source" }
values passed to Url.Action: { controller = "UrlGeneration", action = "Destination" }
route template: {controller}/{action}/{id?}
result: /UrlGeneration/Destination
Cada parâmetro de rota no modelo de rota tem seu valor substituído por nomes correspondentes com os
valores e os valores de ambiente. Um parâmetro de rota que não tem um valor pode usar um valor
padrão se houver um ou pode ser ignorado se for opcional (como no caso de id neste exemplo). A
geração de URL falhará se qualquer parâmetro de rota obrigatório não tiver um valor correspondente. Se
a geração de URL falhar para uma rota, a rota seguinte será tentada até que todas as rotas tenham sido
tentadas ou que uma correspondência seja encontrada.
O exemplo de Url.Action acima pressupõe que o roteamento seja convencional, mas a geração de URL
funciona de forma semelhante com o roteamento de atributo, embora os conceitos sejam diferentes. Com
o roteamento convencional, os valores de rota são usados para expandir um modelo e os valores de rota
para controller e action normalmente são exibidos no modelo – isso funciona porque as URLs
correspondidas pelo roteamento aderem a uma convenção. No roteamento de atributo, os valores de rota
para controller e action não podem ser exibidos no modelo; em vez disso, eles são usados para
pesquisar o modelo a ser usado.
Este exemplo usa o roteamento de atributo:
// In Startup class
{
app.UseMvc();
}

{
[HttpGet("")]
{
var url = Url.Action("Destination"); // Generates /custom/url/to/destination
return Content($"Go check out {url}, it's really great.");
}
[HttpGet("custom/url/to/destination")]
public IActionResult Destination() {
return View();
}
}
O MVC cria uma tabela de pesquisa de todas as ações de atributo roteadas e faz a correspondência dos
valores de controller e action para selecionar o modelo de rota a ser usado para geração de URL. Na
amostra acima, custom/url/to/destination é gerado.
Gerando URLs pelo nome da ação
Url.Action ( IUrlHelper . Action ) e todas as sobrecargas relacionadas são baseadas na ideia de que
você deseja especificar ao que está vinculando, especificando um nome do controlador e um nome da
ação.
NOTE
Ao usar Url.Action , os valores de rota atuais para controller e action são especificados para você – o valor
de controller e action fazem parte de valores de ambiente e de valores. O método Url.Action sempre
usa os valores atuais de action e controller e gera um caminho de URL que roteia para a ação atual.
O roteamento tenta usar os valores em valores de ambiente para preencher informações que você não
forneceu ao gerar uma URL. Usando uma rota como {a}/{b}/{c}/{d} e valores de ambiente
{ a = Alice, b = Bob, c = Carol, d = David } , o roteamento tem informações suficientes para gerar uma
URL sem valores adicionais – uma vez que todos os parâmetros de rota têm um valor. Se você tiver
adicionado o valor { d = Donovan } , o valor { d = David } será ignorado e o caminho de URL gerado
será Alice/Bob/Carol/Donovan .
WARNING
Caminhos de URL são hierárquicos. No exemplo acima, se você tiver adicionado o valor { c = Cheryl } , ambos
os valores { c = Carol, d = David } serão ignorados. Nesse caso, não teremos mais um valor para d e a
geração de URL falhará. Você precisaria especificar o valor desejado de c e d . Você pode esperar se deparar com
esse problema com a rota padrão ( {controller}/{action}/{id?} ) – mas raramente encontrará esse
comportamento na prática, pois Url.Action sempre especificará explicitamente um valor de controller e
action .
Sobrecargas maiores de Url.Action também usam um objeto adicional de valores de rota para fornecer
valores para parâmetros de rota diferentes de controller e action . É mais comum ver isso com id
como Url.Action("Buy", "Products", new { id = 17 }) . Por convenção, o objeto de valores de rota
geralmente é um objeto de tipo anônimo, mas também pode ser um IDictionary<> ou um objeto .NET
simples. Qualquer valor de rota adicional que não corresponder aos parâmetros de rota será colocado na
cadeia de caracteres de consulta.
public class TestController : Controller

{
{
// Generates /Products/Buy/17?color=red
var url = Url.Action("Buy", "Products", new { id = 17, color = "red" });
return Content(url);
}
}
TIP
Para criar uma URL absoluta, use uma sobrecarga que aceita um protocol :
Url.Action("Buy", "Products", new { id = 17 }, protocol: Request.Scheme)
Gerando URLs pela rota

O código acima demonstrou a geração de uma URL passando o nome do controlador e da ação.
IUrlHelper também fornece a família de métodos Url.RouteUrl . Esses métodos são semelhantes a
Url.Action , mas não copiam os valores atuais de action e controller para os valores de rota. O uso
mais comum é especificar um nome de rota para usar uma rota específica para gerar a URL, geralmente
sem especificar um nome de controlador ou de ação.

{
[HttpGet("")]
{
var url = Url.RouteUrl("Destination_Route"); // Generates /custom/url/to/destination
return Content($"See {url}, it's really great.");
}
[HttpGet("custom/url/to/destination", Name = "Destination_Route")]

public IActionResult Destination() {
return View();
}
}
Gerar URLs em HTML

IHtmlHelper fornece o métodos Html.BeginForm e Html.ActionLink de HtmlHelper para gerar elementos
<form> e <a> respectivamente. Esses métodos usam o método Url.Action para gerar uma URL e
aceitam argumentos semelhantes. O complementos Url.RouteUrl para HtmlHelper são
Html.BeginRouteForm e Html.RouteLink , que têm uma funcionalidade semelhante.
TagHelpers geram URLs por meio do TagHelper form e do TagHelper <a> . Ambos usam IUrlHelper
para sua implementação. Consulte Trabalhando com Formulários para obter mais informações.
Nos modos de exibição, o IUrlHelper está disponível por meio da propriedade Url para qualquer
geração de URL ad hoc não abordada acima.
Gerando URLS nos resultados da ação
Os exemplos acima mostraram o uso de IUrlHelper em um controlador, enquanto o uso mais comum
em um controlador é gerar uma URL como parte do resultado de uma ação.
As classes base ControllerBase e Controller fornecem métodos de conveniência para resultados de
ação que fazem referência a outra ação. Um uso típico é para redirecionar após aceitar a entrada do
usuário.
public IActionResult Edit(int id, Customer customer)

{
{
// Update DB with new details.
}
return View(customer);
}
Os métodos de fábrica dos resultados da ação seguem um padrão semelhante aos métodos em
IUrlHelper .
Caso especial para rotas convencionais dedicadas

O roteamento convencional pode usar um tipo especial de definição de rota chamado rota convencional
dedicada. No exemplo a seguir, a rota chamada blog é uma rota convencional dedicada.
{
});
Usando essas definições de rota, Url.Action("Index", "Home") gerará o caminho de URL / com a rota
default , mas por quê? Você poderia imaginar que os valores de rota
{ controller = Home, action = Index } seriam suficientes para gerar uma URL usando blog e o
resultado seria /blog?action=Index&controller=Home .
Rotas convencionais dedicadas dependem de um comportamento especial de valores padrão que não
têm um parâmetro de rota correspondente que impeça que a rota seja "muito ambiciosa" com a geração
de URLs. Nesse caso, os valores padrão são { controller = Blog, action = Article } e nem controller
ou action aparece como um parâmetro de rota. Quando o roteamento executa a geração de URL, os
valores fornecidos devem corresponder aos valores padrão. A geração de URL usando blog falhará
porque os valores de { controller = Home, action = Index } não correspondem a
{ controller = Blog, action = Article } . O roteamento, então, faz o fallback para tentar default , que é
bem-sucedido.
Áreas
Áreas são um recurso do MVC usado para organizar funcionalidades relacionadas em um grupo como
um namespace de roteamento (para ações do controlador) e estrutura de pasta (para exibições) separada.
O uso de áreas permite que um aplicativo tenha vários controladores com o mesmo nome, desde que
tenham áreas diferentes. O uso de áreas cria uma hierarquia para fins de roteamento, adicionando outro
parâmetro de rota, area a controller e action . Esta seção aborda como o roteamento interage com as
áreas. Consulte Áreas para obter detalhes sobre como as áreas são usadas com exibições.
O exemplo a seguir configura o MVC para usar a rota convencional padrão e uma rota de área para uma
área chamada Blog :
{
routes.MapAreaRoute("blog_route", "Blog",
"Manage/{controller}/{action}/{id?}");
routes.MapRoute("default_route", "{controller}/{action}/{id?}");
});
Ao fazer a correspondência de um caminho de URL como /Manage/Users/AddUser , a primeira rota

produzirá os valores de rota { area = Blog, controller = Users, action = AddUser } . O valor de rota
area é produzido por um valor padrão para area . De fato, a rota criada por MapAreaRoute é equivalente
à seguinte:
{
routes.MapRoute("blog_route", "Manage/{controller}/{action}/{id?}",
defaults: new { area = "Blog" }, constraints: new { area = "Blog" });
routes.MapRoute("default_route", "{controller}/{action}/{id?}");
});
MapAreaRoute cria uma rota usando um valor padrão e a restrição para area usando o nome da área
fornecido, nesse caso, Blog . O valor padrão garante que a rota sempre produza { area = Blog, ... } , a
restrição requer o valor { area = Blog, ... } para geração de URL.
TIP
O roteamento convencional é dependente da ordem. De modo geral, rotas com áreas devem ser colocadas mais
no início na tabela de rotas, uma vez que são mais específicas que rotas sem uma área.
Usando o exemplo acima, os valores de rota corresponderiam à ação a seguir:
namespace MyApp.Namespace1
{
[Area("Blog")]
public class UsersController : Controller
{
public IActionResult AddUser()
{
return View();
}
}
}
O AreaAttribute é o que indica que um controlador faz parte de uma área; dizemos que esse controlador
está na área Blog . Controladores sem um atributo [Area] não são membros de nenhuma área e não
corresponderão quando o valor de rota area for fornecido pelo roteamento. No exemplo a seguir,
somente o primeiro controlador listado pode corresponder aos valores de rota
{ area = Blog, controller = Users, action = AddUser } .
{
[Area("Blog")]
{
{
return View();
}
}
}
{
// Matches { area = Zebra, controller = Users, action = AddUser }
[Area("Zebra")]
{
{
return View();
}
}
}
{
// Matches { area = string.Empty, controller = Users, action = AddUser }
// Matches { area = null, controller = Users, action = AddUser }
// Matches { controller = Users, action = AddUser }
{
{
return View();
}
}
}
NOTE
O namespace de cada controlador é mostrado aqui para fins de integridade – caso contrário, os controladores
teriam um conflito de nomenclatura e gerariam um erro do compilador. Namespaces de classe não têm efeito sobre
o roteamento do MVC.
Os primeiros dois controladores são membros de áreas e correspondem somente quando seus
respectivos nomes de área são fornecidos pelo valor de rota area . O terceiro controlador não é um
membro de nenhuma área e só pode corresponder quando nenhum valor para area for fornecido pelo
roteamento.
NOTE
Em termos de não corresponder a nenhum valor, a ausência do valor de area é equivalente ao valor de area
ser nulo ou uma cadeia de caracteres vazia.
Ao executar uma ação dentro de uma área, o valor de rota para area estará disponível como um valor de
ambiente para o roteamento usar para geração de URL. Isso significa que, por padrão, as áreas atuam
como se fossem autoadesivas para a geração de URL, como demonstrado no exemplo a seguir.
{
routes.MapAreaRoute("duck_route", "Duck",
"Manage/{controller}/{action}/{id?}");
routes.MapRoute("default", "Manage/{controller=Home}/{action=Index}/{id?}");
});
{
[Area("Duck")]
{
public IActionResult GenerateURLInArea()
{
// Uses the 'ambient' value of area
var url = Url.Action("Index", "Home");
// returns /Manage
}
public IActionResult GenerateURLOutsideOfArea()

{
// Uses the empty value for area
var url = Url.Action("Index", "Home", new { area = "" });
// returns /Manage/Home/Index
}
}
}
Entendendo IActionConstraint
NOTE
Esta seção é uma análise aprofundada dos elementos internos da estrutura e de como o MVC escolhe uma ação
para ser executada. Um aplicativo típico não precisará de um IActionConstraint personalizado
Provavelmente, você já usou IActionConstraint mesmo que não esteja familiarizado com a interface. O
atributo [HttpGet] e atributos [Http-VERB] semelhantes implementam IActionConstraint para limitar a
execução de um método de ação.

{
[HttpGet]
public IActionResult Edit() { }
public IActionResult Edit(...) { }

}
Presumindo a rota convencional padrão, o caminho de URL /Products/Edit produziria os valores

{ controller = Products, action = Edit } , que corresponderiam a ambas as ações mostradas aqui. Na
terminologia IActionConstraint , diríamos que essas duas ações são consideradas candidatas – uma vez
que ambas correspondem aos dados da rota.
Quando for executado, HttpGetAttribute indicará que Edit() corresponde a GET e não corresponde a
nenhum outro verbo HTTP. A ação Edit(...) não tem restrições definidas e, portanto, corresponderá a
qualquer verbo HTTP. Sendo assim, supondo um POST , Edit(...) será correspondente. Mas, para um
GET , ambas as ações ainda podem corresponder – no entanto, uma ação com um IActionConstraint
sempre é considerada melhor que uma ação sem. Assim, como Edit() tem [HttpGet] , ela é considerada
mais específica e será selecionada se as duas ações puderem corresponder.
Conceitualmente, IActionConstraint é uma forma de sobrecarga, mas em vez de uma sobrecarga de
métodos com o mesmo nome, trata-se da sobrecarga entre ações que correspondem à mesma URL. O
roteamento de atributo também usa IActionConstraint e pode fazer com que ações de controladores
diferentes sejam consideradas candidatas.
Implementando IActionConstraint
A maneira mais simples de implementar um IActionConstraint é criar uma classe derivada de
System.Attribute e colocá-la em suas ações e controladores. O MVC descobrirá automaticamente
qualquer IActionConstraint que for aplicado como atributo. Você pode usar o modelo de aplicativo para
aplicar restrições e, provavelmente, essa é a abordagem mais flexível, pois permite a você faça uma
metaprogramação de como elas são aplicadas.
No exemplo a seguir, uma restrição escolhe uma ação com base em um código de país dos dados de rota.
O exemplo completo no GitHub.
public class CountrySpecificAttribute : Attribute, IActionConstraint

{
private readonly string _countryCode;
public CountrySpecificAttribute(string countryCode)

{
_countryCode = countryCode;
}
public int Order

{
get
{
return 0;
}
}
public bool Accept(ActionConstraintContext context)

{
return string.Equals(
context.RouteContext.RouteData.Values["country"].ToString(),
_countryCode,
StringComparison.OrdinalIgnoreCase);
}
}
Você é responsável por implementar o método Accept e por escolher uma "ordem" na qual a restrição
deve ser executada. Nesse caso, o método Accept retorna true para indicar que a ação é
correspondente quando o valor de rota country é correspondente. Isso é diferente de um
RouteValueAttribute , pois permite o fallback para uma ação não atribuída. O exemplo mostra que se você
definir uma ação en-US , um código de país como fr-FR fará o fallback para um controlador mais
genérico que não tem [CountrySpecific(...)] aplicado.
A propriedade Order decide de qual estágio a restrição faz parte. Restrições de ação são executadas em
grupos com base no Order . Por exemplo, todos atributos de método HTTP fornecidos pela estrutura
usam o mesmo valor de Order para que sejam executados no mesmo estágio. Você pode ter tantos
estágios quantos forem necessários para implementar suas políticas desejadas.
TIP
Para decidir o valor para Order , considere se sua restrição deve ou não deve ser aplicada antes de métodos
HTTP. Números inferiores são executados primeiro.
Uploads de arquivos no ASP.NET Core
Por Steve Smith

Ações do ASP.NET MVC dão suporte ao upload de um ou mais arquivos usando model binding simples para
arquivos menores ou streaming para arquivos maiores.
Exibir ou baixar a amostra do GitHub
Upload de arquivos pequenos com o model binding

Para carregar arquivos pequenos, você pode usar um formulário HTML com várias partes ou construir uma
solicitação POST usando JavaScript. Um formulário de exemplo usando Razor, que dá suporte a vários arquivos
carregados, é mostrado abaixo:
<form method="post" enctype="multipart/form-data" asp-controller="UploadFiles" asp-action="Index">

<p>Upload one or more files using this form:</p>
<input type="file" name="files" multiple />
</div>
</div>
<input type="submit" value="Upload" />
</div>
</div>
</form>
Para dar suporte a uploads de arquivos, os formulários HTML devem especificar um enctype igual a
multipart/form-data . O elemento de entrada files mostrado acima dá suporte ao upload de vários arquivos.
Omita o atributo multiple neste elemento de entrada para permitir o upload de apenas um arquivo. A marcação
acima é renderizada em um navegador como:
Os arquivos individuais carregados no servidor podem ser acessados por meio do Model binding usando a
interface IFormFile. IFormFile tem esta estrutura:
public interface IFormFile
{
string ContentType { get; }
string ContentDisposition { get; }
IHeaderDictionary Headers { get; }
long Length { get; }
string Name { get; }
string FileName { get; }
Stream OpenReadStream();
void CopyTo(Stream target);
Task CopyToAsync(Stream target, CancellationToken cancellationToken = null);
}
WARNING
Não dependa ou confie na propriedade FileName sem validação. A propriedade FileName deve ser usada somente para
fins de exibição.
Ao fazer upload de arquivos usando model binding e a interface IFormFile , o método de ação pode aceitar um
único IFormFile ou um IEnumerable<IFormFile> (ou List<IFormFile> ) que representa vários arquivos. O exemplo
a seguir executa um loop em um ou mais arquivos carregados, salva-os no sistema de arquivos local e retorna o
número total e o tamanho dos arquivos carregados.
Aviso: o seguinte código usa GetTempFileName , que gerará um IOException se mais de 65.535 arquivos forem
criados sem excluir os arquivos temporários anteriores. Um aplicativo real deve excluir arquivos temporários ou
usar GetTempPath e GetRandomFileName para criar nomes de arquivo temporários. O limite de 65.535 arquivos é
por servidor, então outro aplicativo no servidor poderá usar todos os 65.535 arquivos.
[HttpPost("UploadFiles")]
public async Task<IActionResult> Post(List<IFormFile> files)
{
long size = files.Sum(f => f.Length);
// full path to file in temp location

var filePath = Path.GetTempFileName();
foreach (var formFile in files)

{
if (formFile.Length > 0)
{
using (var stream = new FileStream(filePath, FileMode.Create))
{
await formFile.CopyToAsync(stream);
}
}
}
// process uploaded files

// Don't rely on or trust the FileName property without validation.
return Ok(new { count = files.Count, size, filePath});

}
Arquivos carregados usando a técnica IFormFile são armazenados em buffer na memória ou no disco no servidor
Web antes de serem processados. Dentro do método de ação, o conteúdo de IFormFile podem ser acessado como
um fluxo. Além do sistema de arquivos local, os arquivos podem ser transmitidos para o Armazenamento de Blobs
do Azure ou para o Entity Framework.
Para armazenar dados de arquivo binário em um banco de dados usando o Entity Framework, defina uma
propriedade do tipo byte[] na entidade:
public class ApplicationUser : IdentityUser

{
public byte[] AvatarImage { get; set; }
}
Especifique uma propriedade de viewmodel do tipo IFormFile :
public class RegisterViewModel

{
// other properties omitted
public IFormFile AvatarImage { get; set; }

}
NOTE
IFormFile pode ser usado diretamente como um parâmetro de método de ação ou como uma propriedade de viewmodel,
como mostrado acima.
Copie o IFormFile para um fluxo e salve-o na matriz de bytes:
// POST: /Account/Register
[HttpPost]
[AllowAnonymous]
public async Task<IActionResult> Register(RegisterViewModel model)
{
ViewData["ReturnUrl"] = returnUrl;
{
var user = new ApplicationUser {
UserName = model.Email,
Email = model.Email
};
using (var memoryStream = new MemoryStream())
{
await model.AvatarImage.CopyToAsync(memoryStream);
user.AvatarImage = memoryStream.ToArray();
}
// additional logic omitted
// Don't rely on or trust the model.AvatarImage.FileName property

// without validation.
}
NOTE
Tenha cuidado ao armazenar dados binários em bancos de dados relacionais, pois isso pode afetar negativamente o
desempenho.
Upload de arquivos grandes usando streaming

Se o tamanho ou a frequência dos uploads de arquivos estiver causando problemas de recursos para o aplicativo,
considere transmitir o upload dos arquivos por streaming em vez de armazená-los completamente em buffer,
como na abordagem de model binding mostrada acima. Embora o uso de IFormFile e do model binding seja uma
solução muito mais simples, o streaming requer a execução de algumas etapas para ser implementado
corretamente.
NOTE
Qualquer arquivo armazenado em buffer que exceder 64KB será movido do RAM para um arquivo temporário em disco no
servidor. Os recursos (disco, RAM) usados pelos uploads de arquivos dependem do número e do tamanho dos uploads de
arquivos simultâneos. Streaming não é tanto uma questão de desempenho, e sim de escala. Se você tentar armazenar muitos
uploads em buffer, seu site falhará quando ficar sem memória ou sem espaço em disco.
O exemplo a seguir demonstra como usar JavaScript/Angular para fazer o streaming para uma ação do
controlador. O token antifalsificação do arquivo é gerado usando um atributo de filtro personalizado e passada nos
cabeçalhos HTTP em vez do corpo da solicitação. Como um método de ação processa os dados carregados
diretamente, o model binding é desabilitado por outro filtro. Dentro da ação, o conteúdo do formulário é lido
usando um MultipartReader , que lê cada MultipartSection individual, processando o arquivo ou armazenando o
conteúdo conforme apropriado. Após todas as seções serem lidas, a ação executa seu próprio model binding.
A ação inicial carrega o formulário e salva um token antifalsificação em um cookie (por meio do atributo
GenerateAntiforgeryTokenCookieForAjax ):
[HttpGet]
[GenerateAntiforgeryTokenCookieForAjax]
{
return View();
}
O atributo usa o suporte interno Antifalsificação do ASP.NET Core para definir um cookie com um token de
solicitação:
public class GenerateAntiforgeryTokenCookieForAjaxAttribute : ActionFilterAttribute

{
public override void OnActionExecuted(ActionExecutedContext context)
{
var antiforgery = context.HttpContext.RequestServices.GetService<IAntiforgery>();
// We can send the request token as a JavaScript-readable cookie,

// and Angular will use it by default.
var tokens = antiforgery.GetAndStoreTokens(context.HttpContext);
context.HttpContext.Response.Cookies.Append(
"XSRF-TOKEN",
tokens.RequestToken,
new CookieOptions() { HttpOnly = false });
}
}
O Angular passa automaticamente um token antifalsificação em um cabeçalho de solicitação chamado

X-XSRF-TOKEN . O aplicativo ASP.NET Core MVC é configurado para se referir a esse cabeçalho em sua
configuração em Startup.cs:

{
// Angular's default header name for sending the XSRF token.
services.AddAntiforgery(options => options.HeaderName = "X-XSRF-TOKEN");
services.AddMvc();
}
O atributo DisableFormValueModelBinding , mostrado abaixo, é usado para desabilitar o model binding para o
método de ação Upload .
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
public class DisableFormValueModelBindingAttribute : Attribute, IResourceFilter
{
public void OnResourceExecuting(ResourceExecutingContext context)
{
var factories = context.ValueProviderFactories;
factories.RemoveType<FormValueProviderFactory>();
factories.RemoveType<JQueryFormValueProviderFactory>();
}
public void OnResourceExecuted(ResourceExecutedContext context)

{
}
}
Como o model binding é desabilitado, o método de ação Upload não aceita parâmetros. Ele trabalha diretamente
com a propriedade Request de ControllerBase . Um MultipartReader é usado para ler cada seção. O arquivo é
salvo com um nome de arquivo GUID e os dados de chave/valor são armazenados em um KeyValueAccumulator .
Após todas as seções terem sido lidas, o conteúdo do KeyValueAccumulator é usado para associar os dados do
formulário a um tipo de modelo.
O método Upload completo é mostrado abaixo:
Aviso: o seguinte código usa GetTempFileName , que gerará um IOException se mais de 65.535 arquivos forem
criados sem excluir os arquivos temporários anteriores. Um aplicativo real deve excluir arquivos temporários ou
usar GetTempPath e GetRandomFileName para criar nomes de arquivo temporários. O limite de 65.535 arquivos é
por servidor, então outro aplicativo no servidor poderá usar todos os 65.535 arquivos.
// 1. Disable the form value model binding here to take control of handling
// potentially large files.
// 2. Typically antiforgery tokens are sent in request body, but since we
// do not want to read the request body early, the tokens are made to be
// sent via headers. The antiforgery token filter first looks for tokens
// in the request header and then falls back to reading the body.
[HttpPost]
[DisableFormValueModelBinding]
public async Task<IActionResult> Upload()
{
if (!MultipartRequestHelper.IsMultipartContentType(Request.ContentType))
{
return BadRequest($"Expected a multipart request, but got {Request.ContentType}");
}
// Used to accumulate all the form url encoded key value pairs in the
// request.
var formAccumulator = new KeyValueAccumulator();
string targetFilePath = null;
var boundary = MultipartRequestHelper.GetBoundary(

MediaTypeHeaderValue.Parse(Request.ContentType),
_defaultFormOptions.MultipartBoundaryLengthLimit);
var reader = new MultipartReader(boundary, HttpContext.Request.Body);
var section = await reader.ReadNextSectionAsync();

while (section != null)
{
ContentDispositionHeaderValue contentDisposition;
var hasContentDispositionHeader = ContentDispositionHeaderValue.TryParse(section.ContentDisposition,
out contentDisposition);
out contentDisposition);
if (hasContentDispositionHeader)
{
if (MultipartRequestHelper.HasFileContentDisposition(contentDisposition))
{
targetFilePath = Path.GetTempFileName();
using (var targetStream = System.IO.File.Create(targetFilePath))
{
await section.Body.CopyToAsync(targetStream);
_logger.LogInformation($"Copied the uploaded file '{targetFilePath}'");

}
}
else if (MultipartRequestHelper.HasFormDataContentDisposition(contentDisposition))
{
// Content-Disposition: form-data; name="key"
//
// value
// Do not limit the key name length here because the

// multipart headers length limit is already in effect.
var key = HeaderUtilities.RemoveQuotes(contentDisposition.Name);
var encoding = GetEncoding(section);
using (var streamReader = new StreamReader(
section.Body,
encoding,
detectEncodingFromByteOrderMarks: true,
bufferSize: 1024,
leaveOpen: true))
{
// The value length limit is enforced by MultipartBodyLengthLimit
var value = await streamReader.ReadToEndAsync();
if (String.Equals(value, "undefined", StringComparison.OrdinalIgnoreCase))
{
value = String.Empty;
}
formAccumulator.Append(key, value);
if (formAccumulator.ValueCount > _defaultFormOptions.ValueCountLimit)

{
throw new InvalidDataException($"Form key count limit
{_defaultFormOptions.ValueCountLimit} exceeded.");
}
}
}
}
// Drains any remaining section body that has not been consumed and
// reads the headers for the next section.
section = await reader.ReadNextSectionAsync();
}
// Bind form data to a model

var user = new User();
var formValueProvider = new FormValueProvider(
BindingSource.Form,
new FormCollection(formAccumulator.GetResults()),
CultureInfo.CurrentCulture);
var bindingSuccessful = await TryUpdateModelAsync(user, prefix: "",

valueProvider: formValueProvider);
if (!bindingSuccessful)
{
{
return BadRequest(ModelState);
}
}
var uploadedData = new UploadedData()
{
Name = user.Name,
Age = user.Age,
Zipcode = user.Zipcode,
FilePath = targetFilePath
};
return Json(uploadedData);
}
Abaixo, são listados alguns problemas comuns encontrados ao trabalhar com o upload de arquivos e suas
possíveis soluções.
Erro não encontrado inesperado com o IIS
O erro a seguir indica que o upload do arquivo excede o maxAllowedContentLength configurado do servidor:
HTTP 404.13 - Not Found

The request filtering module is configured to deny a request that exceeds the request content length.
A configuração padrão é 30000000 , que é aproximadamente 28,6 MB. O valor pode ser personalizado editando
web.config:
<system.webServer>
<security>
<requestFiltering>

<requestLimits maxAllowedContentLength="52428800" />
</requestFiltering>
</security>
</system.webServer>
Essa configuração só se aplica ao IIS. Esse comportamento não ocorre por padrão quando a hospedagem é feita
no Kestrel. Para obter mais informações, consulte Limites de solicitação <requestLimits>.
Exceção de referência nula com IFormFile
Se o controlador estiver aceitando arquivos carregados usando IFormFile , mas você observar que o valor sempre
é nulo, confirme que seu formulário HTML está especificando um valor de enctype igual a multipart/form-data .
Se esse atributo não estiver definido no elemento <form> , o upload do arquivo não ocorrerá e os argumentos
IFormFile associados serão nulos.
Injeção de dependência em controladores no
ASP.NET Core
Por Steve Smith

Controladores do ASP.NET Core MVC devem solicitar suas dependências explicitamente por meio de seus
construtores. Em algumas instâncias, ações individuais do controlador podem exigir um serviço e pode não fazer
sentido solicitá-lo no nível do controlador. Nesse caso, você também pode optar por injetar um serviço como um
parâmetro no método de ação.
A injeção de dependência é uma técnica que segue o Princípio de inversão de dependência, permitindo que
aplicativos sejam compostos por módulos acoplados de forma flexível. O ASP.NET Core tem suporte interno
para a injeção de dependência, o que facilita a manutenção e o teste de aplicativos.
Injeção de construtor
O suporte interno do ASP.NET Core para injeção de dependência baseada no construtor se estende para
controladores MVC. Simplesmente adicionando um tipo de serviço ao seu controlador como um parâmetro de
construtor, o ASP.NET Core tentará resolver o tipo usando seu contêiner de serviço interno. Os serviços são
normalmente, mas não sempre, definidos usando interfaces. Por exemplo, se seu aplicativo tiver lógica de
negócios que depende da hora atual, você pode injetar um serviço que recupera a hora (em vez fazer o hard-
coding), o que permite que seus testes sejam passados em implementações que usam uma hora definida.
using System;
namespace ControllerDI.Interfaces
{
public interface IDateTime
{
DateTime Now { get; }
}
}
Implementar uma interface como esta para que ele use o relógio do sistema em tempo de execução é simples:
using System;
using ControllerDI.Interfaces;
namespace ControllerDI.Services
{
public class SystemDateTime : IDateTime
{
public DateTime Now
{
get { return DateTime.Now; }
}
}
}
Com isso em vigor, podemos usar o serviço em nosso controlador. Nesse caso, adicionamos alguma lógica para
ao método HomeController Index para exibir uma saudação ao usuário com base na hora do dia.
using ControllerDI.Interfaces;
namespace ControllerDI.Controllers
{
{
private readonly IDateTime _dateTime;
public HomeController(IDateTime dateTime)

{
_dateTime = dateTime;
}

{
var serverTime = _dateTime.Now;
if (serverTime.Hour < 12)
{
ViewData["Message"] = "It's morning here - Good Morning!";
}
else if (serverTime.Hour < 17)
{
ViewData["Message"] = "It's afternoon here - Good Afternoon!";
}
else
{
ViewData["Message"] = "It's evening here - Good Evening!";
}
return View();
}
}
}
Se executarmos o aplicativo agora, provavelmente encontraremos um erro:
InvalidOperationException: Unable to resolve service for type 'ControllerDI.Interfaces.IDateTime' while

attempting to activate 'ControllerDI.Controllers.HomeController'.
Microsoft.Extensions.DependencyInjection.ActivatorUtilities.GetService(IServiceProvider sp, Type type, Type
requiredBy, Boolean isDefaultParameterRequired)
Esse erro ocorre quando não configuramos um serviço no método ConfigureServices em nossa classe Startup .
Para especificar que solicitações de IDateTime devem ser resolvidas usando uma instância de SystemDateTime ,
adicione a linha realçada à lista abaixo para seu método ConfigureServices :

{
services.AddTransient<IDateTime, SystemDateTime>();
}
NOTE
Esse serviço específico poderia ser implementado usando qualquer uma das várias opções diferentes de tempo de vida (
Transient , Scoped ou Singleton ). Consulte Injeção de dependência para entender como cada uma dessas opções de
escopo afetará o comportamento de seu serviço.
Depois que o serviço tiver sido configurado, executar o aplicativo e navegar para a home page deve exibir a
mensagem baseada em hora conforme o esperado:
TIP
Confira Testar a lógica do controlador para saber como solicitar dependências explicitamente http://deviq.com/explicit-
dependencies-principle/ em controladores e facilitar o teste do código.
A injeção de dependência interna do ASP.NET Core dá suporte a apenas um construtor para classes que
solicitam serviços. Se tiver mais de um construtor, você poderá receber uma exceção informando:
InvalidOperationException: Multiple constructors accepting all given argument types have been found in type
'ControllerDI.Controllers.HomeController'. There should only be one applicable constructor.
Microsoft.Extensions.DependencyInjection.ActivatorUtilities.FindApplicableConstructor(Type instanceType,
Type[] argumentTypes, ConstructorInfo& matchingConstructor, Nullable`1[]& parameterMap)
Como a mensagem de erro afirma, você pode corrigir esse problema usando um único construtor. Você também
pode substituir o contêiner de injeção de dependência padrão por uma implementação de terceiros, muitas das
quais dão suporte a vários construtores.
Injeção de ação com FromServices

Às vezes, você não precisa de um serviço para mais de uma ação em seu controlador. Nesse caso, talvez faça
sentido injetar o serviço como um parâmetro do método de ação. Isso é feito marcando o parâmetro com o
atributo [FromServices] , conforme mostrado aqui:
public IActionResult About([FromServices] IDateTime dateTime)
{
ViewData["Message"] = "Currently on the server the time is " + dateTime.Now;
return View();
}
Acessando configurações de um controlador

Acessar definições de configuração ou do aplicativo de dentro de um controlador é um padrão comum. Esse
acesso deve usar o padrão Opções descrito na configuração. Geralmente, você não deve solicitar configurações
diretamente de seu controlador usando a injeção de dependência. Uma abordagem melhor é solicitar uma
instância de IOptions<T> , em que T é a classe de configuração de que você precisa.
Para trabalhar com o padrão de opções, você precisa criar uma classe que representa as opções, como esta:
namespace ControllerDI.Model
{
public class SampleWebSettings
{
public int Updates { get; set; }
}
}
Em seguida, você precisa configurar o aplicativo para usar o modelo de opções e adicionar sua classe de
configuração à coleção de serviços em ConfigureServices :

{
.SetBasePath(env.ContentRootPath)
.AddJsonFile("samplewebsettings.json");
}
public IConfigurationRoot Configuration { get; set; }
// For more information on how to configure your application, visit http://go.microsoft.com/fwlink/?
LinkID=398940
{
// Required to use the Options<T> pattern
services.AddOptions();
// Add settings from configuration

services.Configure<SampleWebSettings>(Configuration);
// Uncomment to add settings from code

//services.Configure<SampleWebSettings>(settings =>
//{
// settings.Updates = 17;
//});
services.AddMvc();

services.AddTransient<IDateTime, SystemDateTime>();
}
NOTE
Na lista acima, estamos configurando o aplicativo para ler as configurações de um arquivo no formato JSON. Você também
pode definir as configurações inteiramente no código, como é mostrado no código comentado acima. Consulte
Configuração para ver outras opções de configuração.
Após ter especificado um objeto de configuração fortemente tipado (nesse caso, SampleWebSettings ) e tê-lo
adicionado à coleção de serviços, você pode solicitá-lo de qualquer método de Ação ou Controlador solicitando
uma instância de IOptions<T> (nesse caso, IOptions<SampleWebSettings> ). O código a seguir mostra como
alguém solicitaria as configurações de um controlador:
public class SettingsController : Controller

{
private readonly SampleWebSettings _settings;
public SettingsController(IOptions<SampleWebSettings> settingsOptions)

{
_settings = settingsOptions.Value;
}

{
ViewData["Title"] = _settings.Title;
ViewData["Updates"] = _settings.Updates;
return View();
}
}
Seguir o padrão Opções permite que as definições e configurações sejam dissociadas umas das outras e garante
que o controlador esteja seguindo a separação de preocupações, uma vez que ele não precisa saber como nem
onde encontrar as informações de configuração. Isso facilita a realização de teste de unidade no controlador
usando a Lógica do controlador de teste, porque não há nenhuma adesão estática ou criação de instância direta
das classes de configuração dentro da classe do controlador.
Injeção de dependência em exibições no ASP.NET
Core
Por Steve Smith

O ASP.NET Core dá suporte à injeção de dependência em exibições. Isso pode ser útil para serviços específicos
a uma exibição, como localização ou dados necessários apenas para o preenchimento de elementos de exibição.
Você deve tentar manter a separação de interesses entre os controladores e as exibições. A maioria dos dados
exibida pelas exibições deve ser passada pelo controlador.
Um exemplo simples
Injete um serviço em uma exibição usando a diretiva @inject . Considere @inject como a adição de uma
propriedade à exibição e o preenchimento da propriedade usando a DI.
A sintaxe de @inject : @inject <type> <name>
Um exemplo de @inject em ação:

@using System.Threading.Tasks
@using ViewInjectSample.Model
@using ViewInjectSample.Model.Services
@model IEnumerable<ToDoItem>
@inject StatisticsService StatsService
<!DOCTYPE html>
<html>
<head>
<title>To Do Items</title>
</head>
<body>
<div>
<h1>To Do Items</h1>
<ul>
<li>Total Items: @StatsService.GetCount()</li>
<li>Completed: @StatsService.GetCompletedCount()</li>
<li>Avg. Priority: @StatsService.GetAveragePriority()</li>
</ul>
<table>
<tr>
<th>Name</th>
<th>Priority</th>
<th>Is Done?</th>
</tr>
@foreach (var item in Model)
{
<tr>
<td>@item.Name</td>
<td>@item.Priority</td>
<td>@item.IsDone</td>
</tr>
}
</table>
</div>
</body>
</html>
Essa exibição exibe uma lista de instâncias ToDoItem , junto com um resumo mostrando estatísticas gerais. O
resumo é populado com base no StatisticsService injetado. Esse serviço é registrado para injeção de
dependência em ConfigureServices em Startup.cs:
// For more information on how to configure your application, visit http://go.microsoft.com/fwlink/?

LinkID=398940
{
services.AddMvc();
services.AddTransient<IToDoItemRepository, ToDoItemRepository>();
services.AddTransient<StatisticsService>();
services.AddTransient<ProfileOptionsService>();
O StatisticsService faz alguns cálculos no conjunto de instâncias ToDoItem , que ele acessa por meio de um
repositório:
using System.Linq;
using ViewInjectSample.Interfaces;
namespace ViewInjectSample.Model.Services
{
public class StatisticsService
{
private readonly IToDoItemRepository _toDoItemRepository;
public StatisticsService(IToDoItemRepository toDoItemRepository)

{
_toDoItemRepository = toDoItemRepository;
}
public int GetCount()

{
return _toDoItemRepository.List().Count();
}
public int GetCompletedCount()

{
return _toDoItemRepository.List().Count(x => x.IsDone);
}
public double GetAveragePriority()

{
if (_toDoItemRepository.List().Count() == 0)
{
return 0.0;
}
return _toDoItemRepository.List().Average(x => x.Priority);

}
}
}
O repositório de exemplo usa uma coleção em memória. A implementação mostrada acima (que opera em
todos os dados na memória) não é recomendada para conjuntos de dados grandes e acessados remotamente.
A amostra exibe dados do modelo associado à exibição e o serviço injetado na exibição:
Populando os dados de pesquisa

A injeção de exibição pode ser útil para popular opções em elementos de interface do usuário, como listas
suspensas. Considere um formulário de perfil do usuário que inclui opções para especificar o gênero, estado e
outras preferências. A renderização desse formulário usando uma abordagem MVC padrão exigirá que o
controlador solicite serviços de acesso a dados para cada um desses conjuntos de opções e, em seguida, popule
um modelo ou ViewBag com cada conjunto de opções a ser associado.
Uma abordagem alternativa injeta os serviços diretamente na exibição para obter as opções. Isso minimiza a
quantidade de código necessária para o controlador, movendo essa lógica de construção do elemento de
exibição para a própria exibição. A ação do controlador para exibir um formulário de edição de perfil precisa
apenas passar a instância de perfil para o formulário:
using ViewInjectSample.Model;
namespace ViewInjectSample.Controllers
{
public class ProfileController : Controller
{
[Route("Profile")]
{
// TODO: look up profile based on logged-in user
var profile = new Profile()
{
Name = "Steve",
FavColor = "Blue",
Gender = "Male",
State = new State("Ohio","OH")
};
return View(profile);
}
}
}
O formulário HTML usado para atualizar essas preferências inclui listas suspensas para três das propriedades:
Essas listas são populadas por um serviço que foi injetado na exibição:
@using ViewInjectSample.Model.Services
@model ViewInjectSample.Model.Profile
@inject ProfileOptionsService Options
<!DOCTYPE html>
<html>
<head>
<title>Update Profile</title>
</head>
<body>
<div>
<h1>Update Profile</h1>
Name: @Html.TextBoxFor(m => m.Name)
<br/>
Gender: @Html.DropDownList("Gender",
Options.ListGenders().Select(g =>
new SelectListItem() { Text = g, Value = g }))
<br/>
State: @Html.DropDownListFor(m => m.State.Code,

Options.ListStates().Select(s =>
new SelectListItem() { Text = s.Name, Value = s.Code}))
<br />
Fav. Color: @Html.DropDownList("FavColor",

Options.ListColors().Select(c =>
new SelectListItem() { Text = c, Value = c }))
</div>
</body>
</html>
O ProfileOptionsService é um serviço no nível da interface do usuário criado para fornecer apenas os dados
necessários para esse formulário:
namespace ViewInjectSample.Model.Services
{
public class ProfileOptionsService
{
public List<string> ListGenders()
{
// keeping this simple
return new List<string>() {"Female", "Male"};
}
public List<State> ListStates()

{
// a few states from USA
return new List<State>()
{
new State("Alabama", "AL"),
new State("Alaska", "AK"),
new State("Ohio", "OH")
};
}
public List<string> ListColors()

{
return new List<string>() { "Blue","Green","Red","Yellow" };
}
}
}
IMPORTANT
Não se esqueça de registrar tipos que você solicita por meio de injeção de dependência no Startup.ConfigureServices .
Um tipo não registrado gera uma exceção em tempo de execução porque o provedor de serviços é consultado
internamente por meio de GetRequiredService.
Substituindo serviços
Além de injetar novos serviços, essa técnica também pode ser usada para substituir serviços injetados
anteriormente em uma página. A figura abaixo mostra todos os campos disponíveis na página usada no
primeiro exemplo:
Como você pode ver, os campos padrão incluem Html , Component e Url (bem como o StatsService que
injetamos). Se, para a instância, você desejava substituir os Auxiliares HTML padrão por seus próprios, faça isso
com facilidade usando @inject :
@using ViewInjectSample.Helpers
@inject MyHtmlHelper Html
<!DOCTYPE html>
<html>
<head>
<title>My Helper</title>
</head>
<body>
<div>
Test: @Html.Value
</div>
</body>
</html>
Se deseja estender os serviços existentes, basta usar essa técnica herdando da implementação existente ou
encapsulando-a com sua própria implementação.
Consulte também
Blog de Simon Timms: Getting Lookup Data Into Your View (Inserindo dados de pesquisa na exibição)
Lógica do controlador de teste no ASP.NET Core
Por Steve Smith

Controladores desempenham um papel central em qualquer aplicativo ASP.NET Core MVC. Assim, você precisa
estar confiante de que os controladores se comportarão conforme o esperado. Testes automatizados podem
detectar erros antes do aplicativo ser implantado em um ambiente de produção.
Testes de unidade da lógica do controlador

Os testes de unidade envolvem o teste de uma parte de um aplicativo isoladamente em relação à sua infraestrutura
e às suas dependências. Quando a unidade está testando a lógica do controlador, somente o conteúdo de uma
única ação é testada, não o comportamento de suas dependências ou da estrutura em si.
Configure testes de unidade de ações do controlador para se concentrarem no comportamento do controlador. Um
teste de unidade do controlador evita cenários como filtros, roteamento ou model binding. Os testes que abrangem
as interações entre os componentes que respondem coletivamente a uma solicitação são manipulados pelos testes
de integração. Para obter mais informações sobre os testes de integração, consulte Testes de integração no
ASP.NET Core.
Se você estiver escrevendo filtros e rotas personalizados, realize testes de unidade neles de forma isolada, não
como parte dos testes em uma ação do controlador específica.
Para demonstrar testes de unidade do controlador, examine o controlador a seguir no aplicativo de exemplo. O
controlador Home exibe uma lista de sessões de debate e permite que novas sessões sejam criadas com uma
solicitação POST:
{
private readonly IBrainstormSessionRepository _sessionRepository;
public HomeController(IBrainstormSessionRepository sessionRepository)

{
_sessionRepository = sessionRepository;
}

{
var sessionList = await _sessionRepository.ListAsync();
var model = sessionList.Select(session => new StormSessionViewModel()

{
Id = session.Id,
DateCreated = session.DateCreated,
Name = session.Name,
IdeaCount = session.Ideas.Count
});
return View(model);
}
public class NewSessionModel

{
[Required]
public string SessionName { get; set; }
}
[HttpPost]
public async Task<IActionResult> Index(NewSessionModel model)
{
{
}
else
{
await _sessionRepository.AddAsync(new BrainstormSession()
{
DateCreated = DateTimeOffset.Now,
Name = model.SessionName
});
}
return RedirectToAction(actionName: nameof(Index));

}
}
O controlador anterior:
Segue o Princípio de Dependências Explícitas.
Espera DI (injeção de dependência) para fornecer uma instância de IBrainstormSessionRepository .
Pode ser testado com um serviço IBrainstormSessionRepository fictício usando uma estrutura de objeto fictício,
como Moq. Um objeto fictício é um objeto fabricado com um conjunto predeterminado de comportamentos de
propriedade e de método usado para teste. Para saber mais, consulte Introdução aos testes de integração.
O método HTTP GET Index não tem nenhum loop ou branch e chama apenas um método. O teste de unidade para
esta ação:
Imita o serviço IBrainstormSessionRepository usando o método GetTestSessions . GetTestSessions cria duas
sessões de debate fictícias com datas e nomes de sessão.
Executa o método Index .
Faz declarações sobre o resultado retornado pelo método:
Um ViewResult é retornado.
O ViewDataDictionary.Model é um StormSessionViewModel .
Há duas sessões de debate armazenadas no ViewDataDictionary.Model .
[Fact]
public async Task Index_ReturnsAViewResult_WithAListOfBrainstormSessions()
{
// Arrange
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.ListAsync())
.ReturnsAsync(GetTestSessions());
var controller = new HomeController(mockRepo.Object);
// Act
var result = await controller.Index();
// Assert
var viewResult = Assert.IsType<ViewResult>(result);
var model = Assert.IsAssignableFrom<IEnumerable<StormSessionViewModel>>(
viewResult.ViewData.Model);
Assert.Equal(2, model.Count());
}
private List<BrainstormSession> GetTestSessions()

{
var sessions = new List<BrainstormSession>();
sessions.Add(new BrainstormSession()
{
DateCreated = new DateTime(2016, 7, 2),
Id = 1,
Name = "Test One"
});
{
Id = 2,
Name = "Test Two"
});
return sessions;
}
Os testes método HTTP POST Index do controlador Home verificam se:

Quando ModelState.IsValid é false , o método de ação retorna uma 400 Solicitação inválida ViewResult com
os dados apropriados.
Quando ModelState.IsValid é true :
O método Add no repositório é chamado.
Um RedirectToActionResult é retornado com os argumentos corretos.
O estado de modelo inválido é testado por meio da adição de erros usando AddModelError, conforme mostrado
no primeiro teste abaixo:
[Fact]
public async Task IndexPost_ReturnsBadRequestResult_WhenModelStateIsInvalid()
{
// Arrange
controller.ModelState.AddModelError("SessionName", "Required");
var newSession = new HomeController.NewSessionModel();
// Act
var result = await controller.Index(newSession);
// Assert
var badRequestResult = Assert.IsType<BadRequestObjectResult>(result);
Assert.IsType<SerializableError>(badRequestResult.Value);
}
[Fact]
public async Task IndexPost_ReturnsARedirectAndAddsSession_WhenModelStateIsValid()
{
// Arrange
mockRepo.Setup(repo => repo.AddAsync(It.IsAny<BrainstormSession>()))
.Returns(Task.CompletedTask)
.Verifiable();
var newSession = new HomeController.NewSessionModel()
{
SessionName = "Test Name"
};
// Act
// Assert
var redirectToActionResult = Assert.IsType<RedirectToActionResult>(result);
Assert.Null(redirectToActionResult.ControllerName);
Assert.Equal("Index", redirectToActionResult.ActionName);
mockRepo.Verify();
}
Quando ModelState não for válido, o mesmo ViewResult será retornado para uma solicitação GET. O teste não
tenta passar um modelo inválido. Passar um modelo inválido não é uma abordagem válida, visto que o model
binding não está em execução (embora um teste de integração use model binding). Nesse caso, o model binding
não está sendo testado. Esses testes de unidade estão testando apenas o código no método de ação.
O segundo teste verifica se, quando o ModelState é válido:
Um novo BrainstormSession é adicionado (por meio do repositório).
O método retorna um RedirectToActionResult com as propriedades esperadas.
Chamadas fictícias que não são chamadas são normalmente ignoradas, mas a chamada a Verifiable no final da
chamada de instalação permite a validação fictícia no teste. Isso é realizado com a chamada a mockRepo.Verify , que
não será aprovada no teste se o método esperado não tiver sido chamado.
NOTE
A biblioteca do Moq usada neste exemplo possibilita a combinação de simulações verificáveis ou "estritas" com simulações
não verificáveis (também chamadas de simulações "flexíveis" ou stubs). Saiba mais sobre como personalizar o comportamento
de Simulação com o Moq.
SessionController no exemplo de aplicativo exibe informações relacionadas a uma sessão de debate específica. O
controlador inclui lógica para lidar com valores id inválidos (há dois cenários return no exemplo a seguir para
abordar esses cenários). A última instrução return retorna um novo StormSessionViewModel para a exibição
(Controllers/SessionController.cs):
public class SessionController : Controller

{
public SessionController(IBrainstormSessionRepository sessionRepository)

{
}
public async Task<IActionResult> Index(int? id)

{
if (!id.HasValue)
{
return RedirectToAction(actionName: nameof(Index),
controllerName: "Home");
}
var session = await _sessionRepository.GetByIdAsync(id.Value);

if (session == null)
{
return Content("Session not found.");
}
var viewModel = new StormSessionViewModel()

{
Id = session.Id
};
}
}
Os testes de unidade incluem um teste para cada cenário return na ação Index do controlador Session:
[Fact]
public async Task IndexReturnsARedirectToIndexHomeWhenIdIsNull()
{
// Arrange
var controller = new SessionController(sessionRepository: null);
// Act
var result = await controller.Index(id: null);
// Assert
var redirectToActionResult =
Assert.IsType<RedirectToActionResult>(result);
Assert.Equal("Home", redirectToActionResult.ControllerName);
}
[Fact]
public async Task IndexReturnsContentWithSessionNotFoundWhenSessionNotFound()
{
// Arrange
int testSessionId = 1;
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync((BrainstormSession)null);
var controller = new SessionController(mockRepo.Object);
// Act
var result = await controller.Index(testSessionId);
// Assert
var contentResult = Assert.IsType<ContentResult>(result);
Assert.Equal("Session not found.", contentResult.Content);
}
[Fact]
public async Task IndexReturnsViewResultWithStormSessionViewModel()
{
// Arrange
.ReturnsAsync(GetTestSessions().FirstOrDefault(
s => s.Id == testSessionId));
// Act
// Assert
var model = Assert.IsType<StormSessionViewModel>(
Assert.Equal("Test One", model.Name);
Assert.Equal(2, model.DateCreated.Day);
Assert.Equal(testSessionId, model.Id);
}
Mudando para o controlador Ideas, o aplicativo expõe a funcionalidade como uma API Web na rota api/ideas :
Uma lista de ideias ( IdeaDTO ) associada com uma sessão de debate é retornada pelo método ForSession .
O método Create adiciona novas ideias a uma sessão.
[HttpGet("forsession/{sessionId}")]
public async Task<IActionResult> ForSession(int sessionId)
{
var session = await _sessionRepository.GetByIdAsync(sessionId);
{
return NotFound(sessionId);
}
var result = session.Ideas.Select(idea => new IdeaDTO()

{
Id = idea.Id,
Name = idea.Name,
Description = idea.Description,
DateCreated = idea.DateCreated
}).ToList();
return Ok(result);
}
[HttpPost("create")]
public async Task<IActionResult> Create([FromBody]NewIdeaModel model)
{
{
}
var session = await _sessionRepository.GetByIdAsync(model.SessionId);

{
return NotFound(model.SessionId);
}
var idea = new Idea()

{
Description = model.Description,
Name = model.Name
};
session.AddIdea(idea);
await _sessionRepository.UpdateAsync(session);
return Ok(session);
}
Evite retornar entidades de domínio de negócios diretamente por meio de chamadas à API. Entidades de domínio:
Geralmente incluem mais dados do que o cliente necessita.
Acople desnecessariamente o modelo de domínio interno do aplicativo à API exposta publicamente.
É possível executar o mapeamento entre entidades de domínio e os tipos retornados ao cliente:
Manualmente com um LINQ Select , como o aplicativo de exemplo usa. Para saber mais, consulte LINQ
(Consulta Integrada à Linguagem).
Automaticamente com uma biblioteca, como AutoMapper.
Em seguida, o aplicativo de exemplo demonstra os testes de unidade para os métodos de API Create e
ForSession do controlador Ideas.
O aplicativo de exemplo contém dois testes ForSession . O primeiro teste determina se ForSession retorna um
NotFoundObjectResult (HTTP não encontrado) para uma sessão inválida:
[Fact]
public async Task ForSession_ReturnsHttpNotFound_ForInvalidSession()
{
// Arrange
var controller = new IdeasController(mockRepo.Object);
// Act
var result = await controller.ForSession(testSessionId);
// Assert
var notFoundObjectResult = Assert.IsType<NotFoundObjectResult>(result);
Assert.Equal(testSessionId, notFoundObjectResult.Value);
}
O segundo teste ForSession determina se ForSession retorna uma lista de ideias de sessão ( <List<IdeaDTO>> )
para uma sessão válida. As verificações também examinam a primeira ideia para confirmar se sua propriedade
Name está correta:
[Fact]
public async Task ForSession_ReturnsIdeasForSession()
{
// Arrange
.ReturnsAsync(GetTestSession());
// Act
// Assert
var okResult = Assert.IsType<OkObjectResult>(result);
var returnValue = Assert.IsType<List<IdeaDTO>>(okResult.Value);
var idea = returnValue.FirstOrDefault();
Assert.Equal("One", idea.Name);
}
Para testar o comportamento do método Create quando o ModelState é inválido, o aplicativo de exemplo
adiciona um erro de modelo ao controlador como parte do teste. Não tente testar a validação de modelos ou o
model binding em testes de unidade—teste apenas o comportamento do método de ação quando houver um
ModelState inválido:
[Fact]
public async Task Create_ReturnsBadRequest_GivenInvalidModel()
{
// Arrange & Act
controller.ModelState.AddModelError("error", "some error");
// Act
var result = await controller.Create(model: null);
// Assert
Assert.IsType<BadRequestObjectResult>(result);
}
O segundo teste de Create depende do repositório retornar null , portanto, o repositório fictício é configurado
para retornar null . Não é necessário criar um banco de dados de teste (na memória ou de outro tipo) e construir
uma consulta que retornará esse resultado. O teste pode ser realizado em uma única instrução, como mostrado no
código de exemplo:
[Fact]
public async Task Create_ReturnsHttpNotFound_ForInvalidSession()
{
// Arrange
// Act
var result = await controller.Create(new NewIdeaModel());
// Assert
Assert.IsType<NotFoundObjectResult>(result);
}
O terceiro teste Create , Create_ReturnsNewlyCreatedIdeaForSession , verifica se o método UpdateAsync do

repositório é chamado. A simulação é chamada com Verifiable e o método Verify do repositório fictício é
chamado para confirmar se o método verificável é executado. Não é responsabilidade do teste de unidade garantir
que o método UpdateAsync salve os dados—isso pode ser realizado com um teste de integração.
[Fact]
public async Task Create_ReturnsNewlyCreatedIdeaForSession()
{
// Arrange
string testName = "test name";
string testDescription = "test description";
var testSession = GetTestSession();
.ReturnsAsync(testSession);
var newIdea = new NewIdeaModel()

{
Description = testDescription,
Name = testName,
SessionId = testSessionId
};
mockRepo.Setup(repo => repo.UpdateAsync(testSession))
.Verifiable();
// Act
var result = await controller.Create(newIdea);
// Assert
var returnSession = Assert.IsType<BrainstormSession>(okResult.Value);
mockRepo.Verify();
Assert.Equal(2, returnSession.Ideas.Count());
Assert.Equal(testName, returnSession.Ideas.LastOrDefault().Name);
Assert.Equal(testDescription, returnSession.Ideas.LastOrDefault().Description);
}
Testar ActionResult<T>
No ASP.NET Core 2.1 ou posterior, o ActionResult<T> (ActionResult<TValue>) permite que você retorne um tipo
derivado de ActionResult ou retorne um tipo específico.
O aplicativo de exemplo inclui um método que retorna um List<IdeaDTO> para uma sessão id determinada. Se a
sessão id não existir, o controlador retornará NotFound:
[HttpGet("forsessionactionresult/{sessionId}")]
[ProducesResponseType(200)]
public async Task<ActionResult<List<IdeaDTO>>> ForSessionActionResult(int sessionId)
{
{
}

{
Id = idea.Id,
Name = idea.Name,
}).ToList();
return result;
}
Dois testes do controlador ForSessionActionResult estão incluídos no ApiIdeasControllerTests .

O primeiro teste confirma se o controlador retorna um ActionResult , mas não uma lista de ideias inexistente para
uma sessão id inexistente:
O tipo ActionResult<List<IdeaDTO>> é ActionResult .
O Result é um NotFoundObjectResult.
[Fact]
public async Task ForSessionActionResult_ReturnsNotFoundObjectResultForNonexistentSession()
{
// Arrange
var nonExistentSessionId = 999;
// Act
var result = await controller.ForSessionActionResult(nonExistentSessionId);
// Assert
var actionResult = Assert.IsType<ActionResult<List<IdeaDTO>>>(result);
Assert.IsType<NotFoundObjectResult>(actionResult.Result);
}
Para uma sessão id válida, o segundo teste confirma se o método retorna:

Um ActionResult com um tipo List<IdeaDTO> .
O ActionResult<T>.Value é um tipo List<IdeaDTO> .
O primeiro item na lista é uma ideia válida que corresponde à ideia armazenada na sessão fictícia (obtida
chamando GetTestSession ).
[Fact]
public async Task ForSessionActionResult_ReturnsIdeasForSession()
{
// Arrange
// Act
var result = await controller.ForSessionActionResult(testSessionId);
// Assert
var returnValue = Assert.IsType<List<IdeaDTO>>(actionResult.Value);
}
O aplicativo de exemplo também inclui um método para criar um novo Idea para uma determinada sessão. O
controlador retorna:
BadRequest para um modelo inválido.
NotFound se a sessão não existir.
CreatedAtAction quando a sessão for atualizada com a nova ideia.
[HttpPost("createactionresult")]
public async Task<ActionResult<BrainstormSession>> CreateActionResult([FromBody]NewIdeaModel model)
{
{
}
{
}

{
Name = model.Name
};
return CreatedAtAction(nameof(CreateActionResult), new { id = session.Id }, session);

}
Três testes CreateActionResult estão incluídos no ApiIdeasControllerTests .

O primeiro texto confirma que um BadRequest é retornado para um modelo inválido.
[Fact]
public async Task CreateActionResult_ReturnsBadRequest_GivenInvalidModel()
{
// Arrange & Act
// Act
var result = await controller.CreateActionResult(model: null);
// Assert
var actionResult = Assert.IsType<ActionResult<BrainstormSession>>(result);
Assert.IsType<BadRequestObjectResult>(actionResult.Result);
}
O segundo teste verifica se um NotFound será retornado se a sessão não existir.
[Fact]
public async Task CreateActionResult_ReturnsNotFoundObjectResultForNonexistentSession()
{
// Arrange

{
Name = testName,
SessionId = nonExistentSessionId
};
// Act
var result = await controller.CreateActionResult(newIdea);
// Assert
}
Para uma sessão id válida, o teste final confirmará se:

O método retorna um ActionResult com um tipo BrainstormSession .
O ActionResult<T>.Result é um CreatedAtActionResult. CreatedAtActionResult é semelhante à resposta 201
Criado com um cabeçalho Location .
O ActionResult<T>.Value é um tipo BrainstormSession .
A chamada fictícia para atualizar a sessão, UpdateAsync(testSession) , foi invocada. A chamada de método
Verifiable é verificada por meio da execução de mockRepo.Verify() nas declarações.
Dois objetos Idea são retornados para a sessão.
O último item (o Idea adicionado pela chamada fictícia a UpdateAsync ) corresponde ao newIdea adicionado à
sessão no teste.
[Fact]
public async Task CreateActionResult_ReturnsNewlyCreatedIdeaForSession()
{
// Arrange

{
Name = testName,
};
.Verifiable();
// Act
// Assert
var createdAtActionResult = Assert.IsType<CreatedAtActionResult>(actionResult.Result);
var returnValue = Assert.IsType<BrainstormSession>(createdAtActionResult.Value);
mockRepo.Verify();
Assert.Equal(2, returnValue.Ideas.Count());
Assert.Equal(testName, returnValue.Ideas.LastOrDefault().Name);
Assert.Equal(testDescription, returnValue.Ideas.LastOrDefault().Description);
}
Recursos adicionais
<xref:test/index>
Testes de integração no ASP.NET Core
Crie e execute testes de unidade com o Visual Studio.
Estado de sessão e aplicativo no ASP.NET Core
Por Rick Anderson, Steve Smith, Diana LaRose e Luke Latham

O HTTP é um protocolo sem estado. Sem realizar etapas adicionais, as solicitações HTTP são mensagens
independentes que não mantêm os valores de usuário nem o estado do aplicativo. Este artigo descreve várias
abordagens para preservar dados do usuário e estado de aplicativo entre solicitações.
Gerenciamento de estado
O estado pode ser armazenado usando várias abordagens. Cada abordagem é descrita posteriormente neste
tópico.
ABORDAGEM DE ARMAZENAMENTO MECANISMO DE ARMAZENAMENTO
Cookies Cookies HTTP (podem incluir dados armazenados usando o

código de aplicativo do lado do servidor)
Estado de sessão Cookies HTTP e o código de aplicativo do lado do servidor
TempData Estado de sessão ou cookies HTTP
Cadeias de consulta Cadeias de caracteres de consulta HTTP
Campos ocultos Campos de formulário HTTP
HttpContext.Items Código do aplicativo do lado do servidor
Cache Código do aplicativo do lado do servidor
Injeção de dependência Código do aplicativo do lado do servidor
Cookies
Cookies armazenam dados entre solicitações. Como os cookies são enviados com cada solicitação, seu tamanho
deve ser reduzido ao mínimo. Idealmente, somente um identificador deve ser armazenado em um cookie com os
dados armazenados pelo aplicativo. A maioria dos navegadores restringe o tamanho do cookie a 4.096 bytes.
Somente um número limitado de cookies está disponível para cada domínio.
Uma vez que os cookies estão sujeitos à adulteração, eles devem ser validados pelo aplicativo. Os cookies podem
ser excluídos por usuários e expirarem em clientes. No entanto, os cookies geralmente são a forma mais durável
de persistência de dados no cliente.
Frequentemente, cookies são usados para personalização quando o conteúdo é personalizado para um usuário
conhecido. O usuário é apenas identificado, e não autenticado, na maioria dos casos. O cookie pode armazenar o
nome do usuário, o nome da conta ou a ID de usuário único (como um GUID ). Você pode usar o cookie para
acessar as configurações personalizadas do usuário, como cor preferida da tela de fundo do site.
Esteja ciente do RGPD (Regulamento Geral sobre a Proteção de Dados) da União Europeia ao emitir cookies e
lidar com questões de privacidade. Para obter mais informações, veja Suporte ao RGPD (Regulamento Geral
sobre a Proteção de Dados) no ASP.NET Core.
Estado de sessão
Estado de sessão é um cenário do ASP.NET Core para o armazenamento de dados de usuário enquanto o usuário
procura um aplicativo Web. Estado de sessão usa um armazenamento mantido pelo aplicativo para que os dados
persistam entre solicitações de um cliente. Os dados da sessão são apoiados por um cache e considerados dados
efêmeros—o site deve continuar funcionando sem os dados da sessão.
NOTE
A sessão não é compatível com os aplicativos SignalR porque um Hub SignalR pode ser executado independente de um
contexto HTTP. Por exemplo, isso pode ocorrer quando uma solicitação de sondagem longa é mantida aberta por um hub
além do tempo de vida do contexto HTTP da solicitação.
O ASP.NET Core mantém o estado de sessão fornecendo um cookie para o cliente que contém uma ID de sessão,
que é enviada para o aplicativo com cada solicitação. O aplicativo usa a ID da sessão para buscar os dados da
sessão.
Estado de sessão exibe os seguintes comportamentos:
Uma vez que o cookie da sessão é específico ao navegador, não é possível compartilhar sessões entre
navegadores.
Cookies da sessão são excluídos quando a sessão do navegador termina.
Se um cookie for recebido de uma sessão expirada, será criada uma nova sessão que usa o mesmo cookie de
sessão.
Sessões vazias não são mantidas—a sessão deve ter pelo menos um valor definido nela para que mantenha a
sessão entre solicitações. Quando uma sessão não é mantida, uma nova ID de sessão é gerada para cada nova
solicitação.
O aplicativo mantém uma sessão por um tempo limitado após a última solicitação. O aplicativo define o tempo
limite da sessão ou usa o valor padrão de 20 minutos. Estado de sessão é ideal para armazenar dados de
usuário específicos para uma sessão em particular, mas em que os dados não requerem armazenamento
permanente entre sessões.
Dados da sessão são excluídos quando a implementação ISession.Clear é chamada ou quando a sessão expira.
Não há nenhum mecanismo padrão para informar o código do aplicativo de que um navegador cliente foi
fechado ou quando o cookie de sessão foi excluído ou expirou no cliente.
WARNING
Não armazene dados confidenciais no estado de sessão. O usuário não pode fechar o navegador e limpar o cookie de
sessão. Alguns navegadores mantêm cookies de sessão válidos entre as janelas do navegador. Uma sessão não pode ser
restringida a um único usuário—o próximo usuário pode continuar a procurar o aplicativo com o mesmo cookie de sessão.
O provedor de cache na memória armazena dados de sessão na memória do servidor em que o aplicativo reside.
Em um cenário de farm de servidores:
Use sessões persistentes para vincular cada sessão a uma instância de aplicativo específico em um servidor
individual. O Serviço de Aplicativo do Azure usa o ARR (Application Request Routing) para impor as sessões
persistentes por padrão. Entretanto, sessões autoadesivas podem afetar a escalabilidade e complicar
atualizações de aplicativos Web. Uma abordagem melhor é usar um Redis ou cache distribuído do SQL Server,
que não requer sessões persistentes. Para obter mais informações, consulte O cache no ASP.NET Core
distribuído.
O cookie de sessão é criptografado por meio de IDataProtector. A Proteção de Dados deve ser configurada
corretamente para ler os cookies de sessão em cada computador. Para obter mais informações, veja Proteção
de dados no ASP.NET Core e Provedores de armazenamento de chaves.
Configurar o estado de sessão
O pacote Microsoft.AspNetCore.Session, incluído no metapacote Microsoft.AspNetCore.App, fornece middleware
para gerenciar o estado de sessão. Para habilitar o middleware da sessão, Startup deve conter:
O pacote Microsoft.AspNetCore.Session fornece middleware para gerenciar o estado de sessão. Para habilitar o
middleware da sessão, Startup deve conter:
Qualquer um dos caches de memória IDistributedCache. A implementação IDistributedCache é usada como
um repositório de backup para a sessão. Para obter mais informações, consulte O cache no ASP.NET Core
distribuído.
Uma chamada para AddSession em ConfigureServices .
Uma chamada para UseSession em Configure .
O código a seguir mostra como configurar o provedor de sessão na memória com uma implementação padrão na
memória de IDistributedCache :
{
{
{
});
services.AddDistributedMemoryCache();
services.AddSession(options =>
{
// Set a short timeout for easy testing.
options.IdleTimeout = TimeSpan.FromSeconds(10);
options.Cookie.HttpOnly = true;
});
services.AddMvc()
}

{
{
}
else
{
app.UseHsts();
}
app.UseSession();
app.UseHttpContextItemsMiddleware();
app.UseMvc();
}
}
{
{
{
// Set a short timeout for easy testing.
options.CookieHttpOnly = true;
});
services.AddMvc();
}

{
app.UseSession();
app.UseHttpContextItemsMiddleware();
{
routes.MapRoute(
name: "default",
});
}
}
A ordem do middleware é importante. No exemplo anterior, uma exceção InvalidOperationException ocorre

quando UseSession é invocado após UseMvc . Para obter mais informações, veja Ordenação de Middleware.
HttpContext.Session estará disponível depois que o estado de sessão for configurado.
HttpContext.Session não pode ser acessado antes que UseSession tenha sido chamado.
Não é possível criar uma nova sessão com um novo cookie de sessão depois que o aplicativo começou a gravar
no fluxo de resposta. A exceção é registrada no log do servidor Web e não é exibida no navegador.
Carregue o estado de sessão de maneira assíncrona
O provedor de sessão padrão no ASP.NET Core carregará os registros da sessão do repositório de backup
IDistributedCache subjacente de maneira assíncrona somente se o método ISession.LoadAsync for chamado
explicitamente antes dos métodos TryGetValue, Set ou Remove. Se LoadAsync não for chamado primeiro, o
registro de sessão subjacente será carregado de maneira síncrona, o que pode incorrer em uma penalidade de
desempenho em escala.
Para que aplicativos imponham esse padrão, encapsule as implementações DistributedSessionStore e
DistributedSession com versões que geram uma exceção se o método LoadAsync não for chamado antes de
TryGetValue , Set ou Remove . Registre as versões encapsuladas no contêiner de serviços.
Opções da sessão
Para substituir os padrões da sessão, use SessionOptions.
OPÇÃO DESCRIÇÃO
OPÇÃO DESCRIÇÃO
Cookie Determina as configurações usadas para criar o cookie. Name

assume como padrão SessionDefaults.CookieName (
.AspNetCore.Session ). Path assume como padrão
SessionDefaults.CookiePath ( / ). SameSite assume como
padrão SameSiteMode.Lax ( 1 ). HttpOnly assume true
como padrão . IsEssential assume false como padrão.
IdleTimeout O IdleTimeout indica por quanto tempo a sessão pode ficar

ociosa antes de seu conteúdo ser abandonado. Cada acesso à
sessão redefine o tempo limite. Essa configuração aplica-se
somente ao conteúdo da sessão, não ao cookie. O padrão é
de 20 minutos.
IOTimeout O tempo máximo permitido para carregar uma sessão do

repositório ou para confirmá-la de volta para o repositório.
Essa configuração pode se aplicar somente a operações
assíncronas. Esse tempo limite pode ser desabilitado usando
InfiniteTimeSpan. O padrão é 1 minuto.
A sessão usa um cookie para rastrear e identificar solicitações de um único navegador. Por padrão, esse cookie se
chama .AspNetCore.Session , e usa um caminho de / . Uma vez que o padrão do cookie não especifica um
domínio, ele não fica disponível para o script do lado do cliente na página (porque HttpOnly usa true como
padrão).
OPÇÃO DESCRIÇÃO
CookieDomain Determina o domínio usado para criar o cookie.

CookieDomain não é definido por padrão.
CookieHttpOnly Determina se o navegador deve permitir que o cookie seja

acessado pelo JavaScript do lado do cliente. O padrão é
true , o que significa que o cookie é transmitido apenas às
solicitações HTTP e não é disponibilizado para o script na
página.
CookieName Determina o nome do cookie usado para manter a ID da

sessão. O padrão é SessionDefaults.CookieName (
.AspNetCore.Session ).
CookiePath Determina o caminho usado para criar o cookie. Usa como

padrão SessionDefaults.CookiePath ( / ).
CookieSecure Determina se o cookie deve ser transmitido apenas em

solicitações HTTPS. O padrão é CookieSecurePolicy.None ( 2 ).
IdleTimeout O IdleTimeout indica por quanto tempo a sessão pode ficar

ociosa antes de seu conteúdo ser abandonado. Cada acesso à
sessão redefine o tempo limite. Observe que isso só se aplica
ao conteúdo da sessão, não o cookie. O padrão é de 20
minutos.
A sessão usa um cookie para rastrear e identificar solicitações de um único navegador. Por padrão, esse cookie se
chama .AspNet.Session , e usa um caminho de / .
Para substituir os padrões de sessão do cookie, use SessionOptions :
{
{
});
services.AddMvc()
{
options.Cookie.Name = ".AdventureWorks.Session";
});
}

{
{
options.CookieName = ".AdventureWorks.Session";
});
services.AddMvc();
}
O aplicativo usa a propriedade IdleTimeout para determinar por quanto tempo uma sessão pode ficar ociosa
antes de seu conteúdo no cache do servidor ser abandonado. Essa propriedade é independente da expiração do
cookie. Cada solicitação que passa pelo Middleware da Sessão redefine o tempo limite.
Estado de sessão é sem bloqueio. Se duas solicitações tentarem simultaneamente modificar o conteúdo de uma
sessão, a última solicitação substituirá a primeira. Session é implementado como uma sessão coerente, o que
significa que todo o conteúdo é armazenado junto. Quando duas solicitações buscam modificar valores de sessão
diferentes, a última solicitação pode substituir as alterações de sessão feitas pelo primeira.
Definir e obter valores de Session
Estado de sessão é acessado de uma classe PageModel Razor Pages ou classe Controlador MVC com
HttpContext.Session. Esta propriedade é uma implementação de ISession.
A implementação de ISession fornece vários métodos de extensão para definir e recuperar valores de inteiro e
cadeia de caracteres. Os métodos de extensão estão no namespace Microsoft.AspNetCore.Http (adicione uma
instrução using Microsoft.AspNetCore.Http; para acessar os métodos de extensão) quando o pacote
Microsoft.AspNetCore.Http.Extensions for referenciado pelo projeto. Ambos os pacotes são incluídos no
metapacote Microsoft.AspNetCore.App.
A implementação de ISession fornece vários métodos de extensão para definir e recuperar valores de inteiro e
cadeia de caracteres. Os métodos de extensão estão no namespace Microsoft.AspNetCore.Http (adicione uma
instrução using Microsoft.AspNetCore.Http; para acessar os métodos de extensão) quando o pacote
Microsoft.AspNetCore.Http.Extensions for referenciado pelo projeto.
Métodos de extensão ISession :
Get(ISession, String)
GetInt32(ISession, String)
GetString(ISession, String)
SetInt32(ISession, String, Int32)
SetString(ISession, String, String)
O exemplo a seguir recupera o valor da sessão para a chave IndexModel.SessionKeyName ( _Name no aplicativo de
exemplo) em uma página do Razor Pages:
@page
@using Microsoft.AspNetCore.Http
@model IndexModel
...
Name: @HttpContext.Session.GetString(IndexModel.SessionKeyName)
O exemplo a seguir mostra como definir e obter um número inteiro e uma cadeia de caracteres:

{
public const string SessionKeyName = "_Name";
public const string SessionKeyAge = "_Age";
const string SessionKeyTime = "_Time";
public string SessionInfo_Name { get; private set; }

public string SessionInfo_Age { get; private set; }
public string SessionInfo_CurrentTime { get; private set; }
public string SessionInfo_SessionTime { get; private set; }
public string SessionInfo_MiddlewareValue { get; private set; }
public void OnGet()

{
// Requires: using Microsoft.AspNetCore.Http;
if (string.IsNullOrEmpty(HttpContext.Session.GetString(SessionKeyName)))
{
HttpContext.Session.SetString(SessionKeyName, "The Doctor");
HttpContext.Session.SetInt32(SessionKeyAge, 773);
}
var name = HttpContext.Session.GetString(SessionKeyName);

var age = HttpContext.Session.GetInt32(SessionKeyAge);
{
const string SessionKeyName = "_Name";
const string SessionKeyYearsMember = "_YearsMember";
const string SessionKeyDate = "_Date";

{
// Requires using Microsoft.AspNetCore.Http;
HttpContext.Session.SetString(SessionKeyName, "Rick");
HttpContext.Session.SetInt32(SessionKeyYearsMember, 3);
return RedirectToAction("SessionNameYears");
}
public IActionResult SessionNameYears()

{
var name = HttpContext.Session.GetString(SessionKeyName);
var yearsMember = HttpContext.Session.GetInt32(SessionKeyYearsMember);
return Content($"Name: \"{name}\", Membership years: \"{yearsMember}\"");

}
Todos os dados de sessão devem ser serializados para habilitar um cenário de cache distribuído, mesmo ao usar o
cache na memória. Cadeia de caracteres mínima e serializadores número são fornecidos (confira os métodos e os
métodos de extensão de ISession). Tipos complexos devem ser serializados pelo usuário por meio de outro
mecanismo, como JSON.
Adicione os seguintes métodos de extensão para definir e obter objetos serializáveis:
public static class SessionExtensions

{
public static void Set<T>(this ISession session, string key, T value)
{
session.SetString(key, JsonConvert.SerializeObject(value));
}
public static T Get<T>(this ISession session, string key)

{
var value = session.GetString(key);
return value == null ? default(T) :

JsonConvert.DeserializeObject<T>(value);
}
}
public static class SessionExtensions

{
public static void Set<T>(this ISession session, string key, T value)
{
session.SetString(key, JsonConvert.SerializeObject(value));
}
public static T Get<T>(this ISession session,string key)

{
var value = session.GetString(key);
return value == null ? default(T) :
JsonConvert.DeserializeObject<T>(value);
}
}
O exemplo a seguir mostra como definir e obter um objeto serializável com os métodos de extensão:
// Requires you add the Set and Get extension method mentioned in the topic.
if (HttpContext.Session.Get<DateTime>(SessionKeyTime) == default(DateTime))
{
HttpContext.Session.Set<DateTime>(SessionKeyTime, currentTime);
}
public IActionResult SetDate()

{
// Requires you add the Set extension method mentioned in the topic.
HttpContext.Session.Set<DateTime>(SessionKeyDate, DateTime.Now);
return RedirectToAction("GetDate");
}
public IActionResult GetDate()

{
// Requires you add the Get extension method mentioned in the topic.
var date = HttpContext.Session.Get<DateTime>(SessionKeyDate);
var sessionTime = date.TimeOfDay.ToString();
var currentTime = DateTime.Now.TimeOfDay.ToString();
return Content($"Current time: {currentTime} - "

+ $"session time: {sessionTime}");
}
TempData
O ASP.NET Core expõe a propriedade TempData de um modelo de página do Razor Pages ou TempData de um
controlador MVC. Essa propriedade armazena dados até eles serem lidos. Os métodos Keep e Peek podem ser
usados para examinar os dados sem exclusão. TempData é particularmente útil para redirecionamento em casos
em que são necessários dados para mais de uma única solicitação. TempData é implementado por provedores de
TempData usando cookies ou estado de sessão.
Provedores de TempData
No ASP.NET Core 2.0 ou posterior, o provedor TempData baseado em cookies é usado por padrão para
armazenar TempData em cookies.
Os dados do cookie são criptografados usando IDataProtector, codificado com Base64UrlTextEncoder, em
seguida, em partes. Como o cookie é dividido em partes, o limite de tamanho de cookie único encontrado no
ASP.NET Core 1.x não se aplica. Os dados do cookie não são compactados porque a compactação de dados
criptografados pode levar a problemas de segurança, como os ataques CRIME e BREACH. Para obter mais
informações sobre o provedor de TempData baseado em cookie, consulte CookieTempDataProvider.
No ASP.NET Core 1.0 e 1.1, o provedor de TempData do estado de sessão é o provedor padrão.
Escolha um provedor de TempData
Escolher um provedor de TempData envolve várias considerações, como:
1. O aplicativo já usa estado de sessão? Se for o caso, usar o provedor de TempData do estado de sessão não terá
custos adicionais para o aplicativo (além do tamanho dos dados).
2. O aplicativo usa TempData apenas raramente para quantidades relativamente pequenas de dados (até 500
bytes)? Em caso afirmativo, o provedor de TempData do cookie adiciona um pequeno custo a cada solicitação
que transportar TempData. Caso contrário, o provedor de TempData do estado de sessão pode ser útil para
evitar fazer viagens de ida e volta para uma grande quantidade de dados a cada solicitação até que TempData
seja consumido.
3. O aplicativo é executado em um farm de servidores em vários servidores? Se for o caso, não será necessária
nenhuma configuração adicional para usar o provedor TempData do cookie fora da Proteção de Dados
(confira Proteção de Dados e Provedores de armazenamento de chaves).
NOTE
A maioria dos clientes da Web (como navegadores da Web) impõem limites quanto ao tamanho máximo de cada cookie, o
número total de cookies ou ambos. Ao usar o provedor TempData do cookie, verifique se o aplicativo não ultrapassará esses
limites. Considere o tamanho total dos dados. Conta para aumento no tamanho de cookie devido à criptografia e ao
agrupamento.
Configurar o provedor de TempData

O provedor de TempData baseado em cookie é habilitado por padrão.
Para habilitar o provedor TempData baseado em sessão, use o método de extensão
AddSessionStateTempDataProvider:

{
{
});
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_1)
.AddSessionStateTempDataProvider();
services.AddSession();
}

{
{
}
else
{
app.UseHsts();
}
app.UseSession();
app.UseMvc();
}
O código da classe Startup a seguir configura o provedor de TempData baseado em sessão:

{
services.AddMvc();
services.AddSession();
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)

{
app.UseSession();
{
routes.MapRoute(
name: "default",
});
}
A ordem do middleware é importante. No exemplo anterior, uma exceção InvalidOperationException ocorre

quando UseSession é invocado após UseMvc . Para obter mais informações, veja Ordenação de Middleware.
IMPORTANT
Se o alvo for o .NET Framework e o provedor TempData baseado em sessão for usado, adicione o pacote
Microsoft.AspNetCore.Session ao projeto.
Cadeias de consulta
É possível passar uma quantidade limitada de dados de uma solicitação para outra adicionando-a à cadeia de
caracteres de consulta da nova solicitação. Isso é útil para capturar o estado de uma maneira persistente que
permita que links com estado inserido sejam compartilhados por email ou por redes sociais. Uma vez que cadeias
de consulta de URL são públicas, nunca use cadeias de consulta para dados confidenciais.
Além da possibilidade de ocorrência de compartilhamento não intencional, incluir dados em cadeias de consulta
pode criar oportunidades para ataques de CSRF (solicitação intersite forjada), que podem enganar os usuários
para que eles visitem sites mal-intencionados enquanto estão autenticados. Invasores então podem roubar dados
do usuário do aplicativo ou executar ações mal-intencionadas em nome do usuário. Qualquer estado de sessão ou
aplicativo preservado deve se proteger contra ataques CSRF. Para obter mais informações, confira Impedir
ataques de XSRF/CSRF (solicitação intersite forjada).
Campos ocultos
Dados podem ser salvos em campos de formulário ocultos e postados novamente na solicitação seguinte. Isso é
comum em formulários com várias páginas. Uma vez que o cliente potencialmente pode adulterar os dados, o
aplicativo deve sempre revalidar os dados armazenados nos campos ocultos.
HttpContext.Items
A coleção HttpContext.Items é usada para armazenar dados durante o processamento de uma única solicitação. O
conteúdo da coleção é descartado após uma solicitação ser processada. A coleção Items costuma ser usada para
permitir que componentes ou middleware se comuniquem quando operam em diferentes momentos durante
uma solicitação e não têm nenhuma maneira direta de passar parâmetros.
No exemplo a seguir, middleware adiciona isVerified à coleção Items .
{
// perform some verification
context.Items["isVerified"] = true;
});
Mais tarde no pipeline, outro middleware poderá acessar o valor de isVerified :

{
await context.Response.WriteAsync($"Verified: {context.Items["isVerified"]}");
});
Para middleware usado apenas por um único aplicativo, chaves string são aceitáveis. Middleware
compartilhado entre instâncias do aplicativo deve usar chaves de objeto únicas para evitar colisões de chaves. O
exemplo a seguir mostra como usar uma chave de objeto exclusiva definida em uma classe de middleware:
public class HttpContextItemsMiddleware

{
public static readonly object HttpContextItemsMiddlewareKey = new Object();
public HttpContextItemsMiddleware(RequestDelegate next)

{
_next = next;
}

{
httpContext.Items[HttpContextItemsMiddlewareKey] = "K-9";
}
}
public static class HttpContextItemsMiddlewareExtensions

{
public static IApplicationBuilder
UseHttpContextItemsMiddleware(this IApplicationBuilder builder)
{
return builder.UseMiddleware<HttpContextItemsMiddleware>();
}
}
// You may need to install the Microsoft.AspNetCore.Http.Abstractions package
public class HttpContextItemsMiddleware
{
public static readonly object HttpContextItemsMiddlewareKey = new Object();
public HttpContextItemsMiddleware(RequestDelegate next)

{
_next = next;
}

{
httpContext.Items[HttpContextItemsMiddlewareKey] = "K-9";
}
}
public static class HttpContextItemsMiddlewareExtensions

{
public static IApplicationBuilder
UseHttpContextItemsMiddleware(this IApplicationBuilder builder)
{
return builder.UseMiddleware<HttpContextItemsMiddleware>();
}
}
Outros códigos podem acessar o valor armazenado em HttpContext.Items usando a chave exposta pela classe do
middleware:
HttpContext.Items
.TryGetValue(HttpContextItemsMiddleware.HttpContextItemsMiddlewareKey,
out var middlewareSetValue);
SessionInfo_MiddlewareValue =
middlewareSetValue?.ToString() ?? "Middleware value not set!";
public IActionResult GetMiddlewareValue()

{
var middlewareSetValue =
HttpContext.Items[HttpContextItemsMiddleware.HttpContextItemsMiddlewareKey];
return Content($"Value: {middlewareSetValue}");

}
Essa abordagem também tem a vantagem de eliminar o uso de cadeias de caracteres de chave no código.
Cache
O cache é uma maneira eficiente de armazenar e recuperar dados. O aplicativo pode controlar o tempo de vida de
itens em cache.
Dados armazenados em cache não são associados uma solicitação, usuário ou sessão específico. Tenha cuidado
para não armazenar em cache dados específicos do usuário que podem ser recuperados pelas
solicitações de outros usuários.
Para obter mais informações, veja o tópico Armazenar respostas em cache.
Use a Injeção de dependência para disponibilizar dados para todos os usuários:
1. Defina um serviço que contenha os dados. Por exemplo, uma classe denominada MyAppData está definida:
public class MyAppData

{
// Declare properties and methods
}
2. Adicione a classe de serviço a Startup.ConfigureServices :

{
services.AddSingleton<MyAppData>();
}
3. Consuma a classe de serviço de dados:

{
public IndexModel(MyAppData myService)
{
// Do something with the service
// Examples: Read data, store in a field or property
}
}

{
public HomeController(MyAppData myService)
{
// Do something with the service
// Examples: Read data, store in a field or property
}
}
Erros comuns
"Não é possível resolver o serviço para o tipo 'Microsoft.Extensions.Caching.Distributed.IDistributedCache'
ao tentar ativar 'Microsoft.AspNetCore.Session.DistributedSessionStore'."
Geralmente, isso é causado quando não é configurada pelo menos uma implementação de
IDistributedCache . Para obter mais informações, consulte O cache no ASP.NET Core distribuído e
Memória de cache no ASP.NET Core.
Caso a sessão de middleware não consiga manter uma sessão (por exemplo, se o repositório de backup
não estiver disponível), o middleware registrará a exceção e a solicitação continuará normalmente. Isso leva
a um comportamento imprevisível.
Por exemplo, um usuário armazena um carrinho de compras na sessão. O usuário adiciona um item ao
carrinho, mas a confirmação falha. O aplicativo não sabe sobre a falha, assim, relata ao usuário que o item
foi adicionado ao seu carrinho, o que não é verdade.
A abordagem recomendada para verificar se há erros é chamar await feature.Session.CommitAsync(); do
código de aplicativo quando o aplicativo tiver terminado de gravar na sessão. CommitAsync gerará uma
exceção se o repositório de backup não estiver disponível. Se CommitAsync falhar, o aplicativo poderá
processar a exceção. LoadAsync gera sob as mesmas condições em que o armazenamento de dados não
está disponível.
Recursos adicionais
Hospedar o ASP.NET Core em um web farm
Por Rick Anderson
E que são Auxiliares de Marca?

Os Auxiliares de Marca permitem que o código do lado do servidor participe da criação e
renderização de elementos HTML em arquivos do Razor. Por exemplo, o ImageTagHelper
interno pode acrescentar um número de versão ao nome da imagem. Sempre que a
imagem é alterada, o servidor gera uma nova versão exclusiva para a imagem, de modo
que os clientes tenham a garantia de obter a imagem atual (em vez de uma imagem
obsoleta armazenada em cache). Há muitos Auxiliares de Marca internos para tarefas
comuns – como criação de formulários, links, carregamento de ativos e muito mais – e
ainda outros disponíveis em repositórios GitHub públicos e como NuGet. Os Auxiliares de
Marca são criados no C# e são direcionados a elementos HTML de acordo com o nome do
elemento, o nome do atributo ou a marca pai. Por exemplo, o LabelTagHelper interno pode
ser direcionado ao elemento <label> HTML quando os atributos LabelTagHelper são
aplicados. Se você está familiarizado com Auxiliares HTML, os Auxiliares de Marca
reduzem as transições explícitas entre HTML e C# em exibições do Razor. Em muitos
casos, os Auxiliares HTML fornecem uma abordagem alternativa a um Auxiliar de Marca
específico, mas é importante reconhecer que os Auxiliares de Marca não substituem os
Auxiliares HTML e que não há um Auxiliar de Marca para cada Auxiliar HTML.
Comparação entre Auxiliares de Marca e Auxiliares HTML explica as diferenças mais
detalhadamente.
O que os Auxiliares de Marca fornecem

Uma experiência de desenvolvimento amigável a HTML Na maioria dos casos, a
marcação do Razor com Auxiliares de Marca parece um HTML padrão. Designers de front-
end familiarizados com HTML/CSS/JavaScript podem editar o Razor sem aprender a
sintaxe Razor do C#.
Um ambiente avançado do IntelliSense para criação do HTML e da marcação do
Razor Isso é um nítido contraste com Auxiliares HTML, a abordagem anterior para a
criação do lado do servidor de marcação nas exibições do Razor. Comparação entre
Auxiliares de Marca e Auxiliares HTML explica as diferenças mais detalhadamente.
Suporte do IntelliSense para Auxiliares de Marca explica o ambiente do IntelliSense. Até
mesmo desenvolvedores experientes com a sintaxe Razor do C# são mais produtivos
usando Auxiliares de Marca do que escrevendo a marcação do Razor do C#.
Uma maneira de fazer com que você fique mais produtivo e possa produzir um
código mais robusto, confiável e possível de ser mantido usando as informações
apenas disponíveis no servidor Por exemplo, historicamente, o mantra da atualização de
imagens era alterar o nome da imagem quando a imagem era alterada. As imagens devem
ser armazenadas em cache de forma agressiva por motivos de desempenho e, a menos
que você altere o nome de uma imagem, você corre o risco de os clientes obterem uma
cópia obsoleta. Historicamente, depois que uma imagem era editada, o nome precisava ser
alterado e cada referência à imagem no aplicativo Web precisava ser atualizada. Não
apenas isso exige muito trabalho, mas também é propenso a erros (você pode perder uma
referência, inserir a cadeia de caracteres incorreta acidentalmente, etc.) O ImageTagHelper
interno pode fazer isso para você automaticamente. O ImageTagHelper pode acrescentar
um número de versão ao nome da imagem, de modo que sempre que a imagem é
alterada, o servidor gera automaticamente uma nova versão exclusiva para a imagem. Os
clientes têm a garantia de obter a imagem atual. Basicamente, essa economia na robustez e
no trabalho é obtida gratuitamente com o ImageTagHelper .
A maioria dos auxiliares de marca internos é direcionada a elementos HTML padrão e
fornece atributos do lado do servidor para o elemento. Por exemplo, o elemento <input>
usado em várias exibições na pasta Exibição/Conta contém o atributo asp-for . Esse
atributo extrai o nome da propriedade do modelo especificado no HTML renderizado.
Considere uma exibição Razor com o seguinte modelo:
public class Movie

{
}
A seguinte marcação do Razor:
<label asp-for="Movie.Title"></label>
Gera o seguinte HTML:
<label for="Movie_Title">Title</label>
O atributo asp-for é disponibilizado pela propriedade For no LabelTagHelper. Confira

Auxiliares de marca de autor para obter mais informações.
Gerenciando o escopo do Auxiliar de Marca

O escopo dos Auxiliares de Marca é controlado por uma combinação de @addTagHelper ,
@removeTagHelper e o caractere de recusa "!".
@addTagHelper disponibiliza os Auxiliares de Marca

Se você criar um novo aplicativo Web ASP.NET Core chamado AuthoringTagHelpers, o
seguinte arquivo Views/_ViewImports.cshtml será adicionado ao projeto:
@addTagHelper *, AuthoringTagHelpers
A diretiva @addTagHelper disponibiliza os Auxiliares de Marca para a exibição. Nesse caso,

o arquivo de exibição é Pages/_ViewImports.cshtml, que é herdado por padrão por todos
os arquivos na pasta Páginas e suas subpastas, disponibilizando os Auxiliares de Marca. O
código acima usa a sintaxe de curinga ("*") para especificar que todos os Auxiliares de
Marca no assembly especificado (Microsoft.AspNetCore.Mvc.TagHelpers) estarão
disponíveis para todos os arquivos de exibição no diretório Views ou subdiretório. O
primeiro parâmetro após @addTagHelper especifica os Auxiliares de Marca a serem
carregados (estamos usando "*" para todos os Auxiliares de Marca) e o segundo
parâmetro "Microsoft.AspNetCore.Mvc.TagHelpers" especifica o assembly que contém os
Auxiliares de Marca. Microsoft.AspNetCore.Mvc.TagHelpers é o assembly para os
Auxiliares de Marca internos do ASP.NET Core.
Para expor todos os Auxiliares de Marca neste projeto (que cria um assembly chamado
AuthoringTagHelpers), você usará o seguinte:
@using AuthoringTagHelpers
@addTagHelper *, AuthoringTagHelpers
Se o projeto contém um EmailTagHelper com o namespace padrão (

AuthoringTagHelpers.TagHelpers.EmailTagHelper ), forneça o FQN ( nome totalmente
qualificado) do Auxiliar de Marca:
@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers
Para adicionar um Auxiliar de Marca a uma exibição usando um FQN, primeiro adicione o
FQN ( AuthoringTagHelpers.TagHelpers.EmailTagHelper ) e, em seguida, o nome do assembly
(AuthoringTagHelpers). A maioria dos desenvolvedores prefere usar a sintaxe de curinga
"*". A sintaxe de curinga permite que você insira o caractere curinga "*" como o sufixo de
um FQN. Por exemplo, uma das seguintes diretivas exibirá o EmailTagHelper :
@addTagHelper AuthoringTagHelpers.TagHelpers.E*, AuthoringTagHelpers

@addTagHelper AuthoringTagHelpers.TagHelpers.Email*, AuthoringTagHelpers
Conforme mencionado anteriormente, a adição da diretiva @addTagHelper ao arquivo

Views/_ViewImports.cshtml disponibiliza o Auxiliar de Marca para todos os arquivos de
exibição no diretório Views e subdiretórios. Use a diretiva @addTagHelper nos arquivos de
exibição específicos se você deseja aceitar a exposição do Auxiliar de Marca a apenas essas
exibições.
@removeTagHelper remove os Auxiliares de Marca
O @removeTagHelper tem os mesmos dois parâmetros @addTagHelper e remove um
Auxiliar de Marca adicionado anteriormente. Por exemplo, @removeTagHelper aplicado a
uma exibição específica remove o Auxiliar de Marca especificado da exibição. O uso de
@removeTagHelper em um arquivo Views/Folder/_ViewImports.cshtml remove o Auxiliar de
Marca especificado de todas as exibições em Folder.
Controlando o escopo do Auxiliar de Marca com o arquivo _ViewImports.cshtml
Adicione um _ViewImports.cshtml a qualquer pasta de exibição e o mecanismo de exibição
aplicará as diretivas desse arquivo e do arquivo Views/_ViewImports.cshtml. Se você
adicionou um arquivo Views/Home/_ViewImports.cshtml vazio às exibições Home, não
haverá nenhuma alteração porque o arquivo _ViewImports.cshtml é aditivo. As diretivas
@addTagHelper que você adicionar ao arquivo Views/Home/_ViewImports.cshtml (que não
estão no arquivo Views/_ViewImports.cshtml padrão) exporão os Auxiliares de Marca às
exibições somente na pasta Home.
Recusando elementos individuais
Desabilite um Auxiliar de Marca no nível do elemento com o caractere de recusa do
Auxiliar de Marca ("!"). Por exemplo, a validação Email está desabilitada no <span> com o
caractere de recusa do Auxiliar de Marca:
<!span asp-validation-for="Email" class="text-danger"></!span>
É necessário aplicar o caractere de recusa do Auxiliar de Marca à marca de abertura e

fechamento. (O editor do Visual Studio adiciona automaticamente o caractere de recusa à
marca de fechamento quando um é adicionado à marca de abertura). Depois de adicionar
o caractere de recusa, o elemento e os atributos do Auxiliar de Marca deixam de ser
exibidos em uma fonte diferenciada.
Usando @tagHelperPrefix para tornar explícito o uso do Auxiliar de Marca
A diretiva @tagHelperPrefix permite que você especifique uma cadeia de caracteres de
prefixo de marca para habilitar o suporte do Auxiliar de Marca e tornar explícito o uso do
Auxiliar de Marca. Por exemplo, você pode adicionar a seguinte marcação ao arquivo
Views/_ViewImports.cshtml:
@tagHelperPrefix th:
Na imagem do código abaixo, o prefixo do Auxiliar de Marca é definido como th: ;

portanto, somente esses elementos que usam o prefixo th: dão suporte a Auxiliares de
Marca (elementos habilitados para Auxiliar de Marca têm uma fonte diferenciada). Os
elementos <label> e <input> têm o prefixo do Auxiliar de Marca e são habilitados para
Auxiliar de Marca, ao contrário do elemento <span> .
As mesmas regras de hierarquia que se aplicam a @addTagHelper também se aplicam a

@tagHelperPrefix .
Auxiliares de Marca com autofechamento

Muitos Auxiliares de Marca não podem ser usados como marcações com autofechamento.
Alguns Auxiliares de Marca são projetados para serem marcações com autofechamento.
Usar um Auxiliar de Marca que não foi projetado para ser de autofechamento suprime a
saída renderizada. Um Auxiliar de Marca com autofechamento resulta em uma marca com
autofechamento na saída renderizada. Para obter mais informações, confira esta
observação em Criando Auxiliares de Marca.
Suporte do IntelliSense para Auxiliares de Marca

Quando você cria um novo aplicativo Web ASP.NET Core no Visual Studio, ele adiciona o
pacote NuGet "Microsoft.AspNetCore.Razor.Tools". Esse é o pacote que adiciona
ferramentas do Auxiliar de Marca.
Considere a escrita de um elemento <label> HTML. Assim que você insere <l no editor
do Visual Studio, o IntelliSense exibe elementos correspondentes:
Não só você obtém a ajuda do HTML, mas também o ícone (o "@" symbol with "<>"
abaixo dele).
identifica o elemento como direcionado a Auxiliares de Marca. Elementos HTML puros

(como o fieldset ) exibem o ícone "<>".
Uma marca <label> HTML pura exibe a marca HTML (com o tema de cores padrão do
Visual Studio) em uma fonte marrom, os atributos em vermelho e os valores de atributo
em azul.
Depois de inserir <label , o IntelliSense lista os atributos HTML/CSS disponíveis e os

atributos direcionados ao Auxiliar de Marca:
O preenchimento de declaração do IntelliSense permite que você pressione a tecla TAB

para preencher a declaração com o valor selecionado:
Assim que um atributo do Auxiliar de Marca é inserido, as fontes da marca e do atributo

são alteradas. Usando o tema de cores padrão "Azul" ou "Claro" do Visual Studio, a fonte é
roxo em negrito. Se estiver usando o tema "Escuro", a fonte será azul-petróleo em negrito.
As imagens deste documento foram obtidas usando o tema padrão.
Insira o atalho CompleteWord do Visual Studio – Ctrl + barra de espaços é o padrão

dentro das aspas duplas ("") e você está agora no C#, exatamente como estaria em uma
classe do C#. O IntelliSense exibe todos os métodos e propriedades no modelo de página.
Os métodos e as propriedades estão disponíveis porque o tipo de propriedade é
ModelExpression . Na imagem abaixo, estou editando a exibição Register e, portanto, o
RegisterViewModel está disponível.
O IntelliSense lista as propriedades e os métodos disponíveis para o modelo na página. O

ambiente avançado de IntelliSense ajuda você a selecionar a classe CSS:
Comparação entre Auxiliares de Marca e Auxiliares

HTML
Os Auxiliares de Marca são anexados a elementos HTML em exibições do Razor, enquanto
os Auxiliares HTML são invocados como métodos intercalados com HTML nas exibições
do Razor. Considere a seguinte marcação do Razor, que cria um rótulo HTML com a classe
CSS "caption":
@Html.Label("FirstName", "First Name:", new {@class="caption"})
O símbolo de arroba ( @ ) informa o Razor de que este é o início do código. Os dois

próximos parâmetros ("FirstName" e "First Name:") são cadeias de caracteres; portanto, o
IntelliSense não pode ajudar. O último argumento:
new {@class="caption"}
É um objeto anônimo usado para representar atributos. Como a classe é uma palavra-
chave reservada no C#, use o símbolo @ para forçar o C# a interpretar "@class=" como
um símbolo (nome da propriedade). Para um designer de front-end (alguém familiarizado
com HTML/CSS/JavaScript e outras tecnologias de cliente, mas não familiarizado com o
C# e Razor), a maior parte da linha é estranha. Toda a linha precisa ser criada sem
nenhuma ajuda do IntelliSense.
Usando o LabelTagHelper , a mesma marcação pode ser escrita como:
Com a versão do Auxiliar de Marca, assim que você insere <l no editor do Visual Studio,
o IntelliSense exibe elementos correspondentes:
O IntelliSense ajuda você a escrever a linha inteira. O LabelTagHelper também usa como
padrão a definição do conteúdo do valor de atributo asp-for ("FirstName") como "First
Name"; ele converte propriedades concatenadas em uma frase composta do nome da
propriedade com um espaço em que ocorre cada nova letra maiúscula. Na seguinte
marcação:
gera:
<label class="caption" for="FirstName">First Name</label>
O conteúdo concatenado para maiúsculas e minúsculas não é usado se você adiciona o

conteúdo ao <label> . Por exemplo:
gera:
<label class="caption" for="FirstName">Name First</label>
A imagem de código a seguir mostra a parte do Formulário da exibição do Razor

Views/Account/Register.cshtml gerada com base no modelo herdado do ASP.NET 4.5 MVC
incluído com o Visual Studio 2015.
O editor do Visual Studio exibe o código C# com uma tela de fundo cinza. Por exemplo, o
Auxiliar HTML AntiForgeryToken :
@Html.AntiForgeryToken()
é exibido com uma tela de fundo cinza. A maior parte da marcação na exibição Register é
C#. Compare isso com a abordagem equivalente ao uso de Auxiliares de Marca:
A marcação é muito mias limpa e fácil de ler, editar e manter que a abordagem dos
Auxiliares HTML. O código C# é reduzido ao mínimo que o servidor precisa conhecer. O
editor do Visual Studio exibe a marcação direcionada por um Auxiliar de Marca em uma
fonte diferenciada.
Considere o grupo Email:
<label asp-for="Email" class="col-md-2 control-label"></label>
<input asp-for="Email" class="form-control" />
<span asp-validation-for="Email" class="text-danger"></span>
</div>
</div>
Cada um dos atributos "asp-" tem um valor "Email", mas "Email" não é uma cadeia de
caracteres. Nesse contexto, "Email" é a propriedade da expressão do modelo C# para o
RegisterViewModel .
O editor do Visual Studio ajuda você a escrever toda a marcação na abordagem do

Auxiliar de Marca de formulário de registro, enquanto o Visual Studio não fornece
nenhuma ajuda para a maioria do código na abordagem de Auxiliares HTML. Suporte do
IntelliSense para Auxiliares de Marca apresenta detalhes sobre como trabalhar com
Auxiliares de Marca no editor do Visual Studio.
Comparação entre Auxiliares de Marca e Controles de

Servidor Web
Os Auxiliares de Marca não têm o elemento ao qual estão associados; simplesmente
participam da renderização do elemento e do conteúdo. Os controles de Servidor
Web do ASP.NET são declarados e invocados em uma página.
Os controles de Servidor Web têm um ciclo de vida não trivial que pode dificultar o
desenvolvimento e a depuração.
Os controles de Servidor Web permitem que você adicione a funcionalidade aos
elementos DOM (Modelo de Objeto do Documento) do cliente usando um controle
de cliente. Os Auxiliares de Marca não tem nenhum DOM.
Os controles de Servidor Web incluem a detecção automática do navegador. Os
Auxiliares de Marca não têm nenhum conhecimento sobre o navegador.
Vários Auxiliares de Marca podem atuar no mesmo elemento (consulte Evitando
conflitos do Auxiliar de Marca), embora normalmente não seja possível compor
controles de Servidor Web.
Os Auxiliares de Marca podem modificar a marca e o conteúdo de elementos HTML
no escopo com o qual foram definidos, mas não modificam diretamente todo o
resto em uma página. Os controles de Servidor Web têm um escopo menos
específico e podem executar ações que afetam outras partes da página, permitindo
efeitos colaterais não intencionais.
Os controles de Servidor Web usam conversores de tipo para converter cadeias de
caracteres em objetos. Com os Auxiliares de Marca, você trabalha nativamente no
C# e, portanto, não precisa fazer a conversão de tipo.
Os controles de Servidor Web usam System.ComponentModel para implementar o
comportamento de componentes e controles em tempo de execução e em tempo de
design. System.ComponentModel inclui as interfaces e as classes base para
implementar atributos e conversores de tipo, associar a fontes de dados e licenciar
componentes. Compare isso com os Auxiliares de Marca, que normalmente são
derivados de TagHelper , e a classe base TagHelper expõe apenas dois métodos,
Process e ProcessAsync .
Personalizando a fonte de elemento do Auxiliar de

Marca
Personalize a fonte e a colorização em Ferramentas > Opções > Ambiente > Fontes e
Cores:
Recursos adicionais
TagHelperSamples no GitHub contém amostras de Auxiliar de Marca para trabalhar
com o Bootstrap.
Auxiliares de marca de autor no ASP.NET Core
Por Rick Anderson

Introdução aos Auxiliares de Marca

Este tutorial fornece uma introdução à programação de auxiliares de marcação. Introdução aos auxiliares de
marcação descreve os benefícios que os auxiliares de marcação fornecem.
Um auxiliar de marca é qualquer classe que implementa a interface ITagHelper . No entanto, quando cria um
auxiliar de marca, você geralmente deriva de TagHelper , o que fornece acesso ao método Process .
1. Crie um novo projeto do ASP.NET Core chamado AuthoringTagHelpers. Você não precisará de
autenticação para esse projeto.
2. Criar uma pasta para armazenar os auxiliares de marca chamados TagHelpers. A pasta TagHelpers pasta
não é necessária, mas é uma convenção comum. Agora vamos começar a escrever alguns auxiliares de
marca simples.
Um auxiliar de marca mínimo

Nesta seção, você escreve um auxiliar de marca que atualiza uma marca de email. Por exemplo:
<email>Support</email>
O servidor usará nosso auxiliar de marca de email para converter essa marcação como a seguir:
<a href="mailto:Support@contoso.com">Support@contoso.com</a>
Ou seja, uma marca de âncora que torna isso um link de email. Talvez você deseje fazer isso se estiver
escrevendo um mecanismo de blog e precisar que ele envie emails para o marketing, suporte e outros contatos,
todos para o mesmo domínio.
1. Adicione a classe EmailTagHelper a seguir à pasta TagHelpers.
using Microsoft.AspNetCore.Razor.TagHelpers;
namespace AuthoringTagHelpers.TagHelpers
{
public class EmailTagHelper : TagHelper
{
public override void Process(TagHelperContext context, TagHelperOutput output)
{
output.TagName = "a"; // Replaces <email> with <a> tag
}
}
}
Auxiliares de marcação usam uma convenção de nomenclatura que tem como alvo os elementos
do nome da classe raiz (menos o TagHelper parte do nome de classe). Neste exemplo, o nome da
raiz EmailTagHelper é email, portanto, a marca <email> será direcionada. Essa convenção de
nomenclatura deve funcionar para a maioria dos auxiliares de marcação, posteriormente,
mostrarei como substituí-la.
O EmailTagHelper classe deriva de TagHelper . O TagHelper classe fornece métodos e
propriedades para gravar tag helpers.
O método Process substituído controla o que o auxiliar de marca faz quando é executado. A
classe TagHelper também fornece uma versão assíncrona ( ProcessAsync ) com os mesmos
parâmetros.
O parâmetro de contexto para Process (e ProcessAsync ) contém informações associadas à
execução da marca HTML atual.
O parâmetro de saída para Process (e ProcessAsync ) contém um elemento HTML com estado
que representa a fonte original usada para gerar uma marca HTML e o conteúdo.
Nosso nome de classe tem um sufixo TagHelper, que não é necessário, mas que é considerado
uma convenção de melhor prática. Você pode declarar a classe como:
public class Email : TagHelper
2. Para disponibilizar a classe EmailTagHelper para todas as nossas exibições do Razor, adicione a diretiva
addTagHelper ao arquivo Views/_ViewImports.cshtml: [!code-html]
O código acima usa a sintaxe de curinga para especificar que todos os auxiliares de marca em nosso
assembly estarão disponíveis. A primeira cadeia de caracteres após @addTagHelper especifica o auxiliar
de marca a ser carregado (use "*" para todos os auxiliares de marca) e a segunda cadeia de caracteres
"AuthoringTagHelpers" especifica o assembly no qual o auxiliar de marca se encontra. Além disso,
observe que a segunda linha insere os auxiliares de marca do ASP.NET Core MVC usando a sintaxe de
curinga (esses auxiliares são abordados em Introdução ao auxiliares de marcação). É a diretiva
@addTagHelper que disponibiliza o auxiliar de marca para a exibição do Razor. Como alternativa, você
pode fornecer o FQN (nome totalmente qualificado) de um auxiliar de marca, conforme mostrado
abaixo:
@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers
Para adicionar um tag helper para uma exibição usando um FQN, primeiro adicione o FQN (
AuthoringTagHelpers.TagHelpers.EmailTagHelper ) e, em seguida, o nome do assembly ( AuthoringTagHelpers). A
maioria dos desenvolvedores vão preferir usar a sintaxe de curinga. Introdução ao tag helpers apresenta
detalhes sobre a sintaxe de adição, remoção, hierarquia e curinga do tag helper.
1. Atualize a marcação no arquivo Views/Home/Contact.cshtml com essas alterações:
@{
}
<address>
One Microsoft Way<br />
Redmond, WA 98052<br />
425.555.0100
</address>
<address>
<strong>Support:</strong><email>Support</email><br />
<strong>Marketing:</strong><email>Marketing</email>
</address>
2. Execute o aplicativo e use seu navegador favorito para exibir o código-fonte HTML para verificar se as
marcas de email são substituídas pela marcação de âncora (por exemplo, <a>Support</a> ). Suporte e
Marketing são renderizados como links, mas não têm um atributo href para torná-los funcionais.
Corrigiremos isso na próxima seção.
SetAttribute e SetContent
Nesta seção, atualizaremos o EmailTagHelper para que ele crie uma marca de âncora válida para email. Vamos
atualizá-lo para obter informações de uma exibição do Razor (na forma de um atributo mail-to ) e usar isso na
geração da âncora.
Atualize a classe EmailTagHelper com o seguinte:

{
private const string EmailDomain = "contoso.com";
// Can be passed via <email mail-to="..." />.

// Pascal case gets translated into lower-kebab-case.
public string MailTo { get; set; }

{
var address = MailTo + "@" + EmailDomain;

output.Attributes.SetAttribute("href", "mailto:" + address);
output.Content.SetContent(address);
}
}
Nomes de classe e de propriedade na formatação Pascal Case para auxiliares de marca são convertidos
em seu kebab case em minúsculas. Portanto, para usar o atributo MailTo , você usará o equivalente de
<email mail-to="value"/> .
A última linha define o conteúdo concluído para nosso tag helper minimamente funcional.
A linha realçada mostra a sintaxe para adicionar atributos:
{
var address = MailTo + "@" + EmailDomain;

output.Attributes.SetAttribute("href", "mailto:" + address);
output.Content.SetContent(address);
}
Essa abordagem funciona para o atributo "href" como no momento, ele não existe na coleção de atributos. Você
também pode usar o output.Attributes.Add para adicionar um atributo do tag helper ao final da coleção de
atributos de marca.
1. Atualize a marcação no arquivo Views/Home/Contact.cshtml com essas alterações: [!code-html]
2. Execute o aplicativo e verifique se ele gera os links corretos.
NOTE
Se você pretende escrever o autofechamento da marca de email ( <email mail-to="Rick" /> ), a saída final também é o
autofechamento. Para permitir a capacidade de gravar a marca com uma marca de início ( <email mail-to="Rick"> ), é
necessário decorar a classe com o seguinte:
[HtmlTargetElement("email", TagStructure = TagStructure.WithoutEndTag)]

public class EmailVoidTagHelper : TagHelper
{
// Code removed for brevity
Com um auxiliar de marca da marca de email com autofechamento, a saída será

<a href="mailto:Rick@contoso.com" /> . As marcas de âncora com autofechamento são um HTML inválido.
Portanto, não é recomendável criá-las, mas talvez criar um auxiliar de marca com autofechamento. Auxiliares de
marca definem o tipo da propriedade TagMode após a leitura de uma marca.
ProcessAsync
Nesta seção, escreveremos um auxiliar de email assíncrono.
1. Substitua a classe EmailTagHelper pelo seguinte código:

{
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
var content = await output.GetChildContentAsync();
var target = content.GetContent() + "@" + EmailDomain;
output.Attributes.SetAttribute("href", "mailto:" + target);
output.Content.SetContent(target);
}
}
Observações:
Essa versão usa o método ProcessAsync assíncrono. O GetChildContentAsync assíncrono retorna
uma Task que contém o TagHelperContent .
Use o parâmetro output para obter o conteúdo do elemento HTML.
2. Faça a alteração a seguir no arquivo Views/Home/Contact.cshtml para que o auxiliar de marca possa
obter o email de destino.
@{
}
<address>
425.555.0100
</address>
<address>
</address>
3. Execute o aplicativo e verifique se ele gera links de email válidos.

RemoveAll, PreContent.SetHtmlContent e PostContent.SetHtmlContent
1. Adicione a classe BoldTagHelper a seguir à pasta TagHelpers.
{
[HtmlTargetElement(Attributes = "bold")]
public class BoldTagHelper : TagHelper
{
{
output.Attributes.RemoveAll("bold");
output.PreContent.SetHtmlContent("<strong>");
output.PostContent.SetHtmlContent("</strong>");
}
}
}
O atributo [HtmlTargetElement] passa um parâmetro de atributo que especifica que qualquer

elemento HTML que contenha um atributo HTML nomeado "bold" terá uma correspondência e
que o método de substituição Process na classe será executado. Em nossa amostra, o método
Process remove o atributo "bold" e envolve a marcação contida com <strong></strong> .
Como você não deseja substituir a conteúdo de marca existente, você precisa escrever a marca
<strong> de abertura com o método PreContent.SetHtmlContent e a marca </strong> de
fechamento com o método PostContent.SetHtmlContent .
2. Modifique a exibição About.cshtml para que ela contenha um valor de atributo bold . O código completo
é mostrado abaixo.
@{
}
<p bold>Use this area to provide additional information.</p>
<bold> Is this bold?</bold>
3. Execute o aplicativo. Use seu navegador favorito para inspecionar a origem e verificar a marcação.
O [HtmlTargetElement] atributo acima se destina somente a marcação HTML que fornece um nome de
atributo de "bold". O <bold> elemento não foi modificado pelo tag helper.
4. Comente a linha de atributo [HtmlTargetElement] e ela usará como padrão as marcações <bold> de
direcionamento, ou seja, a marcação HTML do formato <bold> . Lembre-se de que a convenção de
nomenclatura padrão fará a correspondência do nome da classe BoldTagHelper com as marcações
<bold> .
5. Execute o aplicativo e verifique se a marca <bold> é processada pelo auxiliar de marca.

A decoração de uma classe com vários atributos [HtmlTargetElement] resulta em um OR lógico dos destinos.
Por exemplo, o uso do código a seguir, uma marca de negrito ou um atributo de negrito terá uma
correspondência.
[HtmlTargetElement("bold")]
[HtmlTargetElement(Attributes = "bold")]
public class BoldTagHelper : TagHelper
{
{
output.Attributes.RemoveAll("bold");
output.PreContent.SetHtmlContent("<strong>");
output.PostContent.SetHtmlContent("</strong>");
}
}
Quando vários atributos são adicionados à mesma instrução, o tempo de execução trata-os como um AND
lógico. Por exemplo, no código abaixo, um elemento HTML precisa ser nomeado "bold" com um atributo
nomeado "bold" ( <bold bold /> ) para que haja a correspondência.
[HtmlTargetElement("bold", Attributes = "bold")]
Também use o [HtmlTargetElement] para alterar o nome do elemento de destino. Por exemplo, se você deseja
que o BoldTagHelper seja direcionado a marcações <MyBold> , use o seguinte atributo:
[HtmlTargetElement("MyBold")]
Passe um model para um tag helper

1. Adicionar uma pasta models.
2. Adicione a seguinte classe WebsiteContext à pasta Models:
using System;
namespace AuthoringTagHelpers.Models
{
public class WebsiteContext
{
public Version Version { get; set; }
public int CopyrightYear { get; set; }
public bool Approved { get; set; }
public int TagsToShow { get; set; }
}
}
3. Adicione a classe WebsiteInformationTagHelper a seguir à pasta TagHelpers.
using System;
using AuthoringTagHelpers.Models;
{
public class WebsiteInformationTagHelper : TagHelper
{
public WebsiteContext Info { get; set; }

{
output.TagName = "section";
output.Content.SetHtmlContent(
$@"<ul><li><strong>Version:</strong> {Info.Version}</li>
<li><strong>Copyright Year:</strong> {Info.CopyrightYear}</li>
<li><strong>Approved:</strong> {Info.Approved}</li>
<li><strong>Number of tags to show:</strong> {Info.TagsToShow}</li></ul>");
output.TagMode = TagMode.StartTagAndEndTag;
}
}
}
Conforme mencionado anteriormente, os auxiliares de marca convertem nomes de classes e

propriedades dos auxiliares de marca do C# na formatação Pascal Case em kebab case em
minúsculas. Portanto, para usar o WebsiteInformationTagHelper no Razor, você escreverá
<website-information /> .
Você não identifica de forma explícita o elemento de destino com o atributo [HtmlTargetElement] .
Portanto, o padrão de website-information será o destino. Se você aplicou o seguinte atributo
(observe que não está em kebab case, mas corresponde ao nome da classe):
[HtmlTargetElement("WebsiteInformation")]
A marca <website-information /> em kebab case em minúsculas não terá uma correspondência. Caso
deseje usar o atributo [HtmlTargetElement] , use o kebab case, conforme mostrado abaixo:
[HtmlTargetElement("Website-Information")]
Os elementos com autofechamento não têm nenhum conteúdo. Para este exemplo, a marcação do
Razor usará uma marca com autofechamento, mas o auxiliar de marca criará um elemento section
(que não tem autofechamento e você escreve o conteúdo dentro do elemento section ). Portanto,
você precisa definir TagMode como StartTagAndEndTag para escrever a saída. Como alternativa,
você pode comentar a linha definindo TagMode e escrever a marcação com uma marca de
fechamento. (A marcação de exemplo é fornecida mais adiante neste tutorial.)
O $ (cifrão) na seguinte linha usa uma cadeia de caracteres interpolada:
$@"<ul><li><strong>Version:</strong> {Info.Version}</li>
4. Adicione a marcação a seguir à exibição About.cshtml. A marcação realçada exibe as informações do site.
@using AuthoringTagHelpers.Models
@{
}
<p bold>Use this area to provide additional information.</p>
<bold> Is this bold?</bold>
<h3> web site info </h3>

<website-information info="new WebsiteContext {
Version = new Version(1, 3),
CopyrightYear = 1638,
Approved = true,
TagsToShow = 131 }" />
NOTE
Na marcação do Razor mostrada abaixo:

Approved = true,
TagsToShow = 131 }" />
O Razor reconhece que o atributo info é uma classe, e não uma cadeia de caracteres, bem como que você
deseja escrever o código C#. Qualquer atributo do auxiliar de marca que não seja uma cadeia de caracteres deve
ser escrito sem o caractere @ .
5. Execute o aplicativo e navegue para a exibição About sobre para ver as informações do site.
NOTE
Você pode usar a seguinte marcação com uma marca de fechamento e remova a linha com
TagMode.StartTagAndEndTag no tag helper:

Approved = true,
TagsToShow = 131 }" >
</website-information>
Tag helper condicional

O auxiliar de marca de condição renderiza a saída quando recebe um valor true.
1. Adicione a classe ConditionTagHelper a seguir à pasta TagHelpers.
{
[HtmlTargetElement(Attributes = nameof(Condition))]
public class ConditionTagHelper : TagHelper
{
public bool Condition { get; set; }

{
if (!Condition)
{
output.SuppressOutput();
}
}
}
}
2. Substitua o conteúdo do arquivo Views/Home/Index.cshtml pela seguinte marcação:
@using AuthoringTagHelpers.Models
@model WebsiteContext
@{
ViewData["Title"] = "Home Page";
}
<div>
<h3>Information about our website (outdated):</h3>
<Website-InforMation info="Model" />
<div condition="Model.Approved">
<p>
This website has <strong surround="em">@Model.Approved</strong> been approved yet.
Visit www.contoso.com for more information.
</p>
</div>
</div>
3. Substitua o método Index no controlador Home pelo seguinte código:
public IActionResult Index(bool approved = false)

{
return View(new WebsiteContext
{
Approved = approved,
Version = new Version(1, 3, 3, 7),
TagsToShow = 20
});
}
4. Execute o aplicativo e navegue para a home page. A marcação no div condicional não será renderizada.
Acrescente a cadeia de caracteres de consulta ?approved=true à URL (por exemplo,
http://localhost:1235/Home/Index?approved=true ). approved é definido como verdadeiro e a marcação
condicional será exibida.
NOTE
Use o nameof operador para especificar o atributo de destino em vez de especificar uma cadeia de caracteres como você
fez com o tag helper em negrito:
[HtmlTargetElement(Attributes = nameof(Condition))]
// [HtmlTargetElement(Attributes = "condition")]
public class ConditionTagHelper : TagHelper
{
public bool Condition { get; set; }

{
if (!Condition)
{
output.SuppressOutput();
}
}
}
O operador nameof protegerá o código, caso ele seja refatorado (recomendamos alterar o nome para RedCondition ).
Evitar conflitos de tag helper

Nesta seção, você escreve um par de tag helpers de vinculação automática. O primeiro substituirá a marcação
que contém uma URL iniciada por HTTP para um HTML âncora marca que contém a mesma URL (e, portanto,
resultando em um link de URL ). O segundo fará o mesmo para uma URL começando com WWW.
Como esses dois auxiliares estão intimamente relacionados e você poderá refatorá-los no futuro, vamos mantê-
los no mesmo arquivo.
1. Adicione a classe AutoLinkerHttpTagHelper a seguir à pasta TagHelpers.
[HtmlTargetElement("p")]
public class AutoLinkerHttpTagHelper : TagHelper
{
{
var childContent = await output.GetChildContentAsync();
// Find Urls in the content and replace them with their anchor tag equivalent.
output.Content.SetHtmlContent(Regex.Replace(
childContent.GetContent(),
@"\b(?:https?://)(\S+)\b",
"<a target=\"_blank\" href=\"$0\">$0</a>")); // http link version}
}
}
NOTE
A classe AutoLinkerHttpTagHelper é direcionada a elementos p e usa o Regex para criar a âncora.
2. Adicione a seguinte marcação ao final do arquivo Views/Home/Contact.cshtml:

@{
}
<address>
425.555.0100
</address>
<address>
</address>
<p>Visit us at http://docs.asp.net or at www.microsoft.com</p>
3. Execute o aplicativo e verifique se o tag helper renderiza a âncora corretamente.

4. Atualize a classe AutoLinker para incluir o AutoLinkerWwwTagHelper que converterá o texto www em uma
marca de âncora que também contém o texto www original. O código atualizado é realçado abaixo:
{
{
@"\b(?:https?://)(\S+)\b",
}
}
public class AutoLinkerWwwTagHelper : TagHelper
{
{
@"\b(www\.)(\S+)\b",
"<a target=\"_blank\" href=\"http://$0\">$0</a>")); // www version
}
}
}
5. Execute o aplicativo. Observe que o texto www é renderizado como um link, ao contrário do texto HTTP.
Se você colocar um ponto de interrupção em ambas as classes, poderá ver que a classe do auxiliar de
marca HTTP é executada primeiro. O problema é que a saída do auxiliar de marca é armazenada em
cache e quando o auxiliar de marca WWW é executado, ele substitui a saída armazenada em cache do
auxiliar de marca HTTP. Mais adiante no tutorial, veremos como controlar a ordem na qual os auxiliares
de marca são executados. Corrigiremos o código com o seguinte:
{
{
var childContent = output.Content.IsModified ? output.Content.GetContent() :
(await output.GetChildContentAsync()).GetContent();
childContent,
@"\b(?:https?://)(\S+)\b",
}
}
public class AutoLinkerWwwTagHelper : TagHelper
{
{
childContent,
@"\b(www\.)(\S+)\b",
"<a target=\"_blank\" href=\"http://$0\">$0</a>")); // www version
}
}
NOTE
Na primeira edição os tag helpers de vinculação automática, você obteve o conteúdo do destino com o código a
seguir:
Ou seja, você chama GetChildContentAsync usando a TagHelperOutput passada para o método

ProcessAsync . Conforme mencionado anteriormente, como a saída é armazenada em cache, o último auxiliar de
marca a ser executado vence. Você corrigiu o problema com o seguinte código:

O código acima verifica se o conteúdo foi modificado e, em caso afirmativo, ele obtém o conteúdo do buffer de
saída.
6. Execute o aplicativo e verifique se os dois links funcionam conforme esperado. Embora possa parecer
que nosso auxiliar de marca de vinculador automático está correto e completo, ele tem um problema
sutil. Se o auxiliar de marca WWW for executado primeiro, os links www não estarão corretos. Atualize o
código adicionando a sobrecarga Order para controlar a ordem em que a marca é executada. A
propriedade Order determina a ordem de execução em relação aos outros auxiliares de marca
direcionados ao mesmo elemento. O valor de ordem padrão é zero e as instâncias com valores mais
baixos são executadas primeiro.
{
// This filter must run before the AutoLinkerWwwTagHelper as it searches and replaces http and
// the AutoLinkerWwwTagHelper adds http to the markup.
public override int Order
{
get { return int.MinValue; }
}
O código acima garante que o auxiliar de marca HTTP seja executado antes do auxiliar de marca WWW.
Altere Order para MaxValue e verifique se a marcação gerada para a marcação WWW está incorreta.
Inspecionar e recuperar o conteúdo filho

Os tag helpers fornecem várias propriedades para recuperar o conteúdo.
O resultado de GetChildContentAsync pode ser acrescentado ao output.Content .
Inspecione o resultado de GetChildContentAsync com GetContent .
Se você modificar output.Content , o corpo da TagHelper não será executado ou renderizado, a menos que
você chame GetChildContentAsync como em nossa amostra de vinculador automático:

{
{
childContent,
@"\b(?:https?://)(\S+)\b",
}
}
Várias chamadas a GetChildContentAsync retornam o mesmo valor e não executam o corpo TagHelper
novamente, a menos que você passe um parâmetro falso indicando para não usar o resultado armazenado
em cache.
Por Rick Anderson, Dave Paquette e Jerrie Pelser

Este documento demonstra como é o trabalho com Formulários e os elementos HTML usados comumente em um
Formulário. O elemento HTML Formulário fornece o mecanismo primário que os aplicativos Web usam para
postar dados para o servidor. A maior parte deste documento descreve os Auxiliares de marca e como eles podem
ajudar você a criar formulários HTML robustos de forma produtiva. É recomendável que você leia Introdução ao
auxiliares de marca antes de ler este documento.
Em muitos casos, os Auxiliares HTML fornecem uma abordagem alternativa a um Auxiliar de Marca específico,
mas é importante reconhecer que os Auxiliares de Marca não substituem os Auxiliares HTML e que não há um
Auxiliar de Marca para cada Auxiliar HTML. Quando existe um Auxiliar HTML alternativo, ele é mencionado.
O Auxiliar de marca de formulário

O Auxiliar de marca de formulário:
Gera o valor do atributo HTML <FORM> action para uma ação do controlador MVC ou uma rota
nomeada
Gera um Token de verificação de solicitação oculto para evitar a falsificação de solicitações entre sites
(quando usado com o atributo [ValidateAntiForgeryToken] no método de ação HTTP Post)
Fornece o atributo asp-route-<Parameter Name> , em que <Parameter Name> é adicionado aos valores de rota.
Os parâmetros routeValues para Html.BeginForm e Html.BeginRouteForm fornecem funcionalidade
semelhante.
Tem uma alternativa de Auxiliar HTML Html.BeginForm e Html.BeginRouteForm
Amostra:
<form asp-controller="Demo" asp-action="Register" method="post">


</form>
O Auxiliar de marca de formulário acima gera o HTML a seguir:
<form method="post" action="/Demo/Register">

<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>" />
</form>
O tempo de execução do MVC gera o valor do atributo action dos atributos asp-controller e asp-action do
Auxiliar de marca de formulário. O Auxiliar de marca de formulário também gera um Token de verificação de
solicitação oculto para evitar a falsificação de solicitações entre sites (quando usado com o atributo
[ValidateAntiForgeryToken] no método de ação HTTP Post). É difícil proteger um Formulário HTML puro contra
falsificação de solicitações entre sites e o Auxiliar de marca de formulário fornece este serviço para você.
Usando uma rota nomeada
O atributo do Auxiliar de Marca asp-route também pode gerar a marcação para o atributo HTML action . Um
aplicativo com uma rota chamada register poderia usar a seguinte marcação para a página de registro:
<form asp-route="register" method="post">

</form>
Muitas das exibições na pasta Modos de Exibição/Conta (gerada quando você cria um novo aplicativo Web com
Contas de usuário individuais) contêm o atributo asp-route-returnurl:
<form asp-controller="Account" asp-action="Login"

asp-route-returnurl="@ViewData["ReturnUrl"]"
method="post" class="form-horizontal" role="form">
NOTE
Com os modelos internos, returnUrl só é preenchido automaticamente quando você tenta acessar um recurso autorizado,
mas não está autenticado ou autorizado. Quando você tenta fazer um acesso não autorizado, o middleware de segurança o
redireciona para a página de logon com o returnUrl definido.
O auxiliar de marca de entrada

O Auxiliar de marca de entrada associa um elemento HTML <input> a uma expressão de modelo em sua exibição
do Razor.
Sintaxe:
<input asp-for="<Expression Name>" />
O auxiliar de marca de entrada:

Gera os atributos HTML id e para o nome da expressão especificada no atributo asp-for .
name
asp-for="Property1.Property2" equivale a m => m.Property1.Property2 . O nome da expressão é o que é
usado para o valor do atributo asp-for . Consulte a seção Nomes de expressão para obter informações
adicionais.
Define o valor do atributo HTML type com base nos atributos de tipo de modelo e anotação de dados
aplicados à propriedade de modelo
O valor do atributo HTML type não será substituído quando um for especificado
Gera atributos de validação HTML5 de atributos de anotação de dados aplicados a propriedades de modelo
Tem uma sobreposição de recursos de Auxiliar HTML com Html.TextBoxFor e Html.EditorFor . Consulte a
seção Alternativas de Auxiliar HTML ao Auxiliar de marca de entrada para obter detalhes.
Fornece tipagem forte. Se o nome da propriedade for alterado e você não atualizar o Auxiliar de marca, você
verá um erro semelhante ao seguinte:
An error occurred during the compilation of a resource required to process
this request. Please review the following specific error details and modify
your source code appropriately.
Type expected
'RegisterViewModel' does not contain a definition for 'Email' and no
extension method 'Email' accepting a first argument of type 'RegisterViewModel'
could be found (are you missing a using directive or an assembly reference?)
O Auxiliar de marca Input define o atributo HTML type com base no tipo .NET. A tabela a seguir lista alguns
tipos .NET comuns e o tipo HTML gerado (não estão listados todos os tipos .NET).
TIPO .NET TIPO DE ENTRADA
Bool type="checkbox"
Cadeia de Caracteres type="text"
DateTime type="datetime"
Byte type="number"
int type="number"
Single e Double type="number"
A tabela a seguir mostra alguns atributos de anotações de dados comuns que o auxiliar de marca de entrada
mapeará para tipos de entrada específicos (não são listados todos os atributos de validação):
ATRIBUTO TIPO DE ENTRADA
[EmailAddress] type="email"
[Url] type="url"
[HiddenInput] type="hidden"
[Phone] type="tel"
[DataType(DataType.Password)] type="password"
[DataType(DataType.Date)] type="date"
[DataType(DataType.Time)] type="time"
Amostra:
namespace FormsTagHelper.ViewModels
{
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
[Required]
}
}
@model RegisterViewModel
<form asp-controller="Demo" asp-action="RegisterInput" method="post">

Email: <input asp-for="Email" /> <br />
Password: <input asp-for="Password" /><br />
<button type="submit">Register</button>
</form>
O código acima gera o seguinte HTML:
<form method="post" action="/Demo/RegisterInput">

Email:
<input type="email" data-val="true"
data-val-email="The Email Address field is not a valid email address."
data-val-required="The Email Address field is required."
id="Email" name="Email" value="" /> <br>
Password:
<input type="password" data-val="true"
data-val-required="The Password field is required."
id="Password" name="Password" /><br>
</form>
As anotações de dados aplicadas às propriedades Email e Password geram metadados no modelo. O Auxiliar de
marca de entrada consome os metadados do modelo e produz atributos HTML5 data-val-* (consulte Validação
de modelo). Esses atributos descrevem os validadores a serem anexados aos campos de entrada. Isso fornece
validação de jQuery e HTML5 discreto. Os atributos discretos têm o formato data-val-rule="Error Message" , em
que a regra é o nome da regra de validação (como data-val-required , data-val-email , data-val-maxlength etc.) Se
uma mensagem de erro for fornecida no atributo, ela será exibida como o valor para do atributo data-val-rule .
Também há atributos do formulário data-val-ruleName-argumentName="argumentValue" que fornecem detalhes
adicionais sobre a regra, por exemplo, data-val-maxlength-max="1024" .
Alternativas de Auxiliar HTML ao Auxiliar de marca de entrada
Html.TextBox , Html.TextBoxFor , Html.Editor e Html.EditorFor têm recursos que se sobrepõem aos di Auxiliar de
marca de entrada. O Auxiliar de marca de entrada define automaticamente o atributo type ; Html.TextBox e
Html.TextBoxFor não o fazem. Html.Editor e Html.EditorFor manipulam coleções, objetos complexos e modelos;
o Auxiliar de marca de entrada não o faz. O Auxiliar de marca de entrada, Html.EditorFor e Html.TextBoxFor são
fortemente tipados (eles usam expressões lambda); Html.TextBox e Html.Editor não usam (eles usam nomes de
expressão).
HtmlAttributes
@Html.Editor() e @Html.EditorFor() usam uma entrada ViewDataDictionary especial chamada htmlAttributes ao
executar seus modelos padrão. Esse comportamento pode ser aumentado usando parâmetros additionalViewData .
A chave "htmlAttributes" diferencia maiúsculas de minúsculas. A chave "htmlAttributes" é tratada de forma
semelhante ao objeto htmlAttributes passado para auxiliares de entrada como @Html.TextBox() .
@Html.EditorFor(model => model.YourProperty,

new { htmlAttributes = new { @class="myCssClass", style="Width:100px" } })
Nomes de expressão
O valor do atributo asp-for é um ModelExpression e o lado direito de uma expressão lambda. Portanto,
asp-for="Property1" se torna m => m.Property1 no código gerado e é por isso você não precisa colocar o prefixo
Model . Você pode usar o caractere "@" para iniciar uma expressão embutida e mover para antes de m. :
@{
var joe = "Joe";
}
<input asp-for="@joe" />
Gera o seguinte:
<input type="text" id="joe" name="joe" value="Joe" />
Com propriedades de coleção, asp-for="CollectionProperty[23].Member" gera o mesmo nome que

asp-for="CollectionProperty[i].Member" quando i tem o valor 23 .
Quando o ASP.NET Core MVC calcula o valor de ModelExpression , ele inspeciona várias fontes, inclusive o
ModelState . Considere o <input type="text" asp-for="@Name" /> . O atributo value calculado é o primeiro valor
não nulo:
Da entrada de ModelState com a chave "Name".
Do resultado da expressão Model.Name .
Navegando para propriedades filho
Você também pode navegar para propriedades filho usando o caminho da propriedade do modelo de exibição.
Considere uma classe de modelo mais complexa que contém uma propriedade Address filho.
public class AddressViewModel

{
public string AddressLine1 { get; set; }
}
public class RegisterAddressViewModel

{
public AddressViewModel Address { get; set; }

}
Na exibição, associamos a Address.AddressLine1 :

@model RegisterAddressViewModel
<form asp-controller="Demo" asp-action="RegisterAddress" method="post">

Address: <input asp-for="Address.AddressLine1" /><br />
</form>
O HTML a seguir é gerado para Address.AddressLine1 :
<input type="text" id="Address_AddressLine1" name="Address.AddressLine1" value="" />
Nomes de expressão e coleções

Exemplo, um modelo que contém uma matriz de Colors :
public class Person

{
public List<string> Colors { get; set; }
public int Age { get; set; }

}
O método de ação:
public IActionResult Edit(int id, int colorIndex)

{
ViewData["Index"] = colorIndex;
return View(GetPerson(id));
}
O Razor a seguir mostra como você acessa um elemento Color específico:
@model Person
@{
var index = (int)ViewData["index"];
}
<form asp-controller="ToDo" asp-action="Edit" method="post">

@Html.EditorFor(m => m.Colors[index])
<label asp-for="Age"></label>
<input asp-for="Age" /><br />
<button type="submit">Post</button>
</form>
O modelo Views/Shared/EditorTemplates/String.cshtml:
@model string
<label asp-for="@Model"></label>
<input asp-for="@Model" /> <br />
Exemplo usando List<T> :

{
public bool IsDone { get; set; }

}
O Razor a seguir mostra como iterar em uma coleção:
@model List<ToDoItem>

<table>
<tr> <th>Name</th> <th>Is Done</th> </tr>
@for (int i = 0; i < Model.Count; i++)

{
<tr>
@Html.EditorFor(model => model[i])
</tr>
}
</table>
</form>
O modelo Views/Shared/EditorTemplates/ToDoItem.cshtml:
@model ToDoItem
<td>
<label asp-for="@Model.Name"></label>
@Html.DisplayFor(model => model.Name)
</td>
<td>
<input asp-for="@Model.IsDone" />
</td>
@*
This template replaces the following Razor which evaluates the indexer three times.
<td>
<label asp-for="@Model[i].Name"></label>
@Html.DisplayFor(model => model[i].Name)
</td>
<td>
<input asp-for="@Model[i].IsDone" />
</td>
*@
NOTE
Sempre use for (e não foreach ) para iterar em uma lista. Avaliar um indexador em uma expressão LINQ pode ser caro e
deve feito o mínimo possível.
NOTE
O código de exemplo comentado acima mostra como você substituiria a expressão lambda pelo operador @ para acessar
cada ToDoItem na lista.
Auxiliar de marca de área de texto

O auxiliar de marca Textarea Tag Helper é semelhante ao Auxiliar de marca de entrada.
Gera os atributos id e name , bem como os atributos de validação de dados do modelo para um elemento
<textarea>.
Fornece tipagem forte.
Alternativa de Auxiliar HTML: Html.TextAreaFor
Amostra:
{
public class DescriptionViewModel
{
[MinLength(5)]
[MaxLength(1024)]
public string Description { get; set; }
}
}
@model DescriptionViewModel
<form asp-controller="Demo" asp-action="RegisterTextArea" method="post">

<textarea asp-for="Description"></textarea>
<button type="submit">Test</button>
</form>
O HTML a seguir é gerado:
<form method="post" action="/Demo/RegisterTextArea">

<textarea data-val="true"
data-val-maxlength="The field Description must be a string or array type with a maximum length of
'1024'."
data-val-maxlength-max="1024"
data-val-minlength="The field Description must be a string or array type with a minimum length of
'5'."
data-val-minlength-min="5"
id="Description" name="Description">
</textarea>
</form>
O auxiliar de marca de rótulo

Gera a legenda do rótulo e o atributo for em um elemento para um nome de expressão
Alternativa de Auxiliar HTML: Html.LabelFor .
O Label Tag Helper fornece os seguintes benefícios em comparação com um elemento de rótulo HTML puro:
Você obtém automaticamente o valor do rótulo descritivo do atributo Display . O nome de exibição
desejado pode mudar com o tempo e a combinação do atributo Display e do Auxiliar de Marca de Rótulo
aplicará Display em qualquer lugar em que for usado.
Menos marcação no código-fonte
Tipagem forte com a propriedade de modelo.
Amostra:
{
public class SimpleViewModel
{
[Required]
[EmailAddress]
}
}
@model SimpleViewModel
<form asp-controller="Demo" asp-action="RegisterLabel" method="post">

<label asp-for="Email"></label>
<input asp-for="Email" /> <br />
</form>
O HTML a seguir é gerado para o elemento <label> :
<label for="Email">Email Address</label>
O Auxiliar de marca de rótulo gerou o valor do atributo for de "Email", que é a ID associada ao elemento
<input> . Auxiliares de marca geram elementos id e for consistentes para que eles possam ser associados
corretamente. A legenda neste exemplo é proveniente do atributo Display . Se o modelo não contivesse um
atributo Display , a legenda seria o nome da propriedade da expressão.
Os auxiliares de marca de validação

Há dois auxiliares de marca de validação. O Validation Message Tag Helper (que exibe uma mensagem de
validação para uma única propriedade em seu modelo) e o Validation Summary Tag Helper (que exibe um resumo
dos erros de validação). O Input Tag Helper adiciona atributos de validação do lado do cliente HTML5 para
elementos de entrada baseados em atributos de anotação de dados em suas classes de modelo. A validação
também é executada no servidor. O Auxiliar de marca de validação exibe essas mensagens de erro quando ocorre
um erro de validação.
O Auxiliar de marca de mensagem de validação
Adiciona o atributo data-valmsg-for="property" HTML5 ao elemento span, que anexa as mensagens de erro
de validação no campo de entrada da propriedade do modelo especificado. Quando ocorre um erro de
validação do lado do cliente, jQuery exibe a mensagem de erro no elemento <span> .
A validação também é feita no servidor. Os clientes poderão ter o JavaScript desabilitado e parte da
validação só pode ser feita no lado do servidor.
Alternativa de Auxiliar HTML: Html.ValidationMessageFor
O Validation Message Tag Helper é usado com o atributo asp-validation-for em um elemento HTML span.
<span asp-validation-for="Email"></span>
O Auxiliar de marca de mensagem de validação gerará o HTML a seguir:
<span class="field-validation-valid"
data-valmsg-for="Email"
data-valmsg-replace="true"></span>
Geralmente, você usa o Validation Message Tag Helper após um Auxiliar de marca Input para a mesma
propriedade. Fazer isso exibe as mensagens de erro de validação próximo à entrada que causou o erro.
NOTE
É necessário ter uma exibição com as referências de script jQuery e JavaScript corretas em vigor para a validação do lado do
cliente. Consulte Validação de Modelo para obter mais informações.
Quando ocorre um erro de validação do lado do servidor (por exemplo, quando você tem validação do lado do
servidor personalizada ou a validação do lado do cliente está desabilitada), o MVC coloca essa mensagem de erro
como o corpo do elemento <span> .
<span class="field-validation-error" data-valmsg-for="Email"

data-valmsg-replace="true">
The Email Address field is required.
</span>
Auxiliar de marca de resumo de validação

Tem como alvo elementos <div> com o atributo asp-validation-summary
Alternativa de Auxiliar HTML: @Html.ValidationSummary
O Validation Summary Tag Helper é usado para exibir um resumo das mensagens de validação. O valor do atributo
asp-validation-summary pode ser qualquer um dos seguintes:
ASP-VALIDATION-SUMMARY MENSAGENS DE VALIDAÇÃO EXIBIDAS
ValidationSummary.All Nível da propriedade e do modelo
ValidationSummary.ModelOnly Modelo
ValidationSummary.None Nenhum
Amostra
No exemplo a seguir, o modelo de dados é decorado com atributos DataAnnotation , o que gera mensagens de erro
de validação no elemento <input> . Quando ocorre um erro de validação, o Auxiliar de marca de validação exibe a
mensagem de erro:
{
{
[Required]
[EmailAddress]
[Required]
}
}
<form asp-controller="Demo" asp-action="RegisterValidation" method="post">

<div asp-validation-summary="ModelOnly"></div>
<span asp-validation-for="Email"></span><br />
<span asp-validation-for="Password"></span><br />
</form>
O código HTML gerado (quando o modelo é válido):
<form action="/DemoReg/Register" method="post">

<div class="validation-summary-valid" data-valmsg-summary="true">
<ul><li style="display:none"></li></ul></div>
Email: <input name="Email" id="Email" type="email" value=""
data-val-required="The Email field is required."
data-val-email="The Email field is not a valid email address."
data-val="true"> <br>
<span class="field-validation-valid" data-valmsg-replace="true"
data-valmsg-for="Email"></span><br>
Password: <input name="Password" id="Password" type="password"
data-val-required="The Password field is required." data-val="true"><br>
data-valmsg-for="Password"></span><br>
</form>
Auxiliar de Marca de Seleção

Gera select e os elementos option associados para as propriedades do modelo.
Tem uma alternativa de Auxiliar HTML Html.DropDownListFor e Html.ListBoxFor
O Select Tag Helper asp-for especifica o nome da propriedade do modelo para o elemento select e asp-items
especifica os elementos option. Por exemplo:
<select asp-for="Country" asp-items="Model.Countries"></select>
Amostra:
{
public class CountryViewModel
{
public string Country { get; set; }
public List<SelectListItem> Countries { get; } = new List<SelectListItem>

{
new SelectListItem { Value = "MX", Text = "Mexico" },
new SelectListItem { Value = "CA", Text = "Canada" },
new SelectListItem { Value = "US", Text = "USA" },
};
}
}
O método Index inicializa o CountryViewModel , define o país selecionado e o transmite para a exibição Index .

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}
O método Index HTTP POST exibe a seleção:
[HttpPost]
public IActionResult Index(CountryViewModel model)
{
{
var msg = model.Country + " selected";
return RedirectToAction("IndexSuccess", new { message = msg});
}
// If we got this far, something failed; redisplay form.

return View(model);
}
A exibição Index :
@model CountryViewModel
<form asp-controller="Home" asp-action="Index" method="post">

<br /><button type="submit">Register</button>
</form>
Que gera o seguinte HTML (com "CA" selecionado):

<form method="post" action="/">
<select id="Country" name="Country">
<option value="MX">Mexico</option>
<option selected="selected" value="CA">Canada</option>
<option value="US">USA</option>
</select>
</form>
NOTE
Não é recomendável usar ViewBag ou ViewData com o Auxiliar de Marca de Seleção. Um modelo de exibição é mais
robusto para fornecer metadados MVC e, geralmente, menos problemático.
O valor do atributo asp-for é um caso especial e não requer um prefixo Model , os outros atributos do Auxiliar de
marca requerem (como asp-items )
Associação de enumeração
Geralmente, é conveniente usar <select> com uma propriedade enum e gerar os elementos SelectListItem dos
valores enum .
Amostra:
public class CountryEnumViewModel

{
public CountryEnum EnumCountry { get; set; }
}
}
{
public enum CountryEnum
{
[Display(Name = "United Mexican States")]
Mexico,
[Display(Name = "United States of America")]
USA,
Canada,
France,
Germany,
Spain
}
}
O método GetEnumSelectList gera um objeto SelectList para uma enumeração.

@model CountryEnumViewModel
<form asp-controller="Home" asp-action="IndexEnum" method="post">

<select asp-for="EnumCountry"
asp-items="Html.GetEnumSelectList<CountryEnum>()"> >
</select>
</form>
É possível decorar sua lista de enumeradores com o atributo Display para obter uma interface do usuário mais
rica:
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}
<form method="post" action="/Home/IndexEnum">

<select data-val="true" data-val-required="The EnumCountry field is required."
id="EnumCountry" name="EnumCountry">
<option value="0">United Mexican States</option>
<option value="1">United States of America</option>
<option value="2">Canada</option>
<option value="3">France</option>
<option value="4">Germany</option>
<option selected="selected" value="5">Spain</option>
</select>
</form>
Grupo de opções
O elemento HTML <optgroup> é gerado quando o modelo de exibição contém um ou mais objetos
SelectListGroup .
O CountryViewModelGroup agrupa os elementos SelectListItem nos grupos "América do Norte" e "Europa":

public class CountryViewModelGroup
{
public CountryViewModelGroup()
{
var NorthAmericaGroup = new SelectListGroup { Name = "North America" };
var EuropeGroup = new SelectListGroup { Name = "Europe" };
Countries = new List<SelectListItem>

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
Group = NorthAmericaGroup
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}
public List<SelectListItem> Countries { get; }
Os dois grupos são mostrados abaixo:

O HTML gerado:
<form method="post" action="/Home/IndexGroup">

<optgroup label="North America">
<option value="MEX">Mexico</option>
<option value="CAN">Canada</option>
</optgroup>
<optgroup label="Europe">
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</optgroup>
</select>
</form>
Seleção múltipla
O Auxiliar de Marca de Seleção gerará automaticamente o atributo multiple = "multiple" se a propriedade
especificada no atributo asp-for for um IEnumerable . Por exemplo, considerando o seguinte modelo:
{
public class CountryViewModelIEnumerable
{
public IEnumerable<string> CountryCodes { get; set; }

{
new SelectListItem { Value = "FR", Text = "France" },
new SelectListItem { Value = "ES", Text = "Spain" },
new SelectListItem { Value = "DE", Text = "Germany"}
};
}
}
Com a seguinte exibição:

@model CountryViewModelIEnumerable
<form asp-controller="Home" asp-action="IndexMultiSelect" method="post">

<select asp-for="CountryCodes" asp-items="Model.Countries"></select>
</form>
<form method="post" action="/Home/IndexMultiSelect">

<select id="CountryCodes"
multiple="multiple"
name="CountryCodes"><option value="MX">Mexico</option>
<option value="CA">Canada</option>
</select>
</form>
Nenhuma seleção
Se acabar usando a opção "não especificado" em várias páginas, você poderá criar um modelo para eliminar o
HTML de repetição:
<form asp-controller="Home" asp-action="IndexEmpty" method="post">

@Html.EditorForModel()
</form>
O modelo Views/Shared/EditorTemplates/CountryViewModel.cshtml:
<select asp-for="Country" asp-items="Model.Countries">

<option value="">--none--</option>
</select>
O acréscimo de elementos HTML <option> não está limitado ao caso de Nenhuma seleção. Por exemplo, o
seguinte método de ação e exibição gerarão HTML semelhante ao código acima:
public IActionResult IndexOption(int id)

{
return View(model);
}

<select asp-for="Country">
<option value=""><none></option>
</select>
</form>
O elemento <option> correto será selecionado (contém o atributo selected="selected" ) dependendo do valor
atual de Country .
<form method="post" action="/Home/IndexEmpty">

<option value="CA" selected="selected">Canada</option>
</select>
</form>
Recursos adicionais
Elemento de formulário HTML
Token de verificação de solicitação
Associação de modelos no ASP.NET Core
Validação de modelo no ASP.NET Core MVC
Interface IAttributeAdapter
Snippets de código para este documento
Componentes do Auxiliar de Marca no ASP.NET Core
Por Scott Addie e Fiyaz Bin Hasan

Um Componente do Auxiliar de Marca é um Auxiliar de Marca que permite que você modifique ou adicione
condicionalmente elementos HTML de código do lado do servidor. Esse recurso está disponível no ASP.NET Core
2.0 ou posterior.
O ASP.NET Core inclui dois Componentes de Auxiliar de Marca internos: head e body . Eles estão localizados no
namespace Microsoft.AspNetCore.Mvc.Razor.TagHelpers e podem ser usados no MVC e no Razor Pages.
Componentes do Auxiliar de Marca não requerem registro com o aplicativo em _ViewImports.cshtml.
Casos de uso
Dois casos de uso comum dos Componentes do Auxiliar de Marca incluem:
1. Injetar um <link> no <head> .
2. Injetar um <script> no <body> .
As seções a seguir descrevem esses casos de uso.

Injetar no elemento HTML head
Dentro do elemento HTML <head> , os arquivos CSS são geralmente importados com o elemento HTML <link> .
O código a seguir injeta um elemento <link> no elemento <head> usando o Componente do Auxiliar de Marca
head :
using System;
namespace RazorPagesSample.TagHelpers
{
public class AddressStyleTagHelperComponent : TagHelperComponent
{
private readonly string _style =
@"<link rel=""stylesheet"" href=""/css/address.css"" />";
public override int Order => 1;
public override Task ProcessAsync(TagHelperContext context,

TagHelperOutput output)
{
if (string.Equals(context.TagName, "head",
StringComparison.OrdinalIgnoreCase))
{
output.PostContent.AppendHtml(_style);
}
}
}
}
No código anterior:
AddressStyleTagHelperComponent implementa TagHelperComponent. A abstração:
Permite a inicialização da classe com um TagHelperContext.
Habilita o uso de Componentes do Auxiliar de Marca para adicionar ou modificar elementos HTML.
A propriedade Order define a ordem na qual os Componentes são renderizados. Order é necessário quando há
vários usos de Componentes do Auxiliar de Marca em um aplicativo.
ProcessAsync compara o valor da propriedade TagName do contexto de execução com head . Se a comparação
for avaliada como verdadeira, o conteúdo do campo _style será injetado no elemento HTML <head> .
Injetar no elemento HTML body
O Componente do Auxiliar de Marca body pode injetar um elemento <script> no elemento <body> . O código a
seguir demonstra essa técnica:
using System;
using System.IO;
{
public class AddressScriptTagHelperComponent : TagHelperComponent
{
public override async Task ProcessAsync(TagHelperContext context,

{
if (string.Equals(context.TagName, "body",
StringComparison.OrdinalIgnoreCase))
{
var script = await File.ReadAllTextAsync(
"TagHelpers/Templates/AddressToolTipScript.html");
output.PostContent.AppendHtml(script);
}
}
}
}
Um arquivo HTML separado é usado para armazenar o elemento <script> . O arquivo HTML torna o código mais
limpo e mais sustentável. O código anterior lê o conteúdo de TagHelpers/Templates/AddressToolTipScript.html e
acrescenta-o com a saída do Auxiliar de Marca. O arquivo AddressToolTipScript.html inclui a seguinte marcação:
<script>
$("address[printable]").hover(function() {
$(this).attr({
"data-toggle": "tooltip",
"data-placement": "right",
"title": "Home of Microsoft!"
});
});
</script>
O código anterior associa um widget de Dica de ferramenta de inicialização a qualquer elemento <address> que
inclua um atributo printable . O efeito é visível quando um ponteiro do mouse focaliza o elemento.
Registrar um componente
Um Componente do Auxiliar de Marca precisa ser adicionado à coleção de Componentes do Auxiliar de Marca do
aplicativo. Há três maneiras de adicioná-lo à coleção:
1. Registro por contêiner de serviços
2. Registro por arquivo Razor
3. Registro por Modelo de página ou controlador
Registro por contêiner de serviços
Se a classe do Componente do Auxiliar de Marca não for gerenciada com ITagHelperComponentManager, ela
precisará ser registrada com o sistema de DI (injeção de dependência). O código Startup.ConfigureServices a
seguir registra as classes AddressStyleTagHelperComponent e AddressScriptTagHelperComponent com um tempo de
vida transitório:

{
{
});
services.AddMvc()
services.AddTransient<ITagHelperComponent,
AddressScriptTagHelperComponent>();
services.AddTransient<ITagHelperComponent,
AddressStyleTagHelperComponent>();
}
Registro por arquivo Razor

Se o Componente do Auxiliar de Marca não estiver registrado com DI, ele poderá ser registrado por uma página
do Razor Pages ou uma exibição do MVC. Essa técnica é usada para controlar a marcação injetada e o pedido de
execução do componente de um arquivo Razor.
ITagHelperComponentManager é usado para adicionar Componentes do Auxiliar de Marca ou removê-los do
aplicativo. O código a seguir demonstra essa técnica com AddressTagHelperComponent :
@using RazorPagesSample.TagHelpers;
@using Microsoft.AspNetCore.Mvc.Razor.TagHelpers;
@inject ITagHelperComponentManager manager;
@{
string markup;
if (Model.IsWeekend)
{
markup = "<em class='text-warning'>Office closed today!</em>";
}
else
{
markup = "<em class='text-info'>Office open today!</em>";
}
manager.Components.Add(new AddressTagHelperComponent(markup, 1));

}
A diretiva @inject fornece uma instância de ITagHelperComponentManager . A instância é atribuída a uma variável
chamada manager para acesso downstream no arquivo Razor.
Uma instância do AddressTagHelperComponent é adicionada à coleção de Componentes do Auxiliar de Marca do
aplicativo.
AddressTagHelperComponent é modificado para acomodar um construtor que aceita os parâmetros markup e order :
private readonly string _markup;
public override int Order { get; }
public AddressTagHelperComponent(string markup = "", int order = 1)

{
_markup = markup;
Order = order;
}
O parâmetro markup fornecido é usado em ProcessAsync da seguinte maneira:

{
if (string.Equals(context.TagName, "address",
StringComparison.OrdinalIgnoreCase) &&
output.Attributes.ContainsName("printable"))
{
TagHelperContent childContent = await output.GetChildContentAsync();
string content = childContent.GetContent();
$"<div>{content}<br>{_markup}</div>{_printableButton}");
}
}
Registro por Modelo de página ou controlador

Se o Componente do Auxiliar de Marca não estiver registrado com DI, ele poderá ser registrado por um modelo de
página do Razor Pages ou um controlador do MVC. Essa técnica é útil para separar a lógica C# de arquivos Razor.
A injeção do construtor é usada para acessar uma instância de ITagHelperComponentManager . Um Componente do
Auxiliar de Marca é adicionado à coleção de Componentes do Auxiliar de Marca da instância. O modelo de página
do Razor Pages a seguir demonstra essa técnica com AddressTagHelperComponent :
using System;
using Microsoft.AspNetCore.Mvc.Razor.TagHelpers;
using RazorPagesSample.TagHelpers;

{
private readonly ITagHelperComponentManager _tagHelperComponentManager;
public bool IsWeekend

{
get
{
var dayOfWeek = DateTime.Now.DayOfWeek;
return dayOfWeek == DayOfWeek.Saturday ||

dayOfWeek == DayOfWeek.Sunday;
}
}
public IndexModel(ITagHelperComponentManager tagHelperComponentManager)

{
_tagHelperComponentManager = tagHelperComponentManager;
}
public void OnGet()

{
string markup;
if (IsWeekend)
{
markup = "<em class='text-warning'>Office closed today!</em>";
}
else
{
markup = "<em class='text-info'>Office open today!</em>";
}
_tagHelperComponentManager.Components.Add(
new AddressTagHelperComponent(markup, 1));
}
}
A injeção do construtor é usada para acessar uma instância de ITagHelperComponentManager .
Uma instância do AddressTagHelperComponent é adicionada à coleção de Componentes do Auxiliar de Marca do
aplicativo.
Criar um componente
Para criar um Componente do Auxiliar de Marca personalizado:
Crie uma classe pública derivada de TagHelperComponentTagHelper.
Aplique um atributo [HtmlTargetElement] à classe. Especifique o nome do elemento HTML de destino.
Opcional: aplique um atributo [EditorBrowsable(EditorBrowsableState.Never)] à classe para suprimir a exibição
do tipo no IntelliSense.
O código a seguir cria um Componente do Auxiliar de Marca personalizado que tem como destino o elemento
HTML <address> :
using System.ComponentModel;
{
[HtmlTargetElement("address")]
[EditorBrowsable(EditorBrowsableState.Never)]
public class AddressTagHelperComponentTagHelper : TagHelperComponentTagHelper
{
public AddressTagHelperComponentTagHelper(
ITagHelperComponentManager componentManager,
ILoggerFactory loggerFactory) : base(componentManager, loggerFactory)
{
}
}
}
Usar o Componente do Auxiliar de Marca address personalizado para inserir uma marcação HTML da seguinte
maneira:
public class AddressTagHelperComponent : TagHelperComponent

{
private readonly string _printableButton =
"<button type='button' class='btn btn-info' onclick=\"window.open("
"'https://binged.it/2AXRRYw')\">" +
"<span class='glyphicon glyphicon-road' aria-hidden='true'></span>" +
"</button>";

{
if (string.Equals(context.TagName, "address",
StringComparison.OrdinalIgnoreCase) &&
output.Attributes.ContainsName("printable"))
{
var content = await output.GetChildContentAsync();
$"<div>{content.GetContent()}</div>{_printableButton}");
}
}
}
O método ProcessAsync anterior injeta o HTML fornecido para SetHtmlContent no elemento <address>
correspondente. A injeção ocorre quando:
O valor da propriedade TagName do contexto de execução é igual a address .
O elemento <address> correspondente tem um atributo printable .
Por exemplo, a instrução if é avaliada como verdadeira ao processar o seguinte elemento <address> :
<address printable>
Redmond, WA 98052-6399<br />
425.555.0100
</address>
Recursos adicionais
Injeção de dependência no ASP.NET Core
Injeção de dependência em exibições no ASP.NET Core
Auxiliares de marcação internos do ASP.NET Core
Auxiliar de Marca de Âncora no ASP.NET Core
De Peter Kellner e Scott Addie

O Auxiliar de Marca de Âncora aprimora a marca de âncora HTML padrão ( <a ... ></a> ) adicionando novos
atributos. Por convenção, os nomes de atributos são prefixados com asp- . O valor do atributo href do
elemento de âncora renderizado é determinado pelos valores dos atributos asp- .
Para obter uma visão geral dos Auxiliares de Marca, confira Auxiliares de Marca no ASP.NET Core.
SpeakerController é usado em exemplos ao longo de todo este documento:
using System.Linq;
public class SpeakerController : Controller

{
private List<Speaker> Speakers =
new List<Speaker>
{
new Speaker {SpeakerId = 10},
new Speaker {SpeakerId = 11},
new Speaker {SpeakerId = 12}
};
[Route("Speaker/{id:int}")]
public IActionResult Detail(int id) =>
View(Speakers.FirstOrDefault(a => a.SpeakerId == id));
[Route("/Speaker/Evaluations",
Name = "speakerevals")]
public IActionResult Evaluations() => View();
[Route("/Speaker/EvaluationsCurrent",
Name = "speakerevalscurrent")]
public IActionResult Evaluations(
int speakerId,
bool currentYear) => View();
public IActionResult Index() => View(Speakers);

}
public class Speaker

{
public int SpeakerId { get; set; }
}
Segue um inventário dos atributos asp- .
asp-controller
O atributo asp-controller designa o controlador usado para gerar a URL. A marcação a seguir lista todos os
palestrantes:
<a asp-controller="Speaker"
asp-action="Index">All Speakers</a>
O HTML gerado:
<a href="/Speaker">All Speakers</a>
Se o atributo asp-controller for especificado e asp-action não for, o valor asp-action padrão é a ação do
controlador associada ao modo de exibição em execução no momento. Se asp-action for omitido da
marcação anterior e o Auxiliar de Marca de Âncora for usado no modo de exibição Índice (/home) do
HomeController, o HTML gerado será:
<a href="/Home">All Speakers</a>
asp-action
O valor do atributo asp-action representa o nome da ação do controlador incluído no atributo href gerado. A
seguinte marcação define o valor do atributo href gerado para a página de avaliações do palestrante:
asp-action="Evaluations">Speaker Evaluations</a>
O HTML gerado:
<a href="/Speaker/Evaluations">Speaker Evaluations</a>
Se nenhum atributo asp-controller for especificado, o controlador padrão que está chamando a exibição que
executa a exibição atual é usado.
Se o valor do atributo asp-action for Index , nenhuma ação será anexada à URL, causando a invocação da
ação Index padrão. A ação especificada (ou padrão), deve existir no controlador referenciado em
asp-controller .
asp-route-{value}
O atributo asp-route-{value} permite um prefixo de roteamento de caractere curinga. Qualquer valor que
esteja ocupando o espaço reservado {value} é interpretado como um possível parâmetro de roteamento. Se
uma rota padrão não for encontrada, esse prefixo de rota será anexado ao atributo href gerado como um
valor e parâmetro de solicitação. Caso contrário, ele será substituído no modelo de rota.
Considere a seguinte ação do controlador:
public IActionResult AnchorTagHelper(int id)

{
var speaker = new Speaker
{
SpeakerId = id
};
return View(speaker);
}
Com um modelo de rota padrão definido em Startup.Configure:
{
// need route and attribute on controller: [Area("Blogs")]
routes.MapRoute(name: "areaRoute",
template: "{area:exists}/{controller=Home}/{action=Index}");
// default route for non-areas

routes.MapRoute(
name: "default",
});
O modo de exibição MVC usa o modelo fornecido pela ação, da seguinte forma:
@model Speaker
<!DOCTYPE html>
<html>
<body>
asp-action="Detail"
asp-route-id="@Model.SpeakerId">SpeakerId: @Model.SpeakerId</a>
</body>
</html>
O espaço reservado {id?} da rota padrão foi correspondido. O HTML gerado:
<a href="/Speaker/Detail/12">SpeakerId: 12</a>
Suponha que o prefixo de roteamento não faça parte do modelo de roteamento de correspondência, como
com o seguinte modo de exibição de MVC:
@model Speaker
<!DOCTYPE html>
<html>
<body>
asp-action="Detail"
asp-route-speakerid="@Model.SpeakerId">SpeakerId: @Model.SpeakerId</a>
<body>
</html>
O seguinte HTML é gerado porque o speakerid não foi encontrado na rota correspondente:
<a href="/Speaker/Detail?speakerid=12">SpeakerId: 12</a>
Se asp-controller ou asp-action não forem especificados, o mesmo processamento padrão será seguido,
como no atributo asp-route .
asp-route
O atributo asp-route é usado para criar um link de URL diretamente para uma rota nomeada. Usando
atributos de roteamento, uma rota pode ser nomeada como mostrado em SpeakerController e usada em sua
ação Evaluations :
[Route("/Speaker/Evaluations",
Name = "speakerevals")]
public IActionResult Evaluations() => View();
Na seguinte marcação, o atributo asp-route faz referência à rota nomeada:
<a asp-route="speakerevals">Speaker Evaluations</a>
O Auxiliar de Marca de Âncora gera uma rota diretamente para essa ação de controlador usando a URL
/Speaker/Evaluations. O HTML gerado:
<a href="/Speaker/Evaluations">Speaker Evaluations</a>
Se asp-controller ou asp-action for especificado além de asp-route , a rota gerada poderá não ser a
esperada. Para evitar um conflito de rota, asp-route não deve ser usado com os atributos asp-controller ou
asp-action .
asp-all-route-data
O atributo asp-all-route-data oferece suporte à criação de um dicionário ou par chave-valor. A chave é o nome
do parâmetro e o valor é o valor do parâmetro.
No exemplo a seguir, um dicionário é inicializado e passado para um modo de exibição Razor. Como
alternativa, os dados podem ser passado com seu modelo.
@{
var parms = new Dictionary<string, string>
{
{ "speakerId", "11" },
{ "currentYear", "true" }
};
}
<a asp-route="speakerevalscurrent"
asp-all-route-data="parms">Speaker Evaluations</a>
O código anterior gera o seguinte HTML:
<a href="/Speaker/EvaluationsCurrent?speakerId=11&currentYear=true">Speaker Evaluations</a>
O dicionário asp-all-route-data é simplificado para produzir um querystring que atenda aos requisitos da
ação Evaluations sobrecarregada:
[Route("/Speaker/EvaluationsCurrent",
Name = "speakerevalscurrent")]
public IActionResult Evaluations(
int speakerId,
bool currentYear) => View();
Se todas as chaves no dicionário corresponderem aos parâmetros, esses valores serão substituídos na rota
conforme apropriado. Os outros valores não correspondentes são gerados como parâmetros de solicitação.
asp-fragment
O atributo asp-fragment define um fragmento de URL para anexar à URL. O Auxiliar de Marca de Âncora
adiciona o caractere de hash (#). Considere a seguinte marcação:
asp-action="Evaluations"
asp-fragment="SpeakerEvaluations">Speaker Evaluations</a>
O HTML gerado:
<a href="/Speaker/Evaluations#SpeakerEvaluations">Speaker Evaluations</a>
As marcas de hash são úteis ao criar aplicativos do lado do cliente. Elas podem ser usadas para marcar e
pesquisar com facilidade em JavaScript, por exemplo.
asp-area
O atributo asp-area define o nome de área usado para definir a rota apropriada. O exemplo a seguir ilustra
como o atributo de área causa um remapeamento das rotas. Definir asp-area como "Blogs" faz com que o
diretório Áreas/Blogs seja prefixado nas rotas dos controladores e exibições associados a essa marca de
âncora.
{Nome do projeto}
wwwroot
Áreas
Blogs
Controladores
HomeController.cs
Exibições
Início
AboutBlog.cshtml
Index.cshtml
_ViewStart.cshtml
Controladores
Dada a hierarquia do diretório anterior, a marcação para referenciar o arquivo AboutBlog.cshtml é:
<a asp-area="Blogs"
asp-controller="Home"
asp-action="AboutBlog">About Blog</a>
O HTML gerado:
<a href="/Blogs/Home/AboutBlog">About Blog</a>

TIP
Para que as áreas funcionem em um aplicativo MVC, o modelo de rota deve incluir uma referência à área, se ela existir.
Esse modelo é representado pelo segundo parâmetro da chamada do método routes.MapRoute em Startup.Configure:
{
// need route and attribute on controller: [Area("Blogs")]
routes.MapRoute(name: "areaRoute",
template: "{area:exists}/{controller=Home}/{action=Index}");
// default route for non-areas

routes.MapRoute(
name: "default",
});
asp-protocol
O atributo asp-protocol é destinado a especificar um protocolo (como https ) em sua URL. Por exemplo:
<a asp-protocol="https"
asp-action="About">About</a>
O HTML gerado:
<a href="https://localhost/Home/About">About</a>
O nome do host no exemplo é localhost, mas o Auxiliar de Marca de Âncora usará o domínio público do site
ao gerar a URL.
asp-host
O atributo asp-host é para especificar um nome do host na sua URL. Por exemplo:
<a asp-protocol="https"
asp-host="microsoft.com"
asp-action="About">About</a>
O HTML gerado:
<a href="https://microsoft.com/Home/About">About</a>
asp-page
O atributo asp-page é usado com as Páginas Razor. Use-o para definir um valor de atributo href da marca de
âncora para uma página específica. Prefixar o nome de página com uma barra ("/") cria a URL.
O exemplo a seguir aponta para o participante da Página Razor:
<a asp-page="/Attendee">All Attendees</a>

O HTML gerado:
<a href="/Attendee">All Attendees</a>
O atributo asp-page é mutuamente exclusivo com os atributos asp-route , asp-controller e asp-action . No

entanto, o asp-page pode ser usado com o asp-route-{value} para controlar o roteamento, como mostra a
marcação a seguir:
<a asp-page="/Attendee"
asp-route-attendeeid="10">View Attendee</a>
O HTML gerado:
<a href="/Attendee?attendeeid=10">View Attendee</a>
asp-page-handler
O atributo asp-page-handler é usado com as Páginas Razor. Ele se destina à vinculação a manipuladores de
página específicos.
Considere o seguinte manipulador de página:
public void OnGetProfile(int attendeeId)

{
ViewData["AttendeeId"] = attendeeId;
// code omitted for brevity

}
A marcação associada do modelo de página vincula ao manipulador de página OnGetProfile . Observe que o
prefixo On<Verb> do nome do método do manipulador de página é omitido no valor do atributo
asp-page-handler . Se esse fosse um método assíncrono, o sufixo Async também seria omitido.
<a asp-page="/Attendee"
asp-page-handler="Profile"
asp-route-attendeeid="12">Attendee Profile</a>
O HTML gerado:
<a href="/Attendee?attendeeid=12&handler=Profile">Attendee Profile</a>
Recursos adicionais
Auxiliar de Marca de Cache no ASP.NET Core MVC
Por Peter Kellner e Luke Latham

O Auxiliar de Marca de Cache possibilita melhorar o desempenho de seu aplicativo ASP.NET Core armazenando
seu conteúdo em cache no provedor de cache interno do ASP.NET Core.
A seguinte marcação Razor armazena em cache a data atual:
<cache>@DateTime.Now</cache>
A primeira solicitação para a página que contém o Auxiliar de Marca exibe a data atual. Solicitações adicionais
mostram o valor armazenado em cache até que o cache expire (padrão de 20 minutos) ou até que a data em
cache seja removida do cache.
Atributos do Auxiliar de Marca de Cache

habilitado
TIPO DE ATRIBUTO EXEMPLOS PADRÃO
Boolean true , false true
enabled determina se o conteúdo envolto pelo Auxiliar de Marca de Cache é armazenado em cache. O padrão é
true . Se definido como false , a saída renderizada não é armazenada em cache.
Exemplo:
<cache enabled="true">
Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>
expires-on
TIPO DE ATRIBUTO EXEMPLO
DateTimeOffset @new DateTime(2025,1,29,17,02,0)
expires-on define uma data do término absoluta para o item em cache.

O exemplo a seguir armazena em cache o conteúdo do Auxiliar de Marca de Cache até às 17:02 de 29 de janeiro
de 2025:
<cache expires-on="@new DateTime(2025,1,29,17,02,0)">

</cache>
expires-after
TIPO DE ATRIBUTO EXEMPLO PADRÃO
TimeSpan @TimeSpan.FromSeconds(120) 20 minutos
expires-after define o tempo decorrido desde a primeira solicitação para armazenar o conteúdo em cache.
Exemplo:
<cache expires-after="@TimeSpan.FromSeconds(120)">
</cache>
O Mecanismo de Exibição do Razor define o valor expires-after padrão como vinte minutos.
expires-sliding
TimeSpan @TimeSpan.FromSeconds(60)
Define a hora em que uma entrada de cache deverá ser removida se o seu valor não tiver sido acessado.
Exemplo:
<cache expires-sliding="@TimeSpan.FromSeconds(60)">
</cache>
vary-by-header
TIPO DE ATRIBUTO EXEMPLOS
Cadeia de Caracteres User-Agent , User-Agent,content-encoding
vary-by-header aceita uma lista delimitada por vírgulas de valores de cabeçalho que disparam uma atualização
do cache quando eles mudam.
O exemplo a seguir monitora o valor do cabeçalho User-Agent . O exemplo armazena em cache o conteúdo para
cada User-Agent diferente apresentado ao servidor Web:
<cache vary-by-header="User-Agent">
</cache>
vary-by-query
Cadeia de Caracteres Make , Make,Model
vary-by-query aceita uma lista delimitada por vírgula de Keys em uma cadeia de consulta (Query) que dispara
uma atualização do cache quando o valor de qualquer chave listada é alterado.
O exemplo a seguir monitora os valores de Make e Model . O exemplo armazena em cache o conteúdo para
todos os diferentes Make e Model apresentados ao servidor Web:
<cache vary-by-query="Make,Model">
</cache>
vary-by-route
Cadeia de Caracteres Make , Make,Model
vary-by-route aceita uma lista delimitada por vírgulas de valores de cabeçalho que disparam uma atualização
do cache quando o valor de parâmetro de dados de rota muda.
Exemplo:
Startup.cs:
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{Make?}/{Model?}");
Index.cshtml:
<cache vary-by-route="Make,Model">
</cache>
vary-by-cookie
Cadeia de Caracteres .AspNetCore.Identity.Application ,

.AspNetCore.Identity.Application,HairColor
vary-by-cookie aceita uma lista delimitada por vírgulas de valores de cabeçalho que disparam uma atualização
do cache quando os valores de cabeçalho mudam.
O exemplo a seguir monitora o cookie associado à identidade do ASP.NET Core. Quando um usuário é
autenticado, uma alteração ao cookie de Identidade dispara uma atualização do cache:
<cache vary-by-cookie=".AspNetCore.Identity.Application">
</cache>
vary-by-user
Boolean true , false true
vary-by-userespecifica se o cache é redefinido ou não quando o usuário conectado (ou a Entidade de Contexto)
muda. O usuário atual também é conhecido como a Entidade do contexto de solicitação e pode ser exibido em
um modo de exibição do Razor referenciando @User.Identity.Name .
O exemplo a seguir monitora o usuário conectado atual para disparar uma atualização de cache:
<cache vary-by-user="true">
</cache>
Usar esse atributo mantém o conteúdo no cache durante um ciclo de entrada e saída. Quando o valor é definido
como true , um ciclo de autenticação invalida o cache para o usuário autenticado. O cache é invalidado porque
um novo valor de cookie exclusivo é gerado quando um usuário é autenticado. O cache é mantido para o estado
anônimo quando nenhum cookie está presente ou quando o cookie expirou. Se o usuário não estiver
autenticado, o cache será mantido.
vary-by
Cadeia de Caracteres @Model
vary-by permite a personalização de quais dados são armazenados em cache. Quando o objeto referenciado
pelo valor de cadeia de caracteres do atributo é alterado, o conteúdo do Auxiliar de Marca de Cache é atualizado.
Frequentemente, uma concatenação de cadeia de caracteres de valores do modelo é atribuída a este atributo. Na
verdade, isso resulta em um cenário em que uma atualização de qualquer um dos valores concatenados invalida
o cache.
O exemplo a seguir supõe que o método do controlador que renderiza a exibição somas o valor inteiro dos dois
parâmetros de rota, myParam1 e myParam2 , e os retorna a soma como a propriedade de modelo única. Quando
essa soma é alterada, o conteúdo do Auxiliar de Marca de Cache é renderizado e armazenado em cache
novamente.
Ação:
public IActionResult Index(string myParam1, string myParam2, string myParam3)

{
int num1;
int num2;
int.TryParse(myParam1, out num1);
int.TryParse(myParam2, out num2);
return View(viewName, num1 + num2);
}
Index.cshtml:
<cache vary-by="@Model">
</cache>
priority
CacheItemPriority High , Low , NeverRemove , Normal Normal
priority fornece diretrizes de remoção do cache para o provedor de cache interno. O servidor Web remove
entradas de cache Low primeiro quando está sob demanda de memória.
Exemplo:
<cache priority="High">
</cache>
O atributo priority não assegura um nível específico de retenção de cache. CacheItemPriority é apenas uma
sugestão. Configurar esse atributo como NeverRemove não assegura que os itens armazenados em cache sempre
sejam retidos. Veja os tópicos na seção Recursos Adicionais para obter mais informações.
O Auxiliar de Marca de Cache é dependente do serviço de cache de memória. O Auxiliar de Marca de Cache
adicionará o serviço se ele não tiver sido adicionado.
Recursos adicionais
Memória de cache no ASP.NET Core
Introdução à identidade do ASP.NET Core
Auxiliar de Marca de Cache Distribuído no ASP.NET
Core
Por Peter Kellner e Luke Latham

O Auxiliar de Marca de Cache Distribuído fornece a capacidade de melhorar consideravelmente o desempenho
do aplicativo ASP.NET Core armazenando seu conteúdo em cache em uma fonte de cache distribuído.
O Auxiliar de Marca de Cache Distribuído herda da mesma classe base do Auxiliar de Marca de Cache. Todos os
atributos de Auxiliar de Marca de Cache estão disponíveis ao Auxiliar de Marca Distribuído.
O Auxiliar de Marca de Cache distribuído usa injeção de construtor. A interface IDistributedCache é passada para
o construtor do Auxiliar de Marca de Cache Distribuído. Se nenhuma implementação concreta de
IDistributedCache for criada em Startup.ConfigureServices ( Startup.cs), o Auxiliar de Marca de Cache
Distribuído usará o mesmo provedor na memória para armazenar dados em cache como o Auxiliar de Marca de
Cache.
Atributos do auxiliar de marca de cache distribuído

Atributos compartilhados com o Auxiliar de Marca de Cache
enabled
expires-on
expires-after
expires-sliding
vary-by-header
vary-by-query
vary-by-route
vary-by-cookie
vary-by-user
vary-by priority
O Auxiliar de Marca de Cache Distribuído herda da mesma classe que o Auxiliar de Marca de Cache. Para obter
descrições desses atributos, confira Auxiliar de Marca de Cache.
name
Cadeia de Caracteres my-distributed-cache-unique-key-101
name é obrigatório. O atributo name é usado como uma chave para cada instância de cache armazenada. Ao
contrário do Auxiliar de Marca de Cache que atribui uma chave de cache a cada instância com base no nome da
página do Razor e na localização na página do Razor, o Auxiliar de Marca de Cache Distribuído somente localiza
suas chaves no atributo name .
Exemplo:
<distributed-cache name="my-distributed-cache-unique-key-101">
Time Inside Cache Tag Helper: @DateTime.Now
</distributed-cache>
Implementações de IDistributedCache do Auxiliar de Marca de Cache

Distribuído
Há duas implementações de IDistributedCache internas do ASP.NET Core. Uma é baseada no SQL Server e a
outra, no Redis. Os detalhes dessas implementações podem ser encontrados em O cache no ASP.NET Core
distribuído. Ambas as implementações envolvem configurar de uma instância do IDistributedCache em Startup .
Não há nenhum atributo de marca especificamente associado ao uso de uma implementação específica de
IDistributedCache .
Recursos adicionais
Injeção de dependência no ASP.NET Core
O cache no ASP.NET Core distribuído
Auxiliar de Marca de Ambiente no ASP.NET Core
Por Peter Kellner, Hisham Bin Ateya e Luke Latham

O Auxiliar de Marca de Ambiente renderiza condicionalmente seu conteúdo contido com base no ambiente de
hospedagem atual. Atributo único do Auxiliar de Marca de Ambiente, names , é uma lista separada por vírgulas de
nomes de ambiente. Se nenhum dos nomes de ambiente fornecido corresponder ao ambiente atual, o conteúdo
contido será renderizado.
Atributos do Auxiliar de Marca de Ambiente

nomes
names aceita um único nome de ambiente de hospedagem ou uma lista separada por vírgula de nomes de
ambiente de hospedagem que disparam a renderização do conteúdo contido.
Valores de ambiente são comparados com o valor retornado por IHostingEnvironment.EnvironmentName. A
comparação ignora o uso de maiúsculas.
O exemplo a seguir usa um Auxiliar de Marca de Ambiente. O conteúdo será renderizado se o ambiente de
hospedagem for De Preparo ou de Produção:
<strong>HostingEnvironment.EnvironmentName is Staging or Production</strong>
</environment>
incluir e excluir atributos

Os atributos include & exclude controlam a renderização do conteúdo contido com base nos nomes de
ambiente de hospedagem incluídos ou excluídos.
include
A propriedade include exibe um comportamento semelhante para o atributo names . Um ambiente listado no
valor do atributo include deve corresponder ao ambiente de hospedagem do aplicativo
(IHostingEnvironment.EnvironmentName) para renderizar o conteúdo da marcação <environment> .
<environment include="Staging,Production">
<strong>HostingEnvironment.EnvironmentName is Staging or Production</strong>
</environment>
exclude
Em contraste com o atributo include , o conteúdo da marcação <environment> é processado quando o ambiente
de hospedagem não corresponde a um ambiente listado no valor do atributo exclude .
<strong>HostingEnvironment.EnvironmentName is not Development</strong>
</environment>
Recursos adicionais


nomeada
semelhante.
Amostra:

</form>

</form>

</form>

NOTE

do Razor.
Sintaxe:

name
adicionais.
Type expected
Byte type="number"
int type="number"
[Url] type="url"
[Phone] type="tel"
Amostra:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>
expressão).
HtmlAttributes

Nomes de expressão
@{
var joe = "Joe";
}
Gera o seguinte:

não nulo:

{
}

{

}


</form>

public class Person

{

}

{
}
@model Person
@{
}

</form>
@model string

{

}

<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
NOTE

<textarea>.
Amostra:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

'1024'."
'5'."
</textarea>
</form>

Amostra:
{
{
[Required]
[EmailAddress]
}
}

</form>

NOTE

</span>

Amostra
mensagem de erro:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

Amostra:
{
{

{
};
}
}

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}

</form>

</select>
</form>
NOTE
valores enum .
Amostra:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
rica:
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
Grupo de opções
SelectListGroup .

{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

O HTML gerado:

</optgroup>
</optgroup>
</select>
</form>
Seleção múltipla
{
{

{
};
}
}


</form>

multiple="multiple"
</select>
</form>
Nenhuma seleção

</form>

</select>

{
return View(model);
}

</select>
</form>
atual de Country .

</select>
</form>
Recursos adicionais
Auxiliar de Marca de Imagem no ASP.NET Core
Por Peter Kellner

O Auxiliar de Marca de Imagem aprimora a marca <img> para fornecer comportamento de extrapolação de cache
para arquivos de imagem estática.
Uma cadeia de caracteres de extrapolação de cache é um valor exclusivo que representa o hash do arquivo de
imagem estática acrescentado à URL do ativo. A cadeia de caracteres exclusiva solicita que os clientes (e alguns
proxies) recarreguem a imagem do servidor Web do host, e não do cache do cliente.
Se a origem da imagem ( src ) for um arquivo estático no servidor Web de host:
Uma cadeia de caracteres exclusiva de extrapolação de cache será anexada como um parâmetro de consulta à
origem da imagem.
Se o arquivo no servidor Web host for alterado, será gerada uma URL de solicitação exclusiva que inclua o
parâmetro de solicitação atualizado.
Atributos de Auxiliar de Marca de Imagem

src
Para ativar o Auxiliar de Marca de Imagem, o atributo src é obrigatório no elemento <img> .
A origem da imagem ( src ) deve apontar para um arquivo estático físico no servidor. Se src for um URI remoto,
o parâmetro de cadeia de caracteres de consulta de extrapolação de cache não será gerado.
asp-append-version
Quando asp-append-version for especificado com um valor true junto com um atributo src , o Auxiliar de Marca
de Imagem será invocado.
O exemplo a seguir usa um Auxiliar de Marca de Imagem:
<img src="~/images/asplogo.png" asp-append-version="true" />
Se o arquivo estático existe no diretório /wwwroot/images/, o HTML gerado é semelhante ao seguinte (o hash será
diferente):
<img src="/images/asplogo.png?v=Kl_dqr9NVtnMdsM2MUg4qthUnWZm5T1fCEimBPWDNgM" />
O valor atribuído ao parâmetro v é o valor de hash do arquivo asplogo.png em disco. Se o servidor Web não
conseguir obter acesso de leitura ao arquivo estático, nenhum parâmetro v será adicionado ao atributo src na
marcação renderizada.
Comportamento de armazenamento em cache de hash

O Auxiliar de Marca de Imagem usa o provedor de cache no servidor Web local para armazenar o hash Sha512
calculado de um determinado arquivo. Se o arquivo for solicitado várias vezes, o hash não será recalculado. O
cache é invalidado por um observador de arquivo anexado ao arquivo quando o hash Sha512 do arquivo é
calculado. Quando o arquivo muda no disco, um novo hash é calculado e armazenado em cache.
Recursos adicionais


nomeada
semelhante.
Amostra:

</form>

</form>

</form>

NOTE

do Razor.
Sintaxe:

name
adicionais.
Type expected
Byte type="number"
int type="number"
[Url] type="url"
[Phone] type="tel"
Amostra:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>
expressão).
HtmlAttributes

Nomes de expressão
@{
var joe = "Joe";
}
Gera o seguinte:

não nulo:

{
}

{

}


</form>

public class Person

{

}

{
}
@model Person
@{
}

</form>
@model string

{

}

<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
NOTE

<textarea>.
Amostra:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

'1024'."
'5'."
</textarea>
</form>

Amostra:
{
{
[Required]
[EmailAddress]
}
}

</form>

NOTE

</span>

Amostra
mensagem de erro:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

Amostra:
{
{

{
};
}
}

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}

</form>

</select>
</form>
NOTE
valores enum .
Amostra:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
rica:
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
Grupo de opções
SelectListGroup .

{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

O HTML gerado:

</optgroup>
</optgroup>
</select>
</form>
Seleção múltipla
{
{

{
};
}
}


</form>

multiple="multiple"
</select>
</form>
Nenhuma seleção

</form>

</select>

{
return View(model);
}

</select>
</form>
atual de Country .

</select>
</form>
Recursos adicionais


nomeada
semelhante.
Amostra:

</form>

</form>

</form>

NOTE

do Razor.
Sintaxe:

name
adicionais.
Type expected
Byte type="number"
int type="number"
[Url] type="url"
[Phone] type="tel"
Amostra:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>
expressão).
HtmlAttributes

Nomes de expressão
@{
var joe = "Joe";
}
Gera o seguinte:

não nulo:

{
}

{

}


</form>

public class Person

{

}

{
}
@model Person
@{
}

</form>
@model string

{

}

<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
NOTE

<textarea>.
Amostra:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

'1024'."
'5'."
</textarea>
</form>

Amostra:
{
{
[Required]
[EmailAddress]
}
}

</form>

NOTE

</span>

Amostra
mensagem de erro:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

Amostra:
{
{

{
};
}
}

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}

</form>

</select>
</form>
NOTE
valores enum .
Amostra:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
rica:
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
Grupo de opções
SelectListGroup .

{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

O HTML gerado:

</optgroup>
</optgroup>
</select>
</form>
Seleção múltipla
{
{

{
};
}
}


</form>

multiple="multiple"
</select>
</form>
Nenhuma seleção

</form>

</select>

{
return View(model);
}

</select>
</form>
atual de Country .

</select>
</form>
Recursos adicionais
Auxiliar de marca parcial no ASP.NET Core
Por Scott Addie

Visão geral
O auxiliar de marca parcial é usado para renderizar uma exibição parcial em Páginas Razor e em aplicativos
MVC. Considere que ele:
Exige o ASP.NET Core 2.1 ou posterior.
É uma alternativa à sintaxe do HTML Helper.
Renderiza a exibição parcial de forma assíncrona.
As opções do HTML Helper para renderizar uma exibição parcial incluem:
@await Html.PartialAsync
@await Html.RenderPartialAsync
@Html.Partial
@Html.RenderPartial
O modelo Product é usado nos exemplos ao longo deste documento:
namespace TagHelpersBuiltIn.Models
{
public class Product
{
public int Number { get; set; }

}
}
Segue um inventário dos atributos do auxiliar de marca parcial.
name
O atributo name é necessário. Indica o nome ou o caminho da exibição parcial a ser renderizada. Quando é
fornecido um nome de exibição parcial, o processo descoberta de exibição é iniciado. Esse processo é ignorado
quando um caminho explícito é fornecido. Para todos os valores de name aceitáveis, consulte Descoberta de
exibição parcial.
A marcação a seguir usa um caminho explícito, indicando que _ProductPartial.cshtml deve ser carregado da
pasta Compartilhado. Usando o atributo for, um modelo é passado para a exibição parcial para associação.
<partial name="Shared/_ProductPartial.cshtml"
for="Product" />
for
O atributo for atribui uma ModelExpression a ser avaliada em relação ao modelo atual. Uma ModelExpression
infere a sintaxe @Model. . Por exemplo, for="Product" pode ser usado em vez de for="@Model.Product" . Esse
comportamento de inferência padrão é substituído usando o símbolo @ para definir uma expressão embutida.
O for atributo não pode ser usado com o atributo modelo.
A seguinte marcação carrega _ProductPartial.cshtml:
<partial name="_ProductPartial"
for="Product" />
A exibição parcial é associada à propriedade Product do modelo de página associado:
using TagHelpersBuiltIn.Models;
namespace TagHelpersBuiltIn.Pages
{
public class ProductModel : PageModel
{
public Product Product { get; set; }
public void OnGet()

{
Product = new Product
{
Number = 1,
Name = "Test product",
Description = "This is a test product"
};
}
}
}
modelo
O atributo model atribui uma instância de modelo a ser passada para a exibição parcial. O atributo model não
pode ser usado com o atributo for.
Na marcação a seguir, é criada uma nova instância do objeto Product que é passada ao atributo model para
associação:
<partial name="_ProductPartial"
model='new Product { Number = 1, Name = "Test product", Description = "This is a test" }' />
view-data
O atributo view-data atribui um ViewDataDictionary a ser passado para a exibição parcial. A seguinte marcação
faz com que toda a coleção ViewData fique acessível para a exibição parcial:
@{
ViewData["IsNumberReadOnly"] = true;
}
<partial name="_ProductViewDataPartial"
for="Product"
view-data="ViewData" />
No código anterior, o valor da chave IsNumberReadOnly é definido como true e adicionado à coleção ViewData.
Consequentemente, ViewData["IsNumberReadOnly"] se torna acessível dentro da exibição parcial a seguir:
@model TagHelpersBuiltIn.Models.Product
<label asp-for="Number"></label>
@if ((bool)ViewData["IsNumberReadOnly"])
{
<input asp-for="Number" type="number" class="form-control" readonly />
}
else
{
<input asp-for="Number" type="number" class="form-control" />
}
</div>
<label asp-for="Name"></label>
<input asp-for="Name" type="text" class="form-control" />
</div>
<label asp-for="Description"></label>
<textarea asp-for="Description" rows="4" cols="50" class="form-control"></textarea>
</div>
Neste exemplo, o valor de ViewData["IsNumberReadOnly"] determina se o campo Número é exibido como

somente leitura.
Migrar de um auxiliar HTML

Considere o seguinte exemplo de auxiliar HTML assíncrono. Uma coleção de produtos é iterada e exibida.
Segundo o primeiro parâmetro do método PartialAsync , a exibição parcial _ProductPartial.cshtml é carregada.
Uma instância do modelo Product é passada para a exibição parcial para associação.
@foreach (var product in Model.Products)

{
@await Html.PartialAsync("_ProductPartial", product)
}
O auxiliar de marca parcial seguir alcança o mesmo comportamento de renderização assíncrona que o auxiliar
HTML PartialAsync . Uma instância de modelo Product é atribuída ao atributo model para associação à
exibição parcial.
@foreach (var product in Model.Products)

{
<partial name="_ProductPartial" model="product" />
}
Recursos adicionais


nomeada
semelhante.
Amostra:

</form>

</form>

</form>

NOTE

do Razor.
Sintaxe:

name
adicionais.
Type expected
Byte type="number"
int type="number"
[Url] type="url"
[Phone] type="tel"
Amostra:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>
expressão).
HtmlAttributes

Nomes de expressão
@{
var joe = "Joe";
}
Gera o seguinte:

não nulo:

{
}

{

}


</form>

public class Person

{

}

{
}
@model Person
@{
}

</form>
@model string

{

}

<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
NOTE

<textarea>.
Amostra:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

'1024'."
'5'."
</textarea>
</form>

Amostra:
{
{
[Required]
[EmailAddress]
}
}

</form>

NOTE

</span>

Amostra
mensagem de erro:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

Amostra:
{
{

{
};
}
}

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}

</form>

</select>
</form>
NOTE
valores enum .
Amostra:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
rica:
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
Grupo de opções
SelectListGroup .

{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

O HTML gerado:

</optgroup>
</optgroup>
</select>
</form>
Seleção múltipla
{
{

{
};
}
}


</form>

multiple="multiple"
</select>
</form>
Nenhuma seleção

</form>

</select>

{
return View(model);
}

</select>
</form>
atual de Country .

</select>
</form>
Recursos adicionais


nomeada
semelhante.
Amostra:

</form>

</form>

</form>

NOTE

do Razor.
Sintaxe:

name
adicionais.
Type expected
Byte type="number"
int type="number"
[Url] type="url"
[Phone] type="tel"
Amostra:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>
expressão).
HtmlAttributes

Nomes de expressão
@{
var joe = "Joe";
}
Gera o seguinte:

não nulo:

{
}

{

}


</form>

public class Person

{

}

{
}
@model Person
@{
}

</form>
@model string

{

}

<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
NOTE

<textarea>.
Amostra:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

'1024'."
'5'."
</textarea>
</form>

Amostra:
{
{
[Required]
[EmailAddress]
}
}

</form>

NOTE

</span>

Amostra
mensagem de erro:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

Amostra:
{
{

{
};
}
}

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}

</form>

</select>
</form>
NOTE
valores enum .
Amostra:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
rica:
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
Grupo de opções
SelectListGroup .

{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

O HTML gerado:

</optgroup>
</optgroup>
</select>
</form>
Seleção múltipla
{
{

{
};
}
}


</form>

multiple="multiple"
</select>
</form>
Nenhuma seleção

</form>

</select>

{
return View(model);
}

</select>
</form>
atual de Country .

</select>
</form>
Recursos adicionais


nomeada
semelhante.
Amostra:

</form>

</form>

</form>

NOTE

do Razor.
Sintaxe:

name
adicionais.
Type expected
Byte type="number"
int type="number"
[Url] type="url"
[Phone] type="tel"
Amostra:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>
expressão).
HtmlAttributes

Nomes de expressão
@{
var joe = "Joe";
}
Gera o seguinte:

não nulo:

{
}

{

}


</form>

public class Person

{

}

{
}
@model Person
@{
}

</form>
@model string

{

}

<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
NOTE

<textarea>.
Amostra:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

'1024'."
'5'."
</textarea>
</form>

Amostra:
{
{
[Required]
[EmailAddress]
}
}

</form>

NOTE

</span>

Amostra
mensagem de erro:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

Amostra:
{
{

{
};
}
}

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}

</form>

</select>
</form>
NOTE
valores enum .
Amostra:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
rica:
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
Grupo de opções
SelectListGroup .

{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

O HTML gerado:

</optgroup>
</optgroup>
</select>
</form>
Seleção múltipla
{
{

{
};
}
}


</form>

multiple="multiple"
</select>
</form>
Nenhuma seleção

</form>

</select>

{
return View(model);
}

</select>
</form>
atual de Country .

</select>
</form>
Recursos adicionais
Auxiliares de marca em formulários no
ASP.NET Core

Este documento demonstra como é o trabalho com Formulários e os elementos
HTML usados comumente em um Formulário. O elemento HTML Formulário
fornece o mecanismo primário que os aplicativos Web usam para postar dados para
o servidor. A maior parte deste documento descreve os Auxiliares de marca e como
eles podem ajudar você a criar formulários HTML robustos de forma produtiva. É
recomendável que você leia Introdução ao auxiliares de marca antes de ler este
documento.
Em muitos casos, os Auxiliares HTML fornecem uma abordagem alternativa a um
Auxiliar de Marca específico, mas é importante reconhecer que os Auxiliares de
Marca não substituem os Auxiliares HTML e que não há um Auxiliar de Marca para
cada Auxiliar HTML. Quando existe um Auxiliar HTML alternativo, ele é mencionado.

Gera o valor do atributo HTML <FORM> action para uma ação do
controlador MVC ou uma rota nomeada
Gera um Token de verificação de solicitação oculto para evitar a falsificação de
solicitações entre sites (quando usado com o atributo
[ValidateAntiForgeryToken] no método de ação HTTP Post)
Fornece o atributo asp-route-<Parameter Name> , em que <Parameter Name> é

adicionado aos valores de rota. Os parâmetros routeValues para
Html.BeginForm e Html.BeginRouteForm fornecem funcionalidade semelhante.
Amostra:

</form>

<input name="__RequestVerificationToken" type="hidden" value="<removed for
brevity>" />
</form>
O tempo de execução do MVC gera o valor do atributo action dos atributos

asp-controller e asp-action do Auxiliar de marca de formulário. O Auxiliar de
marca de formulário também gera um Token de verificação de solicitação oculto para
evitar a falsificação de solicitações entre sites (quando usado com o atributo
[ValidateAntiForgeryToken] no método de ação HTTP Post). É difícil proteger um
Formulário HTML puro contra falsificação de solicitações entre sites e o Auxiliar de
marca de formulário fornece este serviço para você.
O atributo do Auxiliar de Marca asp-route também pode gerar a marcação para o
atributo HTML action . Um aplicativo com uma rota chamada register poderia
usar a seguinte marcação para a página de registro:

</form>
Muitas das exibições na pasta Modos de Exibição/Conta (gerada quando você cria
um novo aplicativo Web com Contas de usuário individuais) contêm o atributo asp-
route-returnurl:

NOTE
Com os modelos internos, returnUrl só é preenchido automaticamente quando você
tenta acessar um recurso autorizado, mas não está autenticado ou autorizado. Quando
você tenta fazer um acesso não autorizado, o middleware de segurança o redireciona para a
página de logon com o returnUrl definido.

O Auxiliar de marca de entrada associa um elemento HTML <input> a uma
expressão de modelo em sua exibição do Razor.
Sintaxe:

Gera os atributos HTML id e name para o nome da expressão especificada
no atributo asp-for . asp-for="Property1.Property2" equivale a
m => m.Property1.Property2 . O nome da expressão é o que é usado para o
valor do atributo asp-for . Consulte a seção Nomes de expressão para obter
informações adicionais.
Define o valor do atributo HTML type com base nos atributos de tipo de
modelo e anotação de dados aplicados à propriedade de modelo
O valor do atributo HTML type não será substituído quando um for
especificado
Gera atributos de validação HTML5 de atributos de anotação de dados
aplicados a propriedades de modelo
Tem uma sobreposição de recursos de Auxiliar HTML com Html.TextBoxFor e
Html.EditorFor . Consulte a seção Alternativas de Auxiliar HTML ao
Auxiliar de marca de entrada para obter detalhes.
Fornece tipagem forte. Se o nome da propriedade for alterado e você não
atualizar o Auxiliar de marca, você verá um erro semelhante ao seguinte:

Type expected
O Auxiliar de marca Input define o atributo HTML type com base no tipo .NET. A
tabela a seguir lista alguns tipos .NET comuns e o tipo HTML gerado (não estão
listados todos os tipos .NET).
Byte type="number"
int type="number"
A tabela a seguir mostra alguns atributos de anotações de dados comuns que o

auxiliar de marca de entrada mapeará para tipos de entrada específicos (não são
listados todos os atributos de validação):
[Url] type="url"
[Phone] type="tel"
Amostra:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
data-val-email="The Email Address field is not a valid email
address."
Password:
brevity>" />
</form>
As anotações de dados aplicadas às propriedades Email e Password geram

metadados no modelo. O Auxiliar de marca de entrada consome os metadados do
modelo e produz atributos HTML5 data-val-* (consulte Validação de modelo). Esses
atributos descrevem os validadores a serem anexados aos campos de entrada. Isso
fornece validação de jQuery e HTML5 discreto. Os atributos discretos têm o formato
data-val-rule="Error Message" , em que a regra é o nome da regra de validação
(como data-val-required , data-val-email , data-val-maxlength etc.) Se uma
mensagem de erro for fornecida no atributo, ela será exibida como o valor para do
atributo data-val-rule . Também há atributos do formulário
data-val-ruleName-argumentName="argumentValue" que fornecem detalhes adicionais
sobre a regra, por exemplo, data-val-maxlength-max="1024" .
Html.TextBox , Html.TextBoxFor , Html.Editor e Html.EditorFor têm recursos que se
sobrepõem aos di Auxiliar de marca de entrada. O Auxiliar de marca de entrada
define automaticamente o atributo type ; Html.TextBox e Html.TextBoxFor não o
fazem. Html.Editor e Html.EditorFor manipulam coleções, objetos complexos e
modelos; o Auxiliar de marca de entrada não o faz. O Auxiliar de marca de entrada,
Html.EditorFor e Html.TextBoxFor são fortemente tipados (eles usam expressões
lambda); Html.TextBox e Html.Editor não usam (eles usam nomes de expressão).
HtmlAttributes
@Html.Editor() e usam uma entrada ViewDataDictionary especial
@Html.EditorFor()
chamada htmlAttributes ao executar seus modelos padrão. Esse comportamento
pode ser aumentado usando parâmetros additionalViewData . A chave
"htmlAttributes" diferencia maiúsculas de minúsculas. A chave "htmlAttributes" é
tratada de forma semelhante ao objeto htmlAttributes passado para auxiliares de
entrada como @Html.TextBox() .

Nomes de expressão
O valor do atributo asp-for é um ModelExpression e o lado direito de uma
expressão lambda. Portanto, asp-for="Property1" se torna m => m.Property1 no
código gerado e é por isso você não precisa colocar o prefixo Model . Você pode usar
o caractere "@" para iniciar uma expressão embutida e mover para antes de m. :
@{
var joe = "Joe";
}
Gera o seguinte:
Com propriedades de coleção, asp-for="CollectionProperty[23].Member" gera o

mesmo nome que asp-for="CollectionProperty[i].Member" quando i tem o valor
23 .
Quando o ASP.NET Core MVC calcula o valor de ModelExpression , ele inspeciona

várias fontes, inclusive o ModelState . Considere o
<input type="text" asp-for="@Name" /> . O atributo value calculado é o primeiro
valor não nulo:
Você também pode navegar para propriedades filho usando o caminho da
propriedade do modelo de exibição. Considere uma classe de modelo mais complexa
que contém uma propriedade Address filho.

{
}

{

}

</form>
<input type="text" id="Address_AddressLine1" name="Address.AddressLine1" value=""

/>

public class Person

{

}

{
}

@model Person
@{
}

</form>
@model string

{

}

<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
This template replaces the following Razor which evaluates the indexer three
times.
<td>
</td>
<td>
</td>
*@
NOTE
Sempre use for (e não foreach ) para iterar em uma lista. Avaliar um indexador em uma
expressão LINQ pode ser caro e deve feito o mínimo possível.
NOTE
O código de exemplo comentado acima mostra como você substituiria a expressão lambda
pelo operador @ para acessar cada ToDoItem na lista.

O auxiliar de marca Textarea Tag Helper é semelhante ao Auxiliar de marca de
entrada.
Gera os atributos id e name , bem como os atributos de validação de dados
do modelo para um elemento <textarea>.
Amostra:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

data-val-maxlength="The field Description must be a string or array type with a
maximum length of '1024'."
data-val-minlength="The field Description must be a string or array type with a
minimum length of '5'."
</textarea>
brevity>" />
</form>

Gera a legenda do rótulo e o atributo for em um elemento para um nome
de expressão
O Label Tag Helper fornece os seguintes benefícios em comparação com um

elemento de rótulo HTML puro:
Você obtém automaticamente o valor do rótulo descritivo do atributo Display
. O nome de exibição desejado pode mudar com o tempo e a combinação do
atributo Display e do Auxiliar de Marca de Rótulo aplicará Display em
qualquer lugar em que for usado.
Amostra:
{
{
[Required]
[EmailAddress]
}
}

</form>
O Auxiliar de marca de rótulo gerou o valor do atributo for de "Email", que é a ID

associada ao elemento <input> . Auxiliares de marca geram elementos id e for
consistentes para que eles possam ser associados corretamente. A legenda neste
exemplo é proveniente do atributo Display . Se o modelo não contivesse um atributo
Display , a legenda seria o nome da propriedade da expressão.

Há dois auxiliares de marca de validação. O Validation Message Tag Helper (que
exibe uma mensagem de validação para uma única propriedade em seu modelo) e o
Validation Summary Tag Helper (que exibe um resumo dos erros de validação). O
Input Tag Helper adiciona atributos de validação do lado do cliente HTML5 para
elementos de entrada baseados em atributos de anotação de dados em suas classes
de modelo. A validação também é executada no servidor. O Auxiliar de marca de
validação exibe essas mensagens de erro quando ocorre um erro de validação.
Adiciona o atributo data-valmsg-for="property" HTML5 ao elemento span,
que anexa as mensagens de erro de validação no campo de entrada da
propriedade do modelo especificado. Quando ocorre um erro de validação do
lado do cliente, jQuery exibe a mensagem de erro no elemento <span> .
A validação também é feita no servidor. Os clientes poderão ter o JavaScript
desabilitado e parte da validação só pode ser feita no lado do servidor.
O Validation Message Tag Helper é usado com o atributo asp-validation-for em um

elemento HTML span.
Geralmente, você usa o Validation Message Tag Helper após um Auxiliar de marca
Input para a mesma propriedade. Fazer isso exibe as mensagens de erro de
validação próximo à entrada que causou o erro.
NOTE
É necessário ter uma exibição com as referências de script jQuery e JavaScript corretas em
vigor para a validação do lado do cliente. Consulte Validação de Modelo para obter mais
informações.
Quando ocorre um erro de validação do lado do servidor (por exemplo, quando você
tem validação do lado do servidor personalizada ou a validação do lado do cliente
está desabilitada), o MVC coloca essa mensagem de erro como o corpo do elemento
<span> .

</span>

O Validation Summary Tag Helper é usado para exibir um resumo das mensagens de
validação. O valor do atributo asp-validation-summary pode ser qualquer um dos
seguintes:
Amostra
No exemplo a seguir, o modelo de dados é decorado com atributos DataAnnotation , o
que gera mensagens de erro de validação no elemento <input> . Quando ocorre um
erro de validação, o Auxiliar de marca de validação exibe a mensagem de erro:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

brevity>" />
</form>

Tem uma alternativa de Auxiliar HTML Html.DropDownListFor e
Html.ListBoxFor
O Select Tag Helper asp-for especifica o nome da propriedade do modelo para o

elemento select e asp-items especifica os elementos option. Por exemplo:

Amostra:
{
{

{
};
}
}
O método Index inicializa o CountryViewModel , define o país selecionado e o

transmite para a exibição Index .

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}

</form>

</select>
brevity>" />
</form>
NOTE
Não é recomendável usar ViewBag ou ViewData com o Auxiliar de Marca de Seleção. Um
modelo de exibição é mais robusto para fornecer metadados MVC e, geralmente, menos
problemático.
O valor do atributo asp-for é um caso especial e não requer um prefixo Model , os

outros atributos do Auxiliar de marca requerem (como asp-items )
Geralmente, é conveniente usar <select> com uma propriedade enum e gerar os
elementos SelectListItem dos valores enum .
Amostra:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
É possível decorar sua lista de enumeradores com o atributo Display para obter
uma interface do usuário mais rica:
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

<select data-val="true" data-val-required="The EnumCountry field is
required."
</select>
<input name="__RequestVerificationToken" type="hidden" value="<removed
for brevity>" />
</form>
Grupo de opções
O elemento HTML <optgroup> é gerado quando o modelo de exibição contém um
ou mais objetos SelectListGroup .
O CountryViewModelGroup agrupa os elementos SelectListItem nos grupos "América
do Norte" e "Europa":
{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

O HTML gerado:

</optgroup>
</optgroup>
</select>
brevity>" />
</form>
Seleção múltipla
O Auxiliar de Marca de Seleção gerará automaticamente o atributo multiple =
"multiple" se a propriedade especificada no atributo asp-for for um IEnumerable .
Por exemplo, considerando o seguinte modelo:
{
{

{
};
}
}

</form>

multiple="multiple"
</select>
brevity>" />
</form>
Nenhuma seleção
Se acabar usando a opção "não especificado" em várias páginas, você poderá criar
um modelo para eliminar o HTML de repetição:

</form>

</select>
O acréscimo de elementos HTML <option> não está limitado ao caso de Nenhuma

seleção. Por exemplo, o seguinte método de ação e exibição gerarão HTML
semelhante ao código acima:

{
return View(model);
}

</select>
</form>
O elemento <option> correto será selecionado (contém o atributo

selected="selected" ) dependendo do valor atual de Country .

</select>
brevity>" />
</form>
Recursos adicionais
Layout no ASP.NET Core
Por Steve Smith e Dave Brock

Páginas e exibições com frequência compartilham elementos visuais e programáticos. Este artigo
demonstra como:
Usar layouts comuns.
Compartilhar diretivas.
Executar o código comum antes de renderizar páginas ou modos de exibição.
Este documento discute os layouts para as duas abordagens diferentes ao ASP.NET Core MVC:
Razor Pages e controladores com exibições. Para este tópico, as diferenças são mínimas:
Razor Pages estão na pasta Pages.
Controladores com exibições usam uma pasta Views pasta exibições.
O que é um layout
A maioria dos aplicativos Web tem um layout comum que fornece aos usuários uma experiência
consistente durante sua navegação de uma página a outra. O layout normalmente inclui elementos
comuns de interface do usuário, como o cabeçalho do aplicativo, elementos de menu ou de
navegação e rodapé.
Estruturas HTML comuns, como scripts e folhas de estilo, também são usadas com frequência por
muitas páginas em um aplicativo. Todos esses elementos compartilhados podem ser definidos em
um arquivo de layout, que pode então ser referenciado por qualquer exibição usada no aplicativo. Os
layouts reduzem o código duplicado em exibições, ajudando-os a seguir o princípio DRY (Don't
Repeat Yourself).
Por convenção, o layout padrão de um aplicativo ASP.NET Core é chamado _Layout.cshtml. O
arquivo de layout para novos projetos do ASP.NET Core criados com os modelos:
Razor Pages: Pages/Shared/_Layout.cshtml
Controlador com exibições: Views/Shared/_Layout.cshtml
O layout define um modelo de nível superior para exibições no aplicativo. Os aplicativos não exigem
um layout. Os aplicativos podem definir mais de um layout, com diferentes exibições especificando
diferentes layouts.
O código a seguir mostra o arquivo de layout para um modelo de projeto criado com um
controlador e exibições:
<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] - WebApplication1</title>
</environment>
<link rel="stylesheet"
href="https://ajax.aspnetcdn.com/ajax/bootstrap/3.3.7/css/bootstrap.min.css"
asp-fallback-test-class="sr-only" asp-fallback-test-property="position" asp-
fallback-test-value="absolute" />
</environment>
</head>
<body>
<button type="button" class="navbar-toggle" data-toggle="collapse" data-
target=".navbar-collapse">
</button>
<a asp-page="/Index" class="navbar-brand">WebApplication1</a>
</div>
</ul>
</div>
</div>
</nav>
<partial name="_CookieConsentPartial" />

@RenderBody()
<hr />
<footer>
<p>© 2018 - WebApplication1</p>
</footer>
</div>
</environment>
integrity="sha384-
tsQFqpEReu7ZLhBV2VZlAu7zcOV+rXbYlF2cqB8txI/8aZajjp4Bqd+V6D5IgvKT">
</script>
integrity="sha384-
Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa">
</script>
</environment>

</body>
</html>
Especificando um layout
As exibições do Razor têm uma propriedade Layout . As exibições individuais especificam um layout
com a configuração dessa propriedade:
@{
Layout = "_Layout";
}
O layout especificado pode usar um caminho completo (por exemplo, /Pages/Shared/_Layout.cshtml

ou /Views/Shared/_Layout.cshtml) ou um nome parcial (exemplo: _Layout ). Quando um nome
parcial for fornecido, o mecanismo de exibição do Razor pesquisará o arquivo de layout usando seu
processo de descoberta padrão. A pasta em que o método do manipulador (ou controlador) existe é
pesquisada primeiro, seguida pela pasta Shared. Esse processo de descoberta é idêntico àquele
usado para descobrir exibições parciais.
Por padrão, todo layout precisa chamar RenderBody . Sempre que a chamada a RenderBody for feita,
o conteúdo da exibição será renderizado.
Seções
Um layout, opcionalmente, pode referenciar uma ou mais seções, chamando RenderSection . As
seções fornecem uma maneira de organizar o local em que determinados elementos da página
devem ser colocados. Cada chamada a RenderSection pode especificar se essa seção é obrigatória
ou opcional:
@section Scripts {
}
Se uma seção obrigatória não for encontrada, uma exceção será gerada. As exibições individuais
especificam o conteúdo a ser renderizado em uma seção usando a sintaxe Razor @section . Se uma
página ou exibição definir uma seção, ela precisará ser renderizada (ou ocorrerá um erro).
Uma definição @section de exemplo na exibição do Razor Pages:
@section Scripts {
<script type="text/javascript" src="/scripts/main.js"></script>
}
No código anterior, scripts/main.js é adicionado à seção scripts em uma página ou exibição. Outras
páginas ou exibições no mesmo aplicativo podem não exigir esse script e não definirão uma seção de
scripts.
A marcação a seguir usa o Auxiliar de Marca Parcial para renderizar _ValidationScriptsPartial.cshtml:
@section Scripts {
<partial name="_ValidationScriptsPartial" />
}
A marcação anterior foi gerada pela Identidade de scaffolding.

As seções definidas em uma página ou exibição estão disponíveis apenas em sua página de layout
imediata. Elas não podem ser referenciadas em parciais, componentes de exibição ou outras partes
do sistema de exibição.
Ignorando seções
Por padrão, o corpo e todas as seções de uma página de conteúdo precisam ser renderizados pela
página de layout. O mecanismo de exibição do Razor impõe isso acompanhando se o corpo e cada
seção foram renderizados.
Para instruir o mecanismo de exibição a ignorar o corpo ou as seções, chame os métodos
IgnoreBody e IgnoreSection .
O corpo e cada seção em uma página do Razor precisam ser renderizados ou ignorados.
Importando diretivas compartilhadas

Exibições e páginas podem usar diretivas do Razor para importar namespaces e usar injeção de
dependência. Diretivas compartilhadas por diversas exibições podem ser especificadas em um
arquivo _ViewImports.cshtml comum. O arquivo _ViewImports dá suporte às seguintes diretivas:
@addTagHelper
@removeTagHelper
@tagHelperPrefix
@using
@model
@inherits
@inject
O arquivo não dá suporte a outros recursos do Razor, como funções e definições de seção.
Um arquivo _ViewImports.cshtml de exemplo:
@using WebApplication1
@using WebApplication1.Models
@using WebApplication1.Models.AccountViewModels
@using WebApplication1.Models.ManageViewModels
@using Microsoft.AspNetCore.Identity
O arquivo _ViewImports.cshtml para um aplicativo ASP.NET Core MVC normalmente é colocado na

pasta Pages (ou Views). Um arquivo _ViewImports.cshtml pode ser colocado em qualquer pasta, caso
em que só será aplicado a páginas ou exibições nessa pasta e em suas subpastas. Arquivos
_ViewImports são processados começando no nível raiz e, em seguida, para cada pasta até o local da
página ou da exibição em si. As configurações _ViewImports especificadas no nível raiz podem ser
substituídas no nível da pasta.
Por exemplo, suponha:
O arquivo _ViewImports.cshtml no nível de raiz inclui @model MyModel1 e
@addTagHelper *, MyTagHelper1 .
Um arquivo _ViewImports.cshtml de subpasta inclui @model MyModel2 e
@addTagHelper *, MyTagHelper2 .
Páginas e exibições na subpasta terão acesso a Auxiliares de Marca e ao modelo MyModel2 .

Se vários arquivos _ViewImports.cshtml forem encontrados na hierarquia de arquivos, o
comportamento combinado das diretivas será:
@addTagHelper , : todos são executados, em ordem
@removeTagHelper
@tagHelperPrefix : o mais próximo à exibição substitui todos os outros
@model : o mais próximo à exibição substitui todos os outros
@inherits : o mais próximo à exibição substitui todos os outros
@using : todos são incluídos; duplicatas são ignoradas
@inject : para cada propriedade, o mais próximo à exibição substitui todos os outros com o
mesmo nome de propriedade
Executando o código antes de cada exibição

Código que precisa ser executado antes de cada exibição ou página precisa ser colocada no arquivo
_ViewStart.cshtml. Por convenção, o arquivo _ViewStart.cshtml está localizado na pasta Pages (ou
Views). As instruções listadas em _ViewStart.cshtml são executadas antes de cada exibição completa
(não layouts nem exibições parciais). Como ViewImports.cshtml, _ViewStart.cshtml é hierárquico. Se
um arquivo _ViewStart.cshtml for definido na pasta de exibições ou páginas, ele será executado
depois daquele definido na raiz da pasta Pages (ou Views) (se houver).
Um arquivo _ViewStart.cshtml de amostra:
@{
Layout = "_Layout";
}
O arquivo acima especifica que todas as exibições usarão o layout _Layout.cshtml.

_ViewStart.cshtml é _ViewImports.cshtml normalmente não são colocados na pasta /Pages/Shared
(ou /Views/Shared). As versões no nível do aplicativo desses arquivos devem ser colocadas
diretamente na pasta /Pages (ou /Views).
Arquivos estáticos no ASP.NET Core
Por Rick Anderson e Scott Addie

Arquivos estáticos, como HTML, CSS, imagens e JavaScript, são ativos que um aplicativo ASP.NET Core
fornece diretamente para os clientes. Algumas etapas de configuração são necessárias para habilitar o
fornecimento desses arquivos.
Fornecer arquivos estáticos

Os arquivos estáticos são armazenados no diretório raiz Web do projeto. O diretório padrão é
<content_root>/wwwroot, mas pode ser alterado por meio do método UseWebRoot. Consulte Raiz de
conteúdo e Diretório base para obter mais informações.
O host Web do aplicativo deve ser informado do diretório raiz do conteúdo.
O método WebHost.CreateDefaultBuilder define a raiz do conteúdo como o diretório atual:

{
{
}

}
Defina a raiz do conteúdo com o diretório atual invocando UseContentRoot dentro de Program.Main :

{
{
.UseKestrel()
.UseApplicationInsights()
.Build();
host.Run();
}
}
Os arquivos estáticos são acessíveis por meio de um caminho relativo ao diretório base. Por exemplo, o
modelo de projeto do Aplicativo Web contém várias pastas dentro da pasta wwwroot:
wwwroot
css
images
js
O formato de URI para acessar um arquivo na subpasta images é
http://<server_address>/images/<image_file_name>. Por exemplo,
http://localhost:9189/images/banner3.svg.
Se estiver direcionando o .NET Framework, adicione o pacote Microsoft.AspNetCore.StaticFiles ao projeto.
Se você estiver direcionando para o .NET Core, o metapacote Microsoft.AspNetCore.App incluirá esse
pacote.
Se estiver direcionando o .NET Framework, adicione o pacote Microsoft.AspNetCore.StaticFiles ao projeto.
Se estiver direcionando o .NET Core, o metapacote Microsoft.AspNetCore.All incluirá esse pacote.
Adicione o pacote Microsoft.AspNetCore.StaticFiles ao projeto.
Configure o middleware que permite o fornecimento de arquivos estáticos.
Fornecer arquivos dentro do diretório base
Invoque o método UseStaticFiles dentro de Startup.Configure :

{
}
A sobrecarga do método UseStaticFiles sem parâmetro marca os arquivos no diretório base como
fornecíveis. A seguinte marcação referencia wwwroot/images/banner1.svg:
<img src="~/images/banner1.svg" alt="ASP.NET" class="img-responsive" />
No código anterior, o caractere til ~/ aponta para o diretório base. Para obter mais informações, confira
Diretório base.
Fornecer arquivos fora do diretório base
Considere uma hierarquia de diretórios na qual os arquivos estáticos a serem atendidos residam fora do
diretório base:
wwwroot
css
images
js
MyStaticFiles
images
banner1.svg
Uma solicitação pode acessar o arquivo banner1.svg configurando o middleware de arquivo estático da
seguinte maneira:
{
app.UseStaticFiles(); // For the wwwroot folder
app.UseStaticFiles(new StaticFileOptions
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), "MyStaticFiles")),
RequestPath = "/StaticFiles"
});
}
No código anterior, a hierarquia de diretórios MyStaticFiles é exposta publicamente por meio do segmento
do URI StaticFiles. Uma solicitação para http://<server_address>/StaticFiles/images/banner1.svg atende ao
arquivo banner1.svg.
A seguinte marcação referencia MyStaticFiles/images/banner1.svg:
<img src="~/StaticFiles/images/banner1.svg" alt="ASP.NET" class="img-responsive" />
Definir cabeçalhos de resposta HTTP

Um objeto StaticFileOptions pode ser usado para definir cabeçalhos de resposta HTTP. Além de configurar
o fornecimento de arquivos estáticos do diretório base, o seguinte código define o cabeçalho
Cache-Control :

{
var cachePeriod = env.IsDevelopment() ? "600" : "604800";
{
OnPrepareResponse = ctx =>
{
// Requires the following import:
ctx.Context.Response.Headers.Append("Cache-Control", $"public, max-age={cachePeriod}");
}
});
}
O método HeaderDictionaryExtensions.Append existe no pacote Microsoft.AspNetCore.Http.

Os arquivos se tornaram armazenáveis em cache publicamente por 10 minutos (600 segundos) no
ambiente de desenvolvimento:
Autorização de arquivo estático

O middleware de arquivo estático não fornece verificações de autorização. Todos os arquivos atendidos,
incluindo aqueles em wwwroot, estão acessíveis publicamente. Para fornecer arquivos com base na
autorização:
Armazene-os fora do wwwroot e de qualquer diretório acessível ao middleware de arquivos estáticos e
Forneça-os por meio de um método de ação ao qual a autorização é aplicada. Retorne um objeto
FileResult:
[Authorize]
public IActionResult BannerImage()
{
var file = Path.Combine(Directory.GetCurrentDirectory(),
"MyStaticFiles", "images", "banner1.svg");
return PhysicalFile(file, "image/svg+xml");

}
Habilitar navegação no diretório

A navegação no diretório permite que os usuários do aplicativo Web vejam uma listagem de diretório e
arquivos em um diretório especificado. A navegação no diretório está desabilitada por padrão por motivos
de segurança (consulte Considerações). Habilite a navegação no diretório invocando o método
UseDirectoryBrowser em Startup.Configure :

{
{
Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
RequestPath = "/MyImages"
});
app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
});
}
Adicione os serviços necessários invocando o método AddDirectoryBrowser em Startup.ConfigureServices

:

{
services.AddDirectoryBrowser();
}
O código anterior permite a navegação no diretório da pasta wwwroot/images usando a URL

http://<server_address>/MyImages, com links para cada arquivo e pasta:
Consulte Considerações para saber mais sobre os riscos de segurança ao habilitar a navegação.
Observe as duas chamadas UseStaticFiles no exemplo a seguir. A primeira chamada permite o
fornecimento de arquivos estáticos na pasta wwwroot. A segunda chamada habilita a navegação no
diretório da pasta wwwroot/images usando a URL http://<server_address>/MyImages:

{
{
});
{
});
}
Fornecer um documento padrão

Definir uma home page padrão fornece ao visitantes um ponto de partida lógico de ao visitar o site. Para
fornecer uma página padrão sem qualificar totalmente o URI do usuário, chame o UseDefaultFiles método
de Startup.Configure :

{
}
IMPORTANT
UseDefaultFiles deve ser chamado antes de UseStaticFiles para fornecer o arquivo padrão.
UseDefaultFiles é um rewriter de URL que, na verdade, não fornece o arquivo. Habilite o middleware de arquivo
estático por meio de UseStaticFiles para fornecer o arquivo.
Com UseDefaultFiles , as solicitações para uma pasta pesquisam:

default.htm
default.html
index.htm
index.html
O primeiro arquivo encontrado na lista é fornecido como se a solicitação fosse o URI totalmente
qualificado. A URL do navegador continua refletindo o URI solicitado.
O seguinte código altera o nome de arquivo padrão para mydefault.html:

{
// Serve my app-specific default file, if present.
DefaultFilesOptions options = new DefaultFilesOptions();
options.DefaultFileNames.Clear();
options.DefaultFileNames.Add("mydefault.html");
app.UseDefaultFiles(options);
}
UseFileServer
UseFileServer combina a funcionalidade de UseStaticFiles , UseDefaultFiles e UseDirectoryBrowser .
O código a seguir permite o fornecimento de arquivos estáticos e do arquivo padrão. A navegação no
diretório não está habilitada.
app.UseFileServer();
O seguinte código baseia-se na sobrecarga sem parâmetros, habilitando a navegação no diretório:
app.UseFileServer(enableDirectoryBrowsing: true);
Considere a seguinte hierarquia de diretórios:

wwwroot
css
images
js
MyStaticFiles
images
banner1.svg
default.html
O seguinte código habilita arquivos estáticos, arquivos padrão e a navegação no diretório de MyStaticFiles
:
{
app.UseFileServer(new FileServerOptions
{
Path.Combine(Directory.GetCurrentDirectory(), "MyStaticFiles")),
RequestPath = "/StaticFiles",
EnableDirectoryBrowsing = true
});
}
AddDirectoryBrowser precisa ser chamado quando o valor da propriedade EnableDirectoryBrowsing é true :

{
services.AddDirectoryBrowser();
}
Com o uso da hierarquia de arquivos e do código anterior, as URLs são resolvidas da seguinte maneira:
URI RESPOSTA
http://<server_address>/StaticFiles/images/banner1.svg MyStaticFiles/images/banner1.svg
http://<server_address>/StaticFiles MyStaticFiles/default.html
Se nenhum arquivo nomeado como padrão existir no diretório MyStaticFiles,

http://<server_address>/StaticFiles retornará a listagem de diretórios com links clicáveis:
NOTE
UseDefaultFiles e UseDirectoryBrowser usam a URL http://<server_address>/StaticFiles sem a barra "" à
direita para disparar um redirecionamento do lado do cliente para http://<server_address>/StaticFiles/. Observe a
adição da barra "" à direita. URLs relativas dentro dos documentos são consideradas inválidas sem uma barra "" à
direita.
FileExtensionContentTypeProvider
A classe FileExtensionContentTypeProvider contém uma propriedade Mappings que serve como um
mapeamento de extensões de arquivo para tipos de conteúdo MIME. Na amostra a seguir, várias extensões
de arquivo são registradas para tipos MIME conhecidos. A extensão .rtf é substituída, e .mp4 é removida.

{
// Set up custom content types - associating file extension to MIME type
var provider = new FileExtensionContentTypeProvider();
// Add new mappings
provider.Mappings[".myapp"] = "application/x-msdownload";
provider.Mappings[".htm3"] = "text/html";
provider.Mappings[".image"] = "image/png";
// Replace an existing mapping
provider.Mappings[".rtf"] = "application/x-msdownload";
// Remove MP4 videos.
provider.Mappings.Remove(".mp4");
{
RequestPath = "/MyImages",
ContentTypeProvider = provider
});
{
});
}
Consulte Tipos de conteúdo MIME.
Tipos de conteúdo não padrão

O middleware de arquivo estático compreende quase 400 tipos de conteúdo de arquivo conhecidos. Se o
usuário solicitar um arquivo com um tipo desconhecido, o middleware de arquivo estático passará a
solicitação para o próximo middleware no pipeline. Se nenhum middleware manipular a solicitação, uma
resposta 404 Não Encontrado será retornada. Se a navegação no diretório estiver habilitada, um link para o
arquivo será exibido na lista do diretório.
O seguinte código habilita o fornecimento de tipos desconhecidos e renderiza o arquivo desconhecido
como uma imagem:

{
{
ServeUnknownFileTypes = true,
DefaultContentType = "image/png"
});
}
Com o código anterior, uma solicitação para um arquivo com um tipo de conteúdo desconhecido é
retornada como uma imagem.
WARNING
A habilitação de ServeUnknownFileTypes é um risco de segurança. Ela está desabilitada por padrão, e seu uso não é
recomendado. FileExtensionContentTypeProvider fornece uma alternativa mais segura para o fornecimento de
arquivos com extensões não padrão.
Considerações
WARNING
UseDirectoryBrowser e UseStaticFiles podem causar a perda de segredos. A desabilitação da navegação no
diretório em produção é altamente recomendada. Examine com atenção os diretórios que são habilitados por meio
de UseStaticFiles ou UseDirectoryBrowser . Todo o diretório e seus subdiretórios se tornam publicamente
acessíveis. Armazene arquivos adequados para fornecimento ao público em um diretório dedicado, como
<content_root>/wwwroot. Separe esses arquivos das exibições MVC, Páginas do Razor (somente 2.x), arquivos de
configuração, etc.
As URLs para o conteúdo exposto com UseDirectoryBrowser e UseStaticFiles estão sujeitas à

diferenciação de maiúsculas e minúsculas e a restrições de caracteres do sistema de arquivos
subjacente. Por exemplo, o Windows diferencia maiúsculas de minúsculas, o macOS e o Linux não.
Os aplicativos ASP.NET Core hospedados no IIS usam o Módulo do ASP.NET Core para
encaminhar todas as solicitações ao aplicativo, inclusive as solicitações de arquivo estático. O
manipulador de arquivos estáticos do IIS não é usado. Ele não tem nenhuma possibilidade de
manipular as solicitações antes que elas sejam manipuladas pelo módulo.
Conclua as etapas seguinte no Gerenciador do IIS para remover o manipulador de arquivos estáticos
no IIS no nível do servidor ou do site:
1. Navegue para o recurso Módulos.
2. Selecione StaticFileModule na lista.
3. Clique em Remover na barra lateral Ações.
WARNING
Se o manipulador de arquivo estático do IIS estiver habilitado e o Módulo do ASP.NET Core não estiver configurado
corretamente, os arquivos estáticos serão atendidos. Isso acontece, por exemplo, se o arquivo web.config não foi
implantado.
Coloque arquivos de código (incluindo .cs e .cshtml) fora do diretório base do projeto do aplicativo.
Portanto, uma separação lógica é criada entre o conteúdo do lado do cliente do aplicativo e o código
baseado em servidor. Isso impede a perda de código do lado do servidor.
Recursos adicionais
Middleware
Por Rachel Appel
Introdução à associação de modelos

A associação de modelos do ASP.NET Core MVC mapeia dados de solicitações HTTP para
parâmetros de método de ação. Os parâmetros podem ser tipos simples, como cadeias de
caracteres, inteiros ou floats, ou podem ser tipos complexos. Esse é um ótimo recurso do MVC,
pois o mapeamento dos dados de entrada para um equivalente é um cenário repetido com
frequência, independentemente do tamanho ou da complexidade dos dados. O MVC resolve
esse problema com a abstração da associação, de modo que os desenvolvedores não precisem
continuar reconfigurando uma versão ligeiramente diferente desse mesmo código em cada
aplicativo. A escrita de seu próprio texto para tipar o código de conversor é entediante e
propensa a erros.
Como funciona a associação de modelos

Quando o MVC recebe uma solicitação HTTP, ele encaminha-a a um método de ação
específico de um controlador. Ele determina qual método de ação será executado com base no
que está nos dados de rota e, em seguida, ele associa valores da solicitação HTTP aos
parâmetros desse método de ação. Por exemplo, considere a seguinte URL:
http://contoso.com/movies/edit/2
Como o modelo de rota é semelhante a isto, {controller=Home}/{action=Index}/{id?} ,

movies/edit/2 encaminha para o controlador Movies e seu método de ação Edit . Ele
também aceita um parâmetro opcional chamado id . O código para o método de ação deve
ter esta aparência:
public IActionResult Edit(int? id)
Observação: as cadeias de caracteres na rota de URL não diferenciam maiúsculas de

minúsculas.
O MVC tentará associar os dados de solicitação aos parâmetros de ação por nome. O MVC
procurará valores para cada parâmetro usando o nome do parâmetro e os nomes de suas
propriedades configuráveis públicas. No exemplo acima, o único parâmetro de ação é chamado
id , que o MVC associa ao valor com o mesmo nome nos valores de rota. Além dos valores de
rota, o MVC associará dados de várias partes da solicitação e faz isso em uma ordem
específica. Veja abaixo uma lista das fontes de dados na ordem em que a associação de
modelos examina-as:
1. : esses são valores de formulário que entram na solicitação HTTP usando o
Form values
método POST. (incluindo as solicitações POST jQuery).
2. Route values : o conjunto de valores de rota fornecido pelo Roteamento
3. Query strings : a parte da cadeia de caracteres de consulta do URI.
Observação: valores de formulário, dados de rota e cadeias de consulta são todos armazenados
como pares nome-valor.
Como a associação de modelos solicitou uma chave chamada id e não há nada chamado id
nos valores de formulário, ela passou para os valores de rota procurando essa chave. Em nosso
exemplo, isso é uma correspondência. A associação ocorre e o valor é convertido no inteiro 2.
A mesma solicitação que usa Edit(string id) converterá na cadeia de caracteres "2".
Até agora, o exemplo usa tipos simples. No MVC, os tipos simples são qualquer tipo primitivo
do .NET ou um tipo com um conversor de tipo de cadeia de caracteres. Se o parâmetro do
método de ação for uma classe, como o tipo Movie , que contém tipos simples e complexos
como propriedades, a associação de modelos do MVC ainda o manipulará perfeitamente. Ele
usa a reflexão e recursão para percorrer as propriedades de tipos complexos procurando
correspondências. A associação de modelos procura o padrão
nome_do_parâmetro.nome_da_propriedade para associar valores a propriedades. Se ela não
encontrar os valores correspondentes desse formulário, ela tentará associar usando apenas o
nome da propriedade. Para esses tipos como tipos Collection , a associação de modelos
procura correspondências para parameter_name [index] ou apenas [index]. A associação de
modelos trata tipos Dictionary da mesma forma, solicitando parameter_name[key ] ou apenas
[key ], desde que as chaves sejam tipos simples. As chaves compatíveis correspondem o HTML
dos nomes de campo e os auxiliares de marca gerados para o mesmo tipo de modelo. Isso
permite a ida e vinda dos valores, de modo que os campos de formulário permaneçam
preenchidos com a entrada do usuário para sua conveniência, por exemplo, quando os dados
associados de uma criação ou edição não são aprovados na validação.
Para que a associação ocorra, a classe precisa ter um construtor padrão público e o membro a
ser associado precisa ser propriedades graváveis públicas. Quando a associação de modelos
ocorrer, só será criada uma instância da classe com o construtor padrão público e, em seguida,
as propriedades poderão ser definidas.
Quando um parâmetro é associado, a associação de modelos para de procurar valores com
esse nome e ela passa para associar o próximo parâmetro. Caso contrário, o comportamento
padrão da associação de modelos define parâmetros com seus valores padrão, dependendo de
seu tipo:
T[] : com a exceção de matrizes do tipo byte[] , a associação define parâmetros do tipo
T[] como Array.Empty<T>() . Matrizes do tipo byte[] são definidas como null .
Tipos de referência: a associação cria uma instância de uma classe com o construtor
padrão sem configurar propriedades. No entanto, a associação de modelos define
parâmetros string como null .
Tipos que permitem valor nulo: os tipos que permitem valor nulo são definidos como
null . No exemplo acima, a associação de modelos define id como null , pois ele é
do tipo int? .
Tipos de valor: os tipos de valor que não permitem valor nulo do tipo T são definidos
como default(T) . Por exemplo, a associação de modelos definirá um parâmetro
int id como 0. Considere o uso da validação de modelo ou de tipos que permitem
valor nulo, em vez de depender de valores padrão.
Se a associação falhar, o MVC não gerará um erro. Todas as ações que aceitam a entrada do
usuário devem verificar a propriedade ModelState.IsValid .
Observação: cada entrada na propriedade ModelState do controlador é uma ModelStateEntry
que contém uma propriedade Errors . Raramente é necessário consultar essa coleção por
conta própria. Use ModelState.IsValid em seu lugar.
Além disso, há alguns tipos de dados especiais que o MVC precisa considerar ao realizar a
associação de modelos:
IFormFile , IEnumerable<IFormFile> : um ou mais arquivos carregados que fazem parte
da solicitação HTTP.
CancellationToken : usado para cancelar a atividade em controladores assíncronos.
Esses tipos podem ser associados a parâmetros de ação ou a propriedades em um tipo de

classe.
Após a conclusão da associação de modelos, a Validação ocorrerá. A associação de modelos
padrão funciona bem para a maioria dos cenários de desenvolvimento. Também é extensível e,
portanto, se você tiver necessidades exclusivas, poderá personalizar o comportamento interno.
Personalizar o comportamento da associação de modelos

com atributos
O MVC contém vários atributos que podem ser usados para direcionar seu comportamento de
associação de modelos padrão para outra fonte. Por exemplo, você pode especificar se a
associação é obrigatória para uma propriedade ou se ela nunca deve ocorrer usando os
atributos [BindRequired] ou [BindNever] . Como alternativa, você pode substituir a fonte de
dados padrão e especificar a fonte de dados do associador de modelos. Veja abaixo uma lista
dos atributos de associação de modelos:
[BindRequired]: esse atributo adiciona um erro de estado do modelo se a associação
não pode ocorrer.
[BindNever] : instrui o associador de modelos a nunca associar a esse parâmetro.
[FromHeader], [FromQuery] , [FromRoute] , [FromForm] : use-os para especificar a origem
da associação exata que deseja aplicar.
[FromServices] : esse atributo usa a injeção de dependência para associar parâmetros de
serviços.
[FromBody] : use os formatadores configurados para associar dados do corpo da
solicitação. O formatador é selecionado de acordo com o tipo de conteúdo da
solicitação.
[ModelBinder] : usado para substituir o associador de modelos padrão, a origem da
associação e o nome.
Os atributos são ferramentas muito úteis quando você precisa substituir o comportamento
padrão da associação de modelos.
Personalizar a validação e a associação de modelos

globalmente
O comportamento do sistema de validação e associação de modelos é orientado pelo
ModelMetadata que descreve:
Como um modelo deve ser associado.
Como ocorre a validação no tipo e em suas propriedades.
Os aspectos do comportamento do sistema podem ser configurados globalmente adicionando
um provedor de detalhes a MvcOptions.ModelMetadataDetailsProviders. O MVC tem alguns
provedores de detalhes internos que permitem configurar o comportamento, como desabilitar
a validação ou a associação de modelos de determinados tipos.
Para desabilitar a associação de modelos em todos os modelos de um determinado tipo,
adicione um ExcludeBindingMetadataProvider em Startup.ConfigureServices . Por exemplo,
para desabilitar a associação de modelos em todos os modelos do tipo System.Version :
services.AddMvc().AddMvcOptions(options =>
options.ModelMetadataDetailsProviders.Add(
new ExcludeBindingMetadataProvider(typeof(System.Version))));
Para desabilitar a validação nas propriedades de um determinado tipo, adicione um

SuppressChildValidationMetadataProvider em Startup.ConfigureServices . Por exemplo, para
desabilitar a validação nas propriedades do tipo System.Guid :
services.AddMvc().AddMvcOptions(options =>
options.ModelMetadataDetailsProviders.Add(
new SuppressChildValidationMetadataProvider(typeof(System.Guid))));
Associar dados formatados do corpo da solicitação

Os dados de solicitação podem ser recebidos em uma variedade de formatos, incluindo JSON,
XML e muitos outros. Quando você usa o atributo [FromBody] para indicar que deseja associar
um parâmetro a dados no corpo da solicitação, o MVC usa um conjunto configurado de
formatadores para manipular os dados de solicitação de acordo com seu tipo de conteúdo. Por
padrão, o MVC inclui uma classe JsonInputFormatter para manipular dados JSON, mas você
pode adicionar outros formatadores para manipular XML e outros formatos personalizados.
NOTE
Pode haver, no máximo, um parâmetro por ação decorado com [FromBody] . O tempo de execução
do ASP.NET Core MVC delega a responsabilidade de ler o fluxo da solicitação ao formatador. Depois
que o fluxo da solicitação é lido para um parâmetro, geralmente, não é possível ler o fluxo da
solicitação novamente para associar outros parâmetros [FromBody] .
NOTE
O JsonInputFormatter é o formatador padrão e se baseia no Json.NET.
O ASP.NET Core seleciona formatadores de entrada com base no cabeçalho Content-Type e

no tipo do parâmetro, a menos que haja um atributo aplicado a ele com outra especificação. Se
deseja usar XML ou outro formato, configure-o no arquivo Startup.cs, mas talvez você precise
obter primeiro uma referência a Microsoft.AspNetCore.Mvc.Formatters.Xml usando o NuGet. O
código de inicialização deverá ter uma aparência semelhante a esta:
{
services.AddMvc()
.AddXmlSerializerFormatters();
}
O código no arquivo Startup.cs contém um método ConfigureServices com um argumento

services que você pode usar para criar serviços para o aplicativo ASP.NET Core. No exemplo,
estamos adicionando um formatador XML como um serviço que o MVC fornecerá para este
aplicativo. O argumento options passado para o método AddMvc permite que você adicione e
gerencie filtros, formatadores e outras opções do sistema no MVC após a inicialização do
aplicativo. Em seguida, aplique o atributo Consumes a classes do controlador ou métodos de
ação para trabalhar com o formato desejado.
Associação de modelos personalizada
Estenda a associação de modelos escrevendo seus próprios associadores de modelos
personalizados. Saiba mais sobre a associação de modelos personalizada.
Validação de modelo no ASP.NET Core
MVC
Por Rachel Appel
Introdução à validação do modelo

Antes que um aplicativo armazene dados em um banco de dados, ele deve validá-los. Os dados
precisam ser verificados quanto a possíveis ameaças de segurança, se estão formatados
corretamente por tipo e tamanho e precisam estar em conformidade com as regras. A validação
é necessária, embora possa ser redundante e monótona de ser implementada. No MVC, a
validação ocorre no cliente e no servidor.
Felizmente, o .NET abstraiu a validação para atributos de validação. Esses atributos contêm o
código de validação, reduzindo a quantidade de código que precisa ser escrita.
Exibir ou baixar amostra do GitHub.
Atributos de validação
Os atributos de validação são uma maneira de configurar a validação do modelo; portanto, é
conceitualmente semelhante à validação em campos de tabelas de banco de dados. Isso inclui
restrições, como atribuição de tipos de dados ou campos obrigatórios. Outros tipos de validação
incluem a aplicação de padrões a dados para impor regras de negócio, como um cartão de
crédito, número de telefone ou endereço de email. Os atributos de validação simplificam e
facilitam o uso da imposição desses requisitos.
Os atributos de validação são especificados no nível da propriedade:
[Required]
public string MyProperty { get; set; }
Veja abaixo um modelo Movie anotado de um aplicativo que armazena informações sobre
filmes e programas de TV. A maioria das propriedades é obrigatória e várias propriedades de
cadeia de caracteres têm requisitos de tamanho. Além disso, há uma restrição de intervalo
numérico em vigor para a propriedade Price de 0 a US$ 999,99, juntamente com um atributo
de validação personalizado.
public class Movie
{
[Required]
[StringLength(100)]
[ClassicMovie(1960)]
[Required]
[StringLength(1000)]
[Range(0, 999.99)]
[Required]
public Genre Genre { get; set; }
public bool Preorder { get; set; }

}
A simples leitura do modelo revela as regras sobre os dados para esse aplicativo, facilitando a
manutenção do código. Veja abaixo vários atributos de validação internos populares:
[CreditCard] : valida se a propriedade tem um formato de cartão de crédito.
[Compare] : valida se duas propriedades em um modelo são correspondentes.
[EmailAddress] : valida se a propriedade tem um formato de email.
[Phone] : valida se a propriedade tem um formato de telefone.
[Range] : valida se o valor da propriedade está dentro do intervalo especificado.
[RegularExpression] : valida se os dados correspondem à expressão regular especificada.
[Required] : torna uma propriedade obrigatória.
: valida se uma propriedade de cadeia de caracteres tem, no máximo, o
[StringLength]
tamanho máximo especificado.
[Url] : valida se a propriedade tem um formato de URL.
O MVC dá suporte a qualquer atributo derivado de ValidationAttribute para fins de validação.

Muitos atributos de validação úteis podem ser encontrados no namespace
System.ComponentModel.DataAnnotations.
Pode haver ocasiões em que você precisa de mais recursos do que os atributos internos
fornecem. Para essas ocasiões, é possível criar atributos de validação personalizados pela
derivação de ValidationAttribute ou alteração do modelo para implementar
IValidatableObject .
Observações sobre o uso do atributo Required

Os tipos de valor que não permitem valores nulos (como decimal , int , float e DateTime )
são inerentemente necessários e não precisam do atributo Required . O aplicativo não executa
nenhuma verificação de validação do lado do servidor para tipos que não permitem valor nulo
marcados como Required .
O model binding do MVC, que não está preocupado com a validação nem com atributos de
validação, rejeita o envio de um campo de formulário que contém um valor ausente ou espaço
em branco para um tipo que não permite valor nulo. Na ausência de um atributo BindRequired
na propriedade de destino, o model binding ignora dados ausentes para tipos que não
permitem valor nulo, nos quais o campo de formulário está ausente nos dados de formulário de
entrada.
O atributo BindRequired (veja também Associação de modelos no ASP.NET Core) é útil para
garantir que os dados do formulário sejam preenchidos. Quando aplicado a uma propriedade, o
sistema de model binding exige um valor para essa propriedade. Quando aplicado a um tipo, o
sistema de model binding exige valores para todas as propriedades desse tipo.
Quando você usa um tipo Nullable<T> (por exemplo, decimal? ou System.Nullable<decimal> )
e marca-o como Required , é realizada uma verificação de validação do lado do servidor, como
se a propriedade fosse um tipo que permite valor nulo padrão (para exemplo, uma string ).
A validação do lado do cliente exige um valor para um campo de formulário que corresponde a
uma propriedade de modelo que foi marcada como Required e para uma propriedade de tipo
que não permite valor nulo que ainda não foi marcada como Required . Required pode ser
usado para controlar a mensagem de erro de validação do lado do cliente.
Estado do modelo
O estado do modelo representa erros de validação nos valores de formulário HTML enviados.
O MVC continuará validando os campos até atingir o número máximo de erros (200 por
padrão). Configure esse número inserindo o seguinte código no método ConfigureServices no
arquivo Startup.cs:
services.AddMvc(options => options.MaxModelValidationErrors = 50);
Tratando erros do estado do modelo

A validação do modelo ocorre antes da invocação de cada ação do controlador e é
responsabilidade do método de ação inspecionar ModelState.IsValid e responder de forma
adequada. Em muitos casos, a resposta apropriada é retornar uma resposta de erro, de
preferência, fornecendo detalhes sobre o motivo pelo qual houve falha na validação do modelo.
Alguns aplicativos optarão por seguir uma convenção padrão para lidar com erros de validação
do modelo, caso em que um filtro pode ser um local adequado para implementar uma política
como essa. É necessário testar o comportamento das ações com estados de modelo válidos e
inválidos.
Validação manual
Após a conclusão da validação e de model binding, recomendamos repetir partes disso. Por
exemplo, um usuário pode ter inserido um texto em um campo que espera um inteiro ou talvez
você precise calcular um valor da propriedade de um modelo.
Talvez seja necessário executar a validação manualmente. Para fazer isso, chame o método
TryValidateModel , conforme mostrado aqui:
TryValidateModel(movie);
Validação personalizada
Os atributos de validação funcionam para a maior parte das necessidades de validação. No
entanto, algumas regras de validação são específicas ao negócio. As regras podem não ser
técnicas comuns de validação de dados, como garantir que um campo seja obrigatório ou que
ele esteja em conformidade com um intervalo de valores. Para esses cenários, os atributos de
validação personalizados são uma ótima solução. É fácil criar seus próprios atributos de
validação personalizados no MVC. Basta herdar do ValidationAttribute e substituir o método
IsValid . O método IsValid aceita dois parâmetros: o primeiro é um objeto chamado value e
o segundo é um objeto ValidationContext chamado validationContext. Value refere-se ao valor
real do campo que o validador personalizado está validando.
Na amostra a seguir, uma regra de negócios indica que os usuários não podem definir o gênero
como Clássico para um filme lançado após 1960. O atributo [ClassicMovie] verifica o gênero
primeiro e, se ele for um clássico, verificará a data de lançamento para ver se ela é posterior a
1960. Se ele tiver sido lançado após 1960, a validação falhará. O atributo aceita um parâmetro
de inteiro que representa o ano que pode ser usado para validar os dados. Capture o valor do
parâmetro no construtor do atributo, conforme mostrado aqui:
public class ClassicMovieAttribute : ValidationAttribute, IClientModelValidator

{
private int _year;
public ClassicMovieAttribute(int year)

{
_year = year;
}
protected override ValidationResult IsValid(object value, ValidationContext

validationContext)
{
Movie movie = (Movie)validationContext.ObjectInstance;
if (movie.Genre == Genre.Classic && movie.ReleaseDate.Year > _year)

{
return new ValidationResult(GetErrorMessage());
}
return ValidationResult.Success;
}
A variável movie acima representa um objeto Movie que contém os dados do envio do
formulário a serem validados. Nesse caso, o código de validação verifica a data e o gênero no
método IsValid da classe ClassicMovieAttribute de acordo com as regras. Após a validação
bem-sucedida, o IsValid retorna um código ValidationResult.Success . Quando a validação
falha, um ValidationResult com uma mensagem erro será retornado:
private string GetErrorMessage()

{
return $"Classic movies must have a release year earlier than {_year}.";
}
Quando um usuário modificar o campo Genre e enviar o formulário, o método IsValid da

ClassicMovieAttribute verificará se o filme é um clássico. Como qualquer atributo interno,
aplique o atributo ClassicMovieAttribute a uma propriedade como ReleaseDate para garantir
que a validação ocorra, conforme mostrado no exemplo de código anterior. Como o exemplo
funciona apenas com tipos Movie , a melhor opção é usar IValidatableObject , conforme
mostrado no parágrafo a seguir.
Como alternativa, esse mesmo código pode ser colocado no modelo implementando o método
Validate na interface IValidatableObject . Embora os atributos de validação personalizados
funcionem bem para validar propriedades individuais, a implementação de IValidatableObject
pode ser usada para implementar a validação no nível da classe como visto aqui.
public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)

{
if (Genre == Genre.Classic && ReleaseDate.Year > _classicYear)
{
yield return new ValidationResult(
$"Classic movies must have a release year earlier than {_classicYear}.",
new[] { "ReleaseDate" });
}
}
Validação do lado do cliente

A validação do lado do cliente é uma ótima conveniência para usuários. Ela economiza tempo
que de outra forma seria gasto aguardando uma viagem de ida e volta para o servidor. Em
termos de negócios, até mesmo algumas frações de segundos multiplicados por centenas de
vezes por dia chega a ser muito tempo, despesa e frustração. A validação imediata e simples
permite que os usuários trabalhem com mais eficiência e façam contribuições e produzam
entradas e saídas de melhor qualidade.
É necessário ter uma exibição com as referências de script JavaScript corretas em vigor para a
validação do lado do cliente para que ela funcione como visto aqui.
<script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.2.0.min.js"></script>
<script src="https://ajax.aspnetcdn.com/ajax/jquery.validate/1.16.0/jquery.validate.min.js">
</script>
<script
src="https://ajax.aspnetcdn.com/ajax/jquery.validation.unobtrusive/3.2.6/jquery.validate.uno
btrusive.min.js"></script>
O script do jQuery Unobtrusive Validation é uma biblioteca de front-end personalizada da

Microsoft que se baseia no popular plug-in jQuery Validate. Sem o jQuery Unobtrusive
Validation, você precisará codificar a mesma lógica de validação em dois locais: uma vez nos
atributos de validação do lado do servidor nas propriedades do modelo e, em seguida,
novamente nos scripts do lado do cliente (os exemplos para o método validate() do jQuery
Validate mostram a complexidade que isso pode gerar). Em vez disso, os Auxiliares de Marca e
os Auxiliares HTML do MVC podem usar os atributos de validação e os metadados de tipo das
propriedades do modelo para renderizar atributos de dados HTML 5 nos elementos de
formulário que precisam de validação. O MVC gera os atributos data- para atributos internos
e personalizados. O jQuery Unobtrusive Validation analisa os atributos data- e passa a lógica
para o jQuery Validate, "copiando" efetivamente a lógica de validação do lado do servidor para
o cliente. Exiba erros de validação no cliente usando os auxiliares de marca relevantes, conforme
mostrado aqui:
</div>
</div>
Os auxiliares de marca acima renderizam o HTML abaixo. Observe que os atributos data- na
saída HTML correspondem aos atributos de validação da propriedade ReleaseDate . O atributo
data-val-required abaixo contém uma mensagem de erro a ser exibida se o usuário não
preencher o campo de data de lançamento. O jQuery Unobtrusive Validation passa esse valor
para o método required() do jQuery Validate, que, por sua vez, exibe essa mensagem no
elemento <span> complementar.
<form action="/Movies/Create" method="post">

<h4>Movie</h4>
<div class="text-danger"></div>
<label class="col-md-2 control-label" for="ReleaseDate">ReleaseDate</label>
<input class="form-control" type="datetime"
data-val="true" data-val-required="The ReleaseDate field is required."
id="ReleaseDate" name="ReleaseDate" value="" />
<span class="text-danger field-validation-valid"
data-valmsg-for="ReleaseDate" data-valmsg-replace="true"></span>
</div>
</div>
</div>
</form>
A validação do lado do cliente impede o envio até que o formulário seja válido. O botão Enviar
executa o JavaScript que envia o formulário ou exibe mensagens de erro.
O MVC determina os valores de atributo de tipo com base no tipo de dados .NET de uma
propriedade, possivelmente, substituído com o uso de atributos [DataType] . O atributo
[DataType] base não faz nenhuma validação real do lado do servidor. Os navegadores
escolhem suas próprias mensagens de erro e exibem esses erros da maneira desejada. No
entanto, o pacote Unobtrusive Validation do jQuery pode substituir as mensagens e exibi-las de
forma consistente com as outras. Isso ocorre de forma mais evidente quando os usuários
aplicam subclasses [DataType] , como [EmailAddress] .
Adicionar validação a formulários dinâmicos
Como o jQuery Unobtrusive Validation passa parâmetros e a lógica de validação para o jQuery
Validate quando a página é carregada pela primeira vez, os formulários gerados dinamicamente
não exibem a validação de forma automática. Em vez disso, é necessário instruir o jQuery
Unobtrusive Validation a analisar o formulário dinâmico imediatamente depois de criá-lo. Por
exemplo, o código abaixo mostra como você pode configurar a validação do lado do cliente em
um formulário adicionado por meio do AJAX.
$.get({
url: "https://url/that/returns/a/form",
dataType: "html",
error: function(jqXHR, textStatus, errorThrown) {
alert(textStatus + ": Couldn't add form. " + errorThrown);
},
success: function(newFormHTML) {
var container = document.getElementById("form-container");
container.insertAdjacentHTML("beforeend", newFormHTML);
var forms = container.getElementsByTagName("form");
var newForm = forms[forms.length - 1];
$.validator.unobtrusive.parse(newForm);
}
})
O método $.validator.unobtrusive.parse() aceita um seletor do jQuery para um argumento

seu. Esse método instrui o jQuery Unobtrusive Validation a analisar os atributos data- de
formulários nesse seletor. Os valores desses atributos são então passados para o plug-in jQuery
Validate, de modo que o formulário exiba as regras de validação do lado do cliente desejadas.
Adicionar validação a controles dinâmicos
Também atualize as regras de validação em um formulário quando controles individuais, como
<input/> s e <select/> s, são gerados dinamicamente. Não é possível passar seletores para
esses elementos para o método parse() diretamente, porque o formulário adjacente já foi
analisado e não será atualizado. Em vez disso, primeiro remova os dados de validação existentes
e, em seguida, analise novamente todo o formulário, conforme mostrado abaixo:
$.get({
url: "https://url/that/returns/a/control",
dataType: "html",
error: function(jqXHR, textStatus, errorThrown) {
alert(textStatus + ": Couldn't add control. " + errorThrown);
},
success: function(newInputHTML) {
var form = document.getElementById("my-form");
form.insertAdjacentHTML("beforeend", newInputHTML);
$(form).removeData("validator") // Added by jQuery Validate
.removeData("unobtrusiveValidation"); // Added by jQuery Unobtrusive
Validation
$.validator.unobtrusive.parse(form);
}
})
IClientModelValidator
Você pode criar uma lógica do lado do cliente para o atributo personalizado, e o unobtrusive
validation, que cria um adaptador para a validação do jQuery, será executado no cliente
automaticamente como parte da validação. A primeira etapa é controlar quais atributos de
dados são adicionados, pela implementação da interface IClientModelValidator , conforme
mostrado aqui:
public void AddValidation(ClientModelValidationContext context)
{
if (context == null)
{
throw new ArgumentNullException(nameof(context));
}
MergeAttribute(context.Attributes, "data-val", "true");

MergeAttribute(context.Attributes, "data-val-classicmovie", GetErrorMessage());
var year = _year.ToString(CultureInfo.InvariantCulture);

MergeAttribute(context.Attributes, "data-val-classicmovie-year", year);
}
Atributos que implementam essa interface podem adicionar atributos HTML a campos gerados.
O exame da saída do elemento ReleaseDate revela um HTML semelhante ao exemplo anterior,
exceto que agora há um atributo data-val-classicmovie que foi definido no método
AddValidation de IClientModelValidator .
<input class="form-control" type="datetime"

data-val="true"
data-val-classicmovie="Classic movies must have a release year earlier than 1960."
data-val-classicmovie-year="1960"
data-val-required="The ReleaseDate field is required."
id="ReleaseDate" name="ReleaseDate" value="" />
A validação não invasiva usa os dados nos atributos data- para exibir mensagens de erro. No
entanto, o jQuery não reconhece regras ou mensagens até que você adicione-as ao objeto
validator do jQuery. Isso é mostrado no exemplo a seguir, que adiciona um método de
validação de cliente classicmovie personalizado ao objeto validator do jQuery. Para obter
uma explicação sobre o método unobtrusive.adapters.add , confira Unobtrusive Client
Validation no ASP.NET MVC.
$.validator.addMethod('classicmovie',
function (value, element, params) {
// Get element value. Classic genre has value '0'.
var genre = $(params[0]).val(),
year = params[1],
date = new Date(value);
if (genre && genre.length > 0 && genre[0] === '0') {
// Since this is a classic movie, invalid if release date is after given year.
return date.getFullYear() <= year;
}
return true;
});
$.validator.unobtrusive.adapters.add('classicmovie',
['year'],
function (options) {
var element = $(options.form).find('select#Genre')[0];
options.rules['classicmovie'] = [element, parseInt(options.params['year'])];
options.messages['classicmovie'] = options.message;
});
Com o código anterior, o método classicmovie executa a validação do lado do cliente na data
de lançamento do filme. A mensagem de erro é exibida se o método retornar false .
Validação remota
A validação remota é um ótimo recurso a ser usado quando você precisa validar os dados no
cliente em relação aos dados no servidor. Por exemplo, o aplicativo pode precisar verificar se um
email ou nome de usuário já está em uso e precisa consultar uma grande quantidade de dados
para fazer isso. O download de conjuntos de dados grandes para validar um ou alguns campos
consome muitos recursos. Isso também pode expor informações confidenciais. Uma alternativa
é fazer uma solicitação de ida e volta para validar um campo.
Implemente a validação remota em um processo de duas etapas. Primeiro, é necessário anotar
o modelo com o atributo [Remote] . O atributo [Remote] aceita várias sobrecargas que podem
ser usadas para direcionar o JavaScript do lado do cliente para o código apropriado a ser
chamado. O exemplo abaixo aponta para o método de ação VerifyEmail do controlador Users .
[Remote(action: "VerifyEmail", controller: "Users")]

A segunda etapa é colocar o código de validação no método de ação correspondente, conforme

definido no atributo [Remote] . De acordo com a documentação do método jQuery
Validateremoto, a resposta do servidor deve ser uma cadeia JSON que seja:
"true" para elementos válidos.
"false" , undefined ou null para elementos inválidos, usando a mensagem de erro
padrão.
Se a resposta do servidor for uma cadeia de caracteres (por exemplo,
"That name is already taken, try peter123 instead" ), a cadeia de caracteres é exibida como
uma mensagem de erro personalizada no lugar da cadeia de caracteres padrão.
A definição do método VerifyEmail segue essas regras, conforme mostrado abaixo. Ela retorna
uma mensagem de erro de validação se o email já está sendo usado ou true se o email está
livre e encapsula o resultado em um objeto JsonResult . O lado do cliente pode então usar o
valor retornado para continuar ou exibir o erro, se necessário.
[AcceptVerbs("Get", "Post")]
public IActionResult VerifyEmail(string email)
{
if (!_userRepository.VerifyEmail(email))
{
return Json($"Email {email} is already in use.");
}
return Json(true);
}
Agora, quando os usuários inserem um email, o JavaScript na exibição faz uma chamada
remota para ver se o email já está sendo usado e, em caso afirmativo, exibe a mensagem de
erro. Caso contrário, o usuário pode enviar o formulário como de costume.
A propriedade AdditionalFields do atributo [Remote] é útil para validação de combinações de
campos em relação aos dados no servidor. Por exemplo, se o modelo User acima tiver duas
propriedades adicionais chamadas FirstName e LastName , é recomendável verificar se não há
usuários que já têm esse par de nomes. Defina as novas propriedades, conforme mostrado no
seguinte código:
[Remote(action: "VerifyName", controller: "Users", AdditionalFields = nameof(LastName))]
public string FirstName { get; set; }
[Remote(action: "VerifyName", controller: "Users", AdditionalFields = nameof(FirstName))]
public string LastName { get; set; }
AdditionalFields poderia ter sido definido de forma explícita com as cadeias de caracteres
"FirstName" e "LastName" , mas o uso do operador nameof dessa forma, simplifica a
refatoração posterior. Em seguida, o método de ação para executar a validação precisa aceitar
dois argumentos, um para o valor de FirstName e outro para o valor de LastName .
[AcceptVerbs("Get", "Post")]
public IActionResult VerifyName(string firstName, string lastName)
{
if (!_userRepository.VerifyName(firstName, lastName))
{
return Json(data: $"A user named {firstName} {lastName} already exists.");
}
return Json(data: true);

}
Agora, quando os usuários inserem um nome e sobrenome, o JavaScript:

Faz uma chamada remota para ver se esse par de nomes já está sendo usado.
Se o par já está sendo usado, uma mensagem de erro é exibida.
Caso contrário, o usuário pode enviar o formulário.
Se você precisa validar dois ou mais campos adicionais com o atributo [Remote] , forneça-os
como uma lista delimitada por vírgula. Por exemplo, para adicionar uma propriedade
MiddleName ao modelo, defina o atributo [Remote] , conforme mostrado no seguinte código:
[Remote(action: "VerifyName", controller: "Users", AdditionalFields = nameof(FirstName) +

"," + nameof(LastName))]
public string MiddleName { get; set; }
AdditionalFields , como todos os argumentos de atributo, deve ser uma expressão de

constante. Portanto, você não deve usar uma cadeia de caracteres interpolada ou chamar
string.Join() para inicializar AdditionalFields . Para cada campo adicional adicionado ao
atributo [Remote] , é necessário adicionar outro argumento ao método de ação do controlador
correspondente.
Por Rick Anderson, Luke Latham, Taylor Mullen e Dan Vicarel

Razor é uma sintaxe de marcação para inserir código baseado em servidor em páginas da Web. A sintaxe
Razor é composta pela marcação Razor, por C# e por HTML. Arquivos que contêm Razor geralmente têm a
extensão de arquivo .cshtml.
Renderizando HTML
A linguagem padrão do Razor padrão é o HTML. Renderizar HTML da marcação Razor não é diferente de
renderizar HTML de um arquivo HTML. A marcação HTML em arquivos Razor .cshtml é renderizada pelo
servidor inalterado.
Sintaxe Razor
O Razor dá suporte a C# e usa o símbolo @ para fazer a transição de HTML para C#. O Razor avalia
expressões em C# e as renderiza na saída HTML.
Quando um símbolo @ é seguido por uma palavra-chave reservada do Razor, ele faz a transição para
marcação específica do Razor. Caso contrário, ele faz a transição para C# simples.
Para fazer o escape de um símbolo @ na marcação Razor, use um segundo símbolo @ :
<p>@@Username</p>
O código é renderizado em HTML com um único símbolo @ :
<p>@Username</p>
Conteúdo e atributos HTML que contêm endereços de email não tratam o símbolo @ como um caractere de
transição. Os endereços de email no exemplo a seguir não são alterados pela análise do Razor:
<a href="mailto:Support@contoso.com">Support@contoso.com</a>
Expressões Razor implícitas

Expressões Razor implícitas são iniciadas por @ seguido do código C#:
<p>@DateTime.Now</p>
<p>@DateTime.IsLeapYear(2016)</p>
Com exceção da palavra-chave C# await , expressões implícitas não devem conter espaços. Se a instrução C#
tiver uma terminação clara, espaços podem ser misturados:
<p>@await DoSomething("hello", "world")</p>

Expressões implícitas não podem conter elementos genéricos de C#, pois caracteres dentro de colchetes ( <> )
são interpretados como uma marca HTML. O código a seguir é inválido:
<p>@GenericMethod<int>()</p>
O código anterior gera um erro de compilador semelhante a um dos seguintes:

O elemento "int" não foi fechado. Todos os elementos devem ter fechamento automático ou ter uma marca
de fim correspondente.
Não é possível converter o grupo de métodos "GenericMethod" em um "object" de tipo não delegado. Você
pretendia invocar o método?
Chamadas de método genérico devem ser encapsuladas em uma expressão Razor explícita ou em um bloco de
código Razor.
Expressões Razor explícitas

Expressões Razor explícitas consistem de um símbolo @ com parênteses equilibradas. Para renderizar a hora
da última semana, a seguinte marcação Razor é usada:
<p>Last week this time: @(DateTime.Now - TimeSpan.FromDays(7))</p>
Qualquer conteúdo dentro dos parênteses @() é avaliado e renderizado para a saída.
Expressões implícitas, descritas na seção anterior, geralmente não podem conter espaços. No código a seguir,
uma semana não é subtraída da hora atual:
<p>Last week: @DateTime.Now - TimeSpan.FromDays(7)</p>
O código renderiza o HTML a seguir:
<p>Last week: 7/7/2016 4:39:52 PM - TimeSpan.FromDays(7)</p>
Expressões explícitas podem ser usadas para concatenar texto com um resultado de expressão:
@{
var joe = new Person("Joe", 33);
}
<p>Age@(joe.Age)</p>
Sem a expressão explícita, <p>Age@joe.Age</p> é tratado como um endereço de email e <p>Age@joe.Age</p> é

renderizado. Quando escrito como uma expressão explícita, <p>Age33</p> é renderizado.
Expressões explícitas podem ser usadas para renderizar a saída de métodos genéricos em arquivos .cshtml. A
marcação a seguir mostra como corrigir o erro mostrado anteriormente causado pelos colchetes de um C#
genérico. O código é escrito como uma expressão explícita:
<p>@(GenericMethod<int>())</p>
Codificação de expressão
Expressões em C# que são avaliadas como uma cadeia de caracteres estão codificadas em HTML. Expressões
em C# que são avaliadas como IHtmlContent são renderizadas diretamente por meio IHtmlContent.WriteTo .
Expressões em C# que não são avaliadas como IHtmlContent são convertidas em uma cadeia de caracteres
por ToString e codificadas antes que sejam renderizadas.
@("<span>Hello World</span>")
<span>Hello World</span>
O HTML é mostrado no navegador como:
A saída HtmlHelper.Raw não é codificada, mas renderizada como marcação HTML.
WARNING
Usar HtmlHelper.Raw em uma entrada do usuário que não está limpa é um risco de segurança. A entrada do usuário
pode conter JavaScript mal-intencionado ou outras formas de exploração. Limpar a entrada do usuário é difícil. Evite usar
HtmlHelper.Raw com a entrada do usuário.
@Html.Raw("<span>Hello World</span>")
Blocos de código Razor

Blocos de código Razor são iniciados por @ e delimitados por {} . Diferente das expressões, o código C#
dentro de blocos de código não é renderizado. Blocos de código e expressões em uma exibição compartilham
o mesmo escopo e são definidos em ordem:
@{
var quote = "The future depends on what you do today. - Mahatma Gandhi";
}
<p>@quote</p>
@{
quote = "Hate cannot drive out hate, only love can do that. - Martin Luther King, Jr.";
}
<p>@quote</p>

<p>The future depends on what you do today. - Mahatma Gandhi</p>
<p>Hate cannot drive out hate, only love can do that. - Martin Luther King, Jr.</p>
Transições implícitas
A linguagem padrão em um bloco de código é C#, mas a página Razor pode fazer a transição de volta para
HTML:
@{
var inCSharp = true;
<p>Now in HTML, was in C# @inCSharp</p>
}
Transição delimitada explícita

Para definir uma subseção de um bloco de código que deve renderizar HTML, circunde os caracteres para
renderização com as marca Razor <text>:
@for (var i = 0; i < people.Length; i++)

{
var person = people[i];
<text>Name: @person.Name</text>
}
Use essa abordagem para renderizar HTML que não está circundado por uma marca HTML. Sem uma marca
HTML ou Razor, ocorrerá um erro de tempo de execução do Razor.
A marca <text> é útil para controlar o espaço em branco ao renderizar conteúdo:
Somente o conteúdo entre a marca <text> é renderizado.
Não aparece nenhum espaço em branco antes ou depois da marca <text> na saída HTML.
Transição de linha explícita com @:
Para renderizar o restante de uma linha inteira como HTML dentro de um bloco de código, use a sintaxe @: :

{
@:Name: @person.Name
}
Sem o @: no código, será gerado um erro de tempo de execução do Razor.

Aviso: caracteres @ extras em um arquivo Razor podem causar erros do compilador em instruções mais
adiante no bloco. Esses erros do compilador podem ser difíceis de entender porque o erro real ocorre antes do
erro relatado. Esse erro é comum após combinar várias expressões implícitas/explícitas em um bloco de código
único.
Estruturas de controle
Estruturas de controle são uma extensão dos blocos de código. Todos os aspectos dos blocos de código
(transição para marcação, C# embutido) também se aplicam às seguintes estruturas:
Condicionais @if, else if, else e @switch
@if controla quando o código é executado:
@if (value % 2 == 0)
{
<p>The value was even.</p>
}
else e else if não exigem o símbolo @ :
@if (value % 2 == 0)
{
<p>The value was even.</p>
}
else if (value >= 1337)
{
<p>The value is large.</p>
}
else
{
<p>The value is odd and small.</p>
}
A marcação a seguir mostra como usar uma instrução switch:
@switch (value)
{
case 1:
<p>The value is 1!</p>
break;
case 1337:
<p>Your number is 1337!</p>
break;
default:
<p>Your number wasn't 1 or 1337.</p>
break;
}
Loop de @for, @foreach, @while e @do while

O HTML no modelo pode ser renderizado com instruções de controle em loop. Para renderizar uma lista de
pessoas:
@{
var people = new Person[]
{
new Person("Weston", 33),
new Person("Johnathon", 41),
...
};
}
Há suporte para as seguintes instruções em loop:

@for

{
<p>Name: @person.Name</p>
<p>Age: @person.Age</p>
}
@foreach
@foreach (var person in people)

{
}
@while
@{ var i = 0; }
@while (i < people.Length)
{
i++;
}
@do while
@{ var i = 0; }
@do
{
i++;
} while (i < people.Length);
@using composto
Em C#, uma instrução using é usada para garantir que um objeto seja descartado. No Razor, o mesmo
mecanismo é usado para criar Auxiliares HTML que têm conteúdo adicional. No código a seguir, os Auxiliares
HTML renderizam uma marca de formulário com a instrução @using :
@using (Html.BeginForm())
{
<div>
email:
<input type="email" id="Email" value="">
<button>Register</button>
</div>
}
Ações no nível de escopo podem ser executadas com Auxiliares de marca.

@try, catch, finally
O tratamento de exceções é semelhante ao de C#:
@try
{
throw new InvalidOperationException("You did something invalid.");
}
{
<p>The exception message: @ex.Message</p>
}
finally
{
<p>The finally statement.</p>
}
@lock
O Razor tem a capacidade de proteger seções críticas com instruções de bloqueio:
@lock (SomeLock)
{
// Do critical section work
}
Comentários
O Razor dá suporte a comentários em C# e HTML:
@{
/* C# comment */
// Another C# comment
}

Comentários em Razor são removidos pelo servidor antes que a página da Web seja renderizada. O Razor usa
@* *@ para delimitar comentários. O código a seguir é comentado, de modo que o servidor não renderiza
nenhuma marcação:
@*
@{
/* C# comment */
// Another C# comment
}
*@
Diretivas
Diretivas de Razor são representadas por expressões implícitas com palavras-chave reservadas após o símbolo
@ . Uma diretiva geralmente altera o modo como uma exibição é analisada ou habilita uma funcionalidade
diferente.
Compreender como o Razor gera código para uma exibição torna mais fácil entender como as diretivas
funcionam.
@{
var quote = "Getting old ain't for wimps! - Anonymous";
}
<div>Quote of the Day: @quote</div>
O código gera uma classe semelhante à seguinte:
public class _Views_Something_cshtml : RazorPage<dynamic>

{
public override async Task ExecuteAsync()
{
var output = "Getting old ain't for wimps! - Anonymous";
WriteLiteral("/r/n<div>Quote of the Day: ");

Write(output);
WriteLiteral("</div>");
}
}
Mais adiante neste artigo, a seção Inspecionar a classe do Razor C# gerada para uma exibição explica como
exibir essa classe gerada.
@using
A diretiva @using adiciona a diretiva using de C# à exibição gerada:
@using System.IO
@{
var dir = Directory.GetCurrentDirectory();
}
<p>@dir</p>
@model
A diretiva @model especifica o tipo do modelo passado para uma exibição:
@model TypeNameOfModel
Em um aplicativo do ASP.NET Core MCV criado com contas de usuário individuais, a exibição
Views/Account/Login.cshtml contém a declaração de modelo a seguir:
@model LoginViewModel
A classe gerada herda de RazorPage<dynamic> :
public class _Views_Account_Login_cshtml : RazorPage<LoginViewModel>
O Razor expõe uma propriedade Model para acessar o modelo passado para a exibição:
<div>The Login Email: @Model.Email</div>
A diretiva @model especifica o tipo dessa propriedade. A diretiva especifica o T em RazorPage<T> da classe
gerada da qual a exibição deriva. Se a diretiva @model não for especificada, a propriedade Model será do tipo
dynamic . O valor do modelo é passado do controlador para a exibição. Para obter mais informações, confira
Modelos fortemente tipados e a @palavra-chave do modelo.
@inherits
A diretiva @inherits fornece controle total da classe que a exibição herda:
@inherits TypeNameOfClassToInheritFrom
O código a seguir é um tipo de página Razor personalizado:
using Microsoft.AspNetCore.Mvc.Razor;
public abstract class CustomRazorPage<TModel> : RazorPage<TModel>

{
public string CustomText { get; } = "Gardyloo! - A Scottish warning yelled from a window before dumping
a slop bucket on the street below.";
}
O CustomText é exibido em uma exibição:
@inherits CustomRazorPage<TModel>
<div>Custom text: @CustomText</div>
<div>Custom text: Gardyloo! - A Scottish warning yelled from a window before dumping a slop bucket on the
street below.</div>
@model e @inherits podem ser usados na mesma exibição. @inherits pode estar em um arquivo
_ViewImports.cshtml que a exibição importa:
O código a seguir é um exemplo de exibição fortemente tipada:
<div>The Login Email: @Model.Email</div>

<div>Custom text: @CustomText</div>
Se "rick@contoso.com" for passado no modelo, a exibição gerará a seguinte marcação HTML:
<div>The Login Email: rick@contoso.com</div>

<div>Custom text: Gardyloo! - A Scottish warning yelled from a window before dumping a slop bucket on the
street below.</div>
@inject
A diretiva @inject permite que a página do Razor injete um serviço do contêiner de serviço em uma exibição.
Para obter mais informações, consulte Injeção de dependência em exibições.
@functions
A diretiva @functions permite que uma página Razor adicione um bloco de código C# a uma exibição:
@functions { // C# Code }
Por exemplo:
@functions {
public string GetHello()
{
return "Hello";
}
}
<div>From method: @GetHello()</div>
O código gera a seguinte marcação HTML:
<div>From method: Hello</div>
O código a seguir é a classe C# do Razor gerada:
using Microsoft.AspNetCore.Mvc.Razor;
public class _Views_Home_Test_cshtml : RazorPage<dynamic>

{
// Functions placed between here
public string GetHello()
{
return "Hello";
}
// And here.
#pragma warning disable 1998
public override async Task ExecuteAsync()
{
WriteLiteral("\r\n<div>From method: ");
Write(GetHello());
WriteLiteral("</div>\r\n");
}
#pragma warning restore 1998
@section
A diretiva @section é usada em conjunto com o layout para permitir que as exibições renderizem conteúdo
em partes diferentes da página HTML. Para obter mais informações, consulte Seções.
Auxiliares de Marca
Há três diretivas que relacionadas aos Auxiliares de marca.
DIRETIVA FUNÇÃO
@addTagHelper Disponibiliza os Auxiliares de marca para uma exibição.
@removeTagHelper Remove os Auxiliares de marca adicionados anteriormente

de uma exibição.
DIRETIVA FUNÇÃO
@tagHelperPrefix Especifica um prefixo de marca para habilitar o suporte do

Auxiliar de marca e tornar explícito o uso do Auxiliar de
marca.
Palavras-chave reservadas ao Razor

Palavras-chave do Razor
page (requer o ASP.NET Core 2.0 e posteriores)
namespace
funções
herda
modelo
section
helper (atualmente sem suporte do ASP.NET Core)
Palavras-chave do Razor têm o escape feito com @(Razor Keyword) (por exemplo, @(functions) ).
Palavras-chave do Razor em C#
case
do
default
for
foreach
if
else
bloqueio
switch
try
catch
finally
using
while
Palavras-chave do Razor em C# precisam ter o escape duplo com @(@C# Razor Keyword) (por exemplo,
@(@case) ). O primeiro @ faz o escape do analisador Razor. O segundo @ faz o escape do analisador C#.
Palavras-chave reservadas não usadas pelo Razor
classe
Inspecionar a classe do Razor C# gerada para uma exibição

Com o SDK do .NET Core 2.1 ou posterior, o SDK do Razor lida com a compilação de arquivos do Razor. Ao
compilar um projeto, o SDK do Razor gera um diretório
obj/<configuração_de_build>/<moniker_da_estrutura_de_destino>/Razor na raiz do projeto. A estrutura de
diretórios dentro do diretório do Razor espelha a estrutura de diretórios do projeto.
Considere a seguinte estrutura de diretórios em um projeto do Razor Pages ASP.NET Core 2.1 direcionado ao
.NET Core 2.1:
Areas/
Admin/
Pages/
Index.cshtml
Index.cshtml.cs
Pages/
Shared/
_Layout.cshtml
_ViewImports.cshtml
_ViewStart.cshtml
Index.cshtml
Index.cshtml.cs
A criação do projeto na configuração de Depuração produz o seguinte diretório obj:
obj/
Debug/
netcoreapp2.1/
Razor/
Areas/
Admin/
Pages/
Index.g.cshtml.cs
Pages/
Shared/
_Layout.g.cshtml.cs
_ViewImports.g.cshtml.cs
_ViewStart.g.cshtml.cs
Index.g.cshtml.cs
Para exibir a classe gerada para Pages/Index.cshtml, abra
obj/Debug/netcoreapp2.1/Razor/Pages/Index.g.cshtml.cs.
Adicione a seguinte classe ao projeto do ASP.NET Core MVC:
using Microsoft.AspNetCore.Mvc.Razor.Extensions;
using Microsoft.AspNetCore.Razor.Language;
public class CustomTemplateEngine : MvcRazorTemplateEngine

{
public CustomTemplateEngine(RazorEngine engine, RazorProject project)
: base(engine, project)
{
}
public override RazorCSharpDocument GenerateCode(RazorCodeDocument codeDocument)

{
var csharpDocument = base.GenerateCode(codeDocument);
var generatedCode = csharpDocument.GeneratedCode;
// Look at generatedCode
return csharpDocument;
}
}
Em Startup.ConfigureServices , substitua o RazorTemplateEngine adicionado pelo MVC pela classe

CustomTemplateEngine :

{
services.AddMvc();
services.AddSingleton<RazorTemplateEngine, CustomTemplateEngine>();
}
Defina o ponto de interrupção CustomTemplateEngine na instrução return csharpDocument; . Quando a execução

do programa for interrompida no ponto de interrupção, veja o valor de generatedCode .
Pesquisas de exibição e diferenciação de maiúsculas e minúsculas

O mecanismo de exibição do Razor executa pesquisas que diferenciam maiúsculas de minúsculas para as
exibições. No entanto, a pesquisa real é determinada pelo sistema de arquivos subjacente:
Origem baseada em arquivo:
Em sistemas operacionais com sistemas de arquivos que não diferenciam maiúsculas e minúsculas
(por exemplo, Windows), pesquisas no provedor de arquivos físico não diferenciam maiúsculas de
minúsculas. Por exemplo, return View("Test") resulta em correspondências para
/Views/Home/Test.cshtml, /Views/home/test.cshtml e qualquer outra variação de maiúsculas e
minúsculas.
Em sistemas de arquivos que diferenciam maiúsculas de minúsculas (por exemplo, Linux, OSX e com
EmbeddedFileProvider ), as pesquisas diferenciam maiúsculas de minúsculas. Por exemplo,
return View("Test") corresponde especificamente a /Views/Home/Test.cshtml.
Exibições pré-compiladas: com o ASP.NET Core 2.0 e posteriores, pesquisar em exibições pré-compiladas
não diferencia maiúsculas de minúsculas em nenhum sistema operacional. O comportamento é idêntico ao
comportamento do provedor de arquivos físico no Windows. Se duas exibições pré-compiladas diferirem
apenas quanto ao padrão de maiúsculas e minúsculas, o resultado da pesquisa não será determinístico.
Os desenvolvedores são incentivados a fazer a correspondência entre as maiúsculas e minúsculas dos nomes
dos arquivos e de diretórios com o uso de maiúsculas e minúsculas em:
* <span data-ttu-id="8f5c9-325">Nomes de área, controlador e ação.</span><span class="sxs-lookup"><span

data-stu-id="8f5c9-325">Area, controller, and action names.</span></span>
* <span data-ttu-id="8f5c9-326">Páginas do Razor.</span><span class="sxs-lookup"><span data-stu-id="8f5c9-
326">Razor Pages.</span></span>
Fazer essa correspondência garante que as implantações encontrem suas exibições, independentemente do
sistema de arquivos subjacente.
Por Rick Anderson

Os componentes de exibição são semelhantes às exibições parciais, mas são muito mais eficientes. Os
componentes de exibição não usam o model binding e dependem apenas dos dados fornecidos durante uma
chamada a eles. Este artigo foi escrito com o ASP.NET Core MVC, mas os componentes de exibição também
funcionam com Páginas do Razor.
Um componente de exibição:
Renderiza uma parte em vez de uma resposta inteira.
Inclui os mesmos benefícios de capacidade de teste e separação de interesses e encontrados entre um
controlador e uma exibição.
Pode ter parâmetros e uma lógica de negócios.
É geralmente invocado em uma página de layout.
Os componentes de exibição destinam-se a qualquer momento em que há uma lógica de renderização
reutilizável muito complexa para uma exibição parcial, como:
Menus de navegação dinâmica
Nuvem de marcas (na qual ela consulta o banco de dados)
Painel de logon
Carrinho de compras
Artigos publicados recentemente
Conteúdo da barra lateral em um blog típico
Um painel de logon que é renderizado em cada página e mostra os links para logoff ou logon, dependendo
do estado de logon do usuário
Um componente de exibição consiste em duas partes: a classe (normalmente derivada de ViewComponent) e
o resultado que ele retorna (normalmente, uma exibição). Assim como os controladores, um componente de
exibição pode ser um POCO, mas a maioria dos desenvolvedores desejará aproveitar os métodos e as
propriedades disponíveis com a derivação de ViewComponent .
Criando um componente de exibição

Esta seção contém os requisitos de alto nível para a criação de um componente de exibição. Mais adiante
neste artigo, examinaremos cada etapa em detalhes e criaremos um componente de exibição.
A classe de componente de exibição
Uma classe de componente de exibição pode ser criada por um dos seguintes:
Derivação de ViewComponent
Decoração de uma classe com o atributo [ViewComponent] ou derivação de uma classe com o atributo
[ViewComponent]
Criação de uma classe em que o nome termina com o sufixo ViewComponent
Assim como os controladores, os componentes de exibição precisam ser classes públicas, não aninhadas e não
abstratas. O nome do componente de exibição é o nome da classe com o sufixo "ViewComponent" removido.
Também pode ser especificado de forma explícita com a propriedade ViewComponentAttribute.Name .
Uma classe de componente de exibição:
Dá suporte total à injeção de dependência do construtor
Não participa do ciclo de vida do controlador, o que significa que não é possível usar filtros em um
componente de exibição
Métodos de componente de exibição
Um componente de exibição define sua lógica em um método InvokeAsync que retorna um
IViewComponentResult . Os parâmetros são recebidos diretamente da invocação do componente de exibição,
não do model binding. Um componente de exibição nunca manipula uma solicitação diretamente.
Normalmente, um componente de exibição inicializa um modelo e passa-o para uma exibição chamando o
método View . Em resumo, os métodos de componente de exibição:
Definem um método InvokeAsync que retorna um IViewComponentResult
Normalmente, inicializam um modelo e passam-o para uma exibição chamando o método ViewComponent
View
Os parâmetros são recebidos do método de chamada, não do HTTP e não há nenhum model binding
Não podem ser acessados diretamente como um ponto de extremidade HTTP e são invocados no código
(normalmente em uma exibição). Um componente de exibição nunca manipula uma solicitação
São sobrecarregados na assinatura, em vez de nos detalhes da solicitação HTTP atual
Caminho de pesquisa de exibição
O tempo de execução pesquisa a exibição nos seguintes caminhos:
/Pages/Components/{Nome do Componente da Exibição}/{Nome da Exibição}
/Views/{Nome do Controlador}/Components/{Nome do Componente da Exibição}/{Nome da Exibição}
/Views/Shared/Components/{Nome do Componente da Exibição}/{Nome da Exibição}
O nome de exibição padrão de um componente de exibição é Default, o que significa que o arquivo de
exibição geralmente será nomeado Default.cshtml. Especifique outro nome de exibição ao criar o resultado do
componente de exibição ou ao chamar o método View .
Recomendamos que você nomeie o arquivo de exibição Default.cshtml e use o caminho
Views/Shared/Components/{Nome do Componente da Exibição }/{Nome da Exibição }. O componente de
exibição PriorityList usado nesta amostra usa Views/Shared/Components/PriorityList/Default.cshtml como
a exibição do componente de exibição.
Invocando um componente de exibição

Para usar o componente de exibição, chame o seguinte em uma exibição:
@await Component.InvokeAsync("Name of view component", {Anonymous Type Containing Parameters})
Os parâmetros serão passados para o método InvokeAsync . O componente de exibição PriorityList

desenvolvido no artigo é invocado por meio do arquivo de exibição Views/Todo/Index.cshtml. A seguir, o
método InvokeAsync é chamado com dois parâmetros:
@await Component.InvokeAsync("PriorityList", new { maxPriority = 4, isDone = true })
Invocando um componente de exibição como um Auxiliar de Marca

Para o ASP.NET Core 1.1 e superior, invoque um componente de exibição como um Auxiliar de Marca:
<vc:priority-list max-priority="2" is-done="false">

</vc:priority-list>
Os parâmetros de classe e de método na formatação Pascal Case para Auxiliares de Marca são convertidos
em seu kebab case em minúsculas. Para invocar um componente de exibição, o Auxiliar de Marca usa o
elemento <vc></vc> . O componente de exibição é especificado da seguinte maneira:
<vc:[view-component-name]
parameter1="parameter1 value"
parameter2="parameter2 value">
</vc:[view-component-name]>
Para usar um componente de exibição como um Auxiliar de Marca, registre o assembly que contém o
componente de exibição usando a diretiva @addTagHelper . Se seu componente de exibição estiver em um
assembly chamado MyWebApp , adicione a seguinte diretiva ao arquivo _ViewImports.cshtml:
@addTagHelper *, MyWebApp
É possível registrar um componente de exibição como um Auxiliar de Marca a qualquer arquivo que
referencie o componente de exibição. Consulte Gerenciando o escopo do Auxiliar de Marca para obter mais
informações sobre como registrar Auxiliares de Marca.
O método InvokeAsync usado neste tutorial:
Na marcação do Auxiliar de Marca:

</vc:priority-list>
Na amostra acima, o componente de exibição PriorityList torna-se priority-list . Os parâmetros para o

componente de exibição são passados como atributos em kebab case em minúsculas.
Invocando um componente de exibição diretamente em um controlador
Os componentes de exibição normalmente são invocados em uma exibição, mas você pode invocá-los
diretamente em um método do controlador. Embora os componentes de exibição não definam pontos de
extremidade como controladores, você pode implementar com facilidade uma ação do controlador que
retorna o conteúdo de um ViewComponentResult .
Neste exemplo, o componente de exibição é chamado diretamente no controlador:
public IActionResult IndexVC()
{
return ViewComponent("PriorityList", new { maxPriority = 3, isDone = false });
}
Passo a passo: criando um componente de exibição simples

Baixe, compile e teste o código inicial. É um projeto simples com um controlador Todo que exibe uma lista de
itens Todo.
Adicionar uma classe ViewComponent

Crie uma pasta ViewComponents e adicione a seguinte classe PriorityListViewComponent :
using System.Linq;
using ViewComponentSample.Models;
namespace ViewComponentSample.ViewComponents
{
public class PriorityListViewComponent : ViewComponent
{
private readonly ToDoContext db;
public PriorityListViewComponent(ToDoContext context)

{
db = context;
}
public async Task<IViewComponentResult> InvokeAsync(

int maxPriority, bool isDone)
{
var items = await GetItemsAsync(maxPriority, isDone);
return View(items);
}
private Task<List<TodoItem>> GetItemsAsync(int maxPriority, bool isDone)
{
return db.ToDo.Where(x => x.IsDone == isDone &&
x.Priority <= maxPriority).ToListAsync();
}
}
}
Observações sobre o código:

As classes de componente de exibição podem ser contidas em qualquer pasta do projeto.
Como o nome da classe PriorityListViewComponent termina com o sufixo ViewComponent, o
tempo de execução usará a cadeia de caracteres "PriorityList" ao referenciar o componente de classe
em uma exibição. Explicarei isso mais detalhadamente mais adiante.
O atributo [ViewComponent] pode alterar o nome usado para referenciar um componente de exibição.
Por exemplo, poderíamos nomear a classe XYZ e aplicar o atributo ViewComponent :
[ViewComponent(Name = "PriorityList")]
public class XYZ : ViewComponent
O atributo [ViewComponent] acima instrui o seletor de componente de exibição a usar o nome

PriorityList ao procurar as exibições associadas ao componente e a usar a cadeia de caracteres
"PriorityList" ao referenciar o componente de classe em uma exibição. Explicarei isso mais
detalhadamente mais adiante.
O componente usa a injeção de dependência para disponibilizar o contexto de dados.
InvokeAsync expõe um método que pode ser chamado em uma exibição e pode usar um número
arbitrário de argumentos.
O método InvokeAsync retorna o conjunto de itens ToDo que atendem aos parâmetros isDone e
maxPriority .
Criar a exibição do Razor do componente de exibição
Crie a pasta Views/Shared/Components. Essa pasta deve nomeada Components.
Crie a pasta Views/Shared/Components/PriorityList. Esse nome de pasta deve corresponder ao nome
da classe do componente de exibição ou ao nome da classe menos o sufixo (se seguimos a convenção e
usamos o sufixo ViewComponent no nome da classe). Se você usou o atributo ViewComponent , o nome
da classe precisa corresponder à designação de atributo.
Crie uma exibição do Razor Views/Shared/Components/PriorityList/Default.cshtml: [!code-cshtml]
A exibição do Razor usa uma lista de TodoItem e exibe-os. Se o método InvokeAsync do componente
de exibição não passar o nome da exibição (como em nossa amostra), Default será usado como o nome
da exibição, por convenção. Mais adiante no tutorial, mostrarei como passar o nome da exibição. Para
substituir o estilo padrão de um controlador específico, adicione uma exibição à pasta de exibição
específica ao controlador (por exemplo, Views/Todo/Components/PriorityList/Default.cshtml).
Se o componente de exibição é específico ao controlador, adicione-o à pasta específica ao controlador
(Views/Todo/Components/PriorityList/Default.cshtml).
Adicione um div que contém uma chamada ao componente da lista de prioridades à parte inferior do
arquivo Views/Todo/index.cshtml:
</table>
<div>
@await Component.InvokeAsync("PriorityList", new { maxPriority = 2, isDone = false })
</div>
A marcação @await Component.InvokeAsync mostra a sintaxe para chamar componentes de exibição. O

primeiro argumento é o nome do componente que queremos invocar ou chamar. Os parâmetros seguintes
são passados para o componente. InvokeAsync pode usar um número arbitrário de argumentos.
Teste o aplicativo. A seguinte imagem mostra a lista ToDo e os itens de prioridade:
Também chame o componente de exibição diretamente no controlador:

public IActionResult IndexVC()
{
return ViewComponent("PriorityList", new { maxPriority = 3, isDone = false });
}
Especificando um nome de exibição

Um componente de exibição complexo pode precisar especificar uma exibição não padrão em algumas
condições. O código a seguir mostra como especificar a exibição "PVC" no método InvokeAsync . Atualize o
método InvokeAsync na classe PriorityListViewComponent .

{
string MyView = "Default";
// If asking for all completed tasks, render with the "PVC" view.
if (maxPriority > 3 && isDone == true)
{
MyView = "PVC";
}
return View(MyView, items);
}
Copie o arquivo Views/Shared/Components/PriorityList/Default.cshtml para uma exibição nomeada

Views/Shared/Components/PriorityList/PVC.cshtml. Adicione um cabeçalho para indicar que a exibição PVC
está sendo usada.
@model IEnumerable<ViewComponentSample.Models.TodoItem>
<h2> PVC Named Priority Component View</h2>

<h4>@ViewBag.PriorityMessage</h4>
<ul>
@foreach (var todo in Model)
{
<li>@todo.Name</li>
}
</ul>
Atualize Views/TodoList/Index.cshtml:

Execute o aplicativo e verifique a exibição PVC.
Se a exibição PVC não é renderizada, verifique se você está chamando o componente de exibição com uma
prioridade igual a 4 ou superior.
Examinar o caminho de exibição
Altere o parâmetro de prioridade para três ou menos para que a exibição de prioridade não seja
retornada.
Renomeie temporariamente o Views/Todo/Components/PriorityList/Default.cshtml como
1Default.cshtml.
Teste o aplicativo. Você obterá o seguinte erro:

InvalidOperationException: The view 'Components/PriorityList/Default' wasn't found. The following
locations were searched:
/Views/ToDo/Components/PriorityList/Default.cshtml
/Views/Shared/Components/PriorityList/Default.cshtml
EnsureSuccessful
Copie Views/Todo/Components/PriorityList/1Default.cshtml para

Views/Shared/Components/PriorityList/Default.cshtml.
Adicione uma marcação ao componente de exibição Todo Shared para indicar que a exibição foi obtida
da pasta Shared.
Teste o componente de exibição Shared.
Evitando cadeias de caracteres mágicas
Se deseja obter segurança em tempo de compilação, substitua o nome do componente de exibição embutido
em código pelo nome da classe. Crie o componente de exibição sem o sufixo "ViewComponent":
using System.Linq;
using ViewComponentSample.Models;
namespace ViewComponentSample.ViewComponents
{
public class PriorityList : ViewComponent
{
private readonly ToDoContext db;
public PriorityList(ToDoContext context)

{
db = context;
}

{
return View(items);
}
private Task<List<TodoItem>> GetItemsAsync(int maxPriority, bool isDone)
{
return db.ToDo.Where(x => x.IsDone == isDone &&
x.Priority <= maxPriority).ToListAsync();
}
}
}
Adicione uma instrução using ao arquivo de exibição do Razor e use o operador nameof :
@using ViewComponentSample.Models
@using ViewComponentSample.ViewComponents
@model IEnumerable<TodoItem>
<h2>ToDo nameof</h2>

<div>
@await Component.InvokeAsync(nameof(PriorityList), new { maxPriority = 4, isDone = true })

</div>
Executar o trabalho síncrono

A estrutura manipulará a invocação de um método Invoke síncrono se não for necessário realizar o trabalho
assíncrono. O método a seguir cria um componente de exibição Invoke síncrono:
public class PriorityList : ViewComponent

{
public IViewComponentResult Invoke(int maxPriority, bool isDone)
{
var items = new List<string> { $"maxPriority: {maxPriority}", $"isDone: {isDone}" };
return View(items);
}
}
O arquivo do Razor do componente de exibição lista as cadeias de caracteres passadas para o método Invoke
(Views/Home/Components/PriorityList/Default.cshtml):
@model List<string>
<h3>Priority Items</h3>
<ul>
{
<li>@item</li>
}
</ul>
O componente de exibição é invocado em um arquivo do Razor (por exemplo, Views/Home/Index.cshtml)

usando uma das seguintes abordagens:
IViewComponentHelper
Auxiliar de Marca
Para usar a abordagem IViewComponentHelper, chame Component.InvokeAsync :
O componente de exibição é invocado em um arquivo do Razor (por exemplo, Views/Home/Index.cshtml)
com IViewComponentHelper.
Chame Component.InvokeAsync :
@await Component.InvokeAsync(nameof(PriorityList), new { maxPriority = 4, isDone = true })
Para usar o Auxiliar de Marca, registre o assembly que contém o Componente de exibição que usa a diretiva
@addTagHelper (o componente de exibição está em um assembly chamado MyWebApp ):
@addTagHelper *, MyWebApp
Use o componente de exibição Auxiliar de Marca no arquivo de marcação do Razor:

</vc:priority-list>
A assinatura do método de PriorityList.Invoke é síncrona, mas o Razor localiza e chama o método com
Component.InvokeAsync no arquivo de marcação.
Recursos adicionais
Injeção de dependência em exibições
Compilação de arquivo do Razor no ASP.NET Core
Por Rick Anderson

Um arquivo do Razor é compilado em tempo de execução, quando o modo de exibição do MVC associado é
chamado. Não há suporte para a publicação de arquivos do Razor de tempo de build. Como opção, os arquivos
do Razor podem ser compilados durante a publicação e implantados com o aplicativo — usando a ferramenta de
pré-compilação.
Um arquivo do Razor é compilado em tempo de execução, quando o modo de exibição do MVC ou da Página do
Razor associada é chamado. Não há suporte para a publicação de arquivos do Razor de tempo de build. Como
opção, os arquivos do Razor podem ser compilados durante a publicação e implantados com o aplicativo —
usando a ferramenta de pré-compilação.
Um arquivo do Razor é compilado em tempo de execução, quando o modo de exibição do MVC ou da Página do
Razor associada é chamado. Os arquivos do Razor são compilados em tempo de build e de publicação usando o
SDK do Razor.
Considerações sobre a pré-compilação

Estes são os efeitos colaterais da pré-compilação de arquivos do Razor:
Pacote publicado menor
Tempo de inicialização mais rápido
Não é possível editar arquivos do Razor—o conteúdo associado está ausente do pacote publicado.
Implantar arquivos pré-compilados

A compilação em tempo de build e de publicação de arquivos do Razor está habilitada por padrão pelo SDK do
Razor. Há suporte para edição de arquivos do Razor depois que eles são atualizados em tempo de build. Por
padrão, nenhum arquivo .cshtml é implantado com o aplicativo; somente a Views.dll compilada.
IMPORTANT
A ferramenta de pré-compilação será removida no ASP.NET Core 3.0. É recomendado migrar para o SDK do Razor.
O SDK do Razor é eficaz somente quando não há propriedades específicas de pré-compilação definidas no arquivo de
projeto. Por exemplo, definir a propriedade MvcRazorCompileOnPublish do arquivo .csproj como true desabilita o SDK
do Razor.
Se o projeto for direcionado ao .NET Framework, instale o pacote NuGet

Microsoft.AspNetCore.Mvc.Razor.ViewCompilation:
<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation"
Version="2.0.4"
PrivateAssets="All" />
Se o projeto for direcionado ao .NET Core, nenhuma alteração será necessária.

Os modelos de projeto do ASP.NET Core 2.x definem implicitamente a propriedade MvcRazorCompileOnPublish
como true por padrão. Consequentemente, esse elemento pode ser removido com segurança do arquivo .csproj.
IMPORTANT
A ferramenta de pré-compilação será removida no ASP.NET Core 3.0. É recomendado migrar para o SDK do Razor.
A pré-compilação do arquivo do Razor não está disponível durante a execução de uma SCD (implantação autossuficiente) no
ASP.NET Core 2.0.
Defina a propriedade MvcRazorCompileOnPublish como true e instale o pacote NuGet

Microsoft.AspNetCore.Mvc.Razor.ViewCompilation. A seguinte amostra .csproj realça essas configurações:
<PropertyGroup>
<MvcRazorCompileOnPublish>true</MvcRazorCompileOnPublish>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore" Version="1.1.0" />
<PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="1.1.0" />
<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="1.1.0-*" />
</ItemGroup>
</Project>
Prepare o aplicativo para uma implantação dependente de estrutura com o comando de publicação da CLI do
.NET Core. Por exemplo, execute o seguinte comando na raiz do projeto:
dotnet publish -c Release
Um arquivo <nome_do_projeto>.PrecompiledViews.dll, que contém os arquivos do Razor compilados, é

produzido quando a pré-compilação é bem-sucedida. Por exemplo, a captura de tela abaixo mostra o conteúdo de
Index.cshtml dentro de WebApplication1.PrecompiledViews.dll:
Recursos adicionais
SDK do Razor do ASP.NET Core
Trabalhar com o modelo de aplicativo no ASP.NET
Core
Por Steve Smith

O ASP.NET Core MVC define um modelo de aplicativo que representa os componentes de um aplicativo MVC.
Leia e manipule esse modelo para modificar o comportamento de elementos MVC. Por padrão, o MVC segue
algumas convenções para determinar quais classes são consideradas controladores, quais métodos nessas classes
são ações e qual o comportamento de parâmetros e do roteamento. Personalize esse comportamento de acordo
com as necessidades do aplicativo criando suas próprias convenções e aplicando-as globalmente ou como
atributos.
Modelos e provedores
O modelo de aplicativo ASP.NET Core MVC inclui interfaces abstratas e classes de implementação concreta que
descrevem um aplicativo MVC. Esse modelo é o resultado da descoberta do MVC de controladores, ações,
parâmetros de ação, rotas e filtros do aplicativo de acordo com as convenções padrão. Trabalhando com o modelo
de aplicativo, você pode modificar o aplicativo para seguir convenções diferentes do comportamento padrão do
MVC. Os parâmetros, os nomes, as rotas e os filtros são todos usados como dados de configuração para ações e
controladores.
O Modelo de Aplicativo ASP.NET Core MVC tem a seguinte estrutura:
ApplicationModel
Controladores (ControllerModel)
Ações (ActionModel)
Parâmetros (ParameterModel)
Cada nível do modelo tem acesso a uma coleção Properties comum e níveis inferiores podem acessar e substituir
valores de propriedade definidos por níveis mais altos na hierarquia. As propriedades são persistidas nas
ActionDescriptor.Properties quando as ações são criadas. Em seguida, quando uma solicitação está sendo
manipulada, as propriedades que uma convenção adicionou ou modificou podem ser acessadas por meio de
ActionContext.ActionDescriptor.Properties . O uso de propriedades é uma ótima maneira de configurar filtros,
associadores de modelos, etc., por ação.
NOTE
A coleção ActionDescriptor.Properties não é thread-safe (para gravações) após a conclusão da inicialização do aplicativo.
Convenções são a melhor maneira de adicionar dados com segurança a essa coleção.
IApplicationModelProvider
O ASP.NET Core MVC carrega o modelo de aplicativo usando um padrão de provedor, definido pela interface
IApplicationModelProvider. Esta seção aborda alguns dos detalhes de implementação interna de como funciona
esse provedor. Este é um tópico avançado – a maioria dos aplicativos que utiliza o modelo de aplicativo deve fazer
isso trabalhando com convenções.
Implementações da interface IApplicationModelProvider "encapsulam" umas às outras, com cada implementação
chamando OnProvidersExecuting em ordem crescente com base em sua propriedade Order . O método
OnProvidersExecuted é então chamado em ordem inversa. A estrutura define vários provedores:
Primeiro ( Order=-1000 ):
DefaultApplicationModelProvider
Em seguida ( Order=-990 ):
AuthorizationApplicationModelProvider
CorsApplicationModelProvider
NOTE
A ordem na qual dois provedores com o mesmo valor para Order são chamados não é definida e, portanto, não se deve
depender dela.
NOTE
IApplicationModelProvider é um conceito avançado a ser estendido pelos autores da estrutura. Em geral, aplicativos
devem usar convenções e estruturas devem usar provedores. A principal diferença é que os provedores sempre são
executados antes das convenções.
O DefaultApplicationModelProvider estabelece muitos dos comportamentos padrão usados pelo ASP.NET Core
MVC. Suas responsabilidades incluem:
Adicionar filtros globais ao contexto
Adicionar controladores ao contexto
Adicionar métodos de controlador públicos como ações
Adicionar parâmetros de método de ação ao contexto
Aplicar a rota e outros atributos
Alguns comportamentos internos são implementados pelo DefaultApplicationModelProvider . Esse provedor é
responsável pela construção do ControllerModel , que, por sua vez, referencia instâncias ActionModel ,
PropertyModel e ParameterModel . A classe DefaultApplicationModelProvider é um detalhe de implementação de
estrutura interna que pode e será alterado no futuro.
O AuthorizationApplicationModelProvider é responsável por aplicar o comportamento associado aos atributos
AuthorizeFilter e AllowAnonymousFilter . Saiba mais sobre esses atributos.
O CorsApplicationModelProvider implementa o comportamento associado ao IEnableCorsAttribute , ao
IDisableCorsAttribute e ao DisableCorsAuthorizationFilter . Saiba mais sobre o CORS.
Convenções
O modelo de aplicativo define abstrações de convenção que fornecem uma maneira simples de personalizar o
comportamento dos modelos em vez de substituir o modelo ou o provedor inteiro. Essas abstrações são a maneira
recomendada para modificar o comportamento do aplicativo. As convenções fornecem uma maneira de escrever
código que aplicará personalizações de forma dinâmica. Enquanto os filtros fornecem um meio de modificar o
comportamento da estrutura, as personalizações permitem que você controle como todo o aplicativo está
conectado.
As seguintes convenções estão disponíveis:
IApplicationModelConvention
IControllerModelConvention
IActionModelConvention
IParameterModelConvention
As convenções são aplicadas por sua adição às opções do MVC ou pela implementação de Attribute s e sua
aplicação a controladores, ações ou parâmetros de ação (semelhante a Filters ). Ao contrário dos filtros, as
convenções são executadas apenas quando o aplicativo é iniciado, não como parte de cada solicitação.
Amostra: modificando o ApplicationModel
A convenção a seguir é usada para adicionar uma propriedade ao modelo de aplicativo.
namespace AppModelSample.Conventions
{
public class ApplicationDescription : IApplicationModelConvention
{
private readonly string _description;
public ApplicationDescription(string description)

{
_description = description;
}
public void Apply(ApplicationModel application)

{
application.Properties["description"] = _description;
}
}
}
As convenções de modelo de aplicativo são aplicadas como opções quando o MVC é adicionado em
ConfigureServices em Startup .

{
{
options.Conventions.Add(new ApplicationDescription("My Application Description"));
options.Conventions.Add(new NamespaceRoutingConvention());
//options.Conventions.Add(new IdsMustBeInRouteParameterModelConvention());
});
}
As propriedades são acessíveis na coleção de propriedades ActionDescriptor nas ações do controlador:
public class AppModelController : Controller

{
public string Description()
{
return "Description: " + ControllerContext.ActionDescriptor.Properties["description"];
}
}
Amostra: modificando a descrição de ControllerModel

Como no exemplo anterior, o modelo de controlador também pode ser modificado para incluir propriedades
personalizadas. Elas substituirão as propriedades existentes com o mesmo nome especificado no modelo de
aplicativo. O seguinte atributo de convenção adiciona uma descrição no nível do controlador:
using System;
{
public class ControllerDescriptionAttribute : Attribute, IControllerModelConvention
{
public ControllerDescriptionAttribute(string description)

{
}
public void Apply(ControllerModel controllerModel)

{
controllerModel.Properties["description"] = _description;
}
}
}
Essa convenção é aplicada como um atributo em um controlador.
[ControllerDescription("Controller Description")]
public class DescriptionAttributesController : Controller
{
{
}
A propriedade "description" é acessada da mesma maneira como nos exemplos anteriores.

Amostra: modificando a descrição de ActionModel
Uma convenção de atributo separada pode ser aplicada a ações individuais, substituindo o comportamento já
aplicado no nível do aplicativo ou do controlador.
using System;
{
public class ActionDescriptionAttribute : Attribute, IActionModelConvention
{
public ActionDescriptionAttribute(string description)

{
}
public void Apply(ActionModel actionModel)

{
actionModel.Properties["description"] = _description;
}
}
}
A aplicação disso a uma ação no controlador do exemplo anterior demonstra como ela substitui a convenção no
nível do controlador:
[ControllerDescription("Controller Description")]
public class DescriptionAttributesController : Controller
{
{
}
[ActionDescription("Action Description")]
public string UseActionDescriptionAttribute()
{
}
}
Amostra: modificando o ParameterModel

A convenção a seguir pode ser aplicada a parâmetros de ação para modificar seu BindingInfo . A convenção a
seguir exige que o parâmetro seja um parâmetro de rota; outras possíveis origens da associação (como valores de
cadeia de caracteres de consulta) são ignoradas.
using System;
{
public class MustBeInRouteParameterModelConvention : Attribute, IParameterModelConvention
{
public void Apply(ParameterModel model)
{
if (model.BindingInfo == null)
{
model.BindingInfo = new BindingInfo();
}
model.BindingInfo.BindingSource = BindingSource.Path;
}
}
}
O atributo pode ser aplicado a qualquer parâmetro de ação:
public class ParameterModelController : Controller

{
// Will bind: /ParameterModel/GetById/123
// WON'T bind: /ParameterModel/GetById?id=123
public string GetById([MustBeInRouteParameterModelConvention]int id)
{
return $"Bound to id: {id}";
}
}
Amostra: modificando o nome de ActionModel

A convenção a seguir modifica o ActionModel para atualizar o nome da ação ao qual ele é aplicado. O novo nome
é fornecido como um parâmetro para o atributo. Esse novo nome é usado pelo roteamento e, portanto, isso afetará
a rota usada para acessar esse método de ação.
using System;
{
public class CustomActionNameAttribute : Attribute, IActionModelConvention
{
private readonly string _actionName;
public CustomActionNameAttribute(string actionName)

{
_actionName = actionName;
}
public void Apply(ActionModel actionModel)

{
// this name will be used by routing
actionModel.ActionName = _actionName;
}
}
}
Esse atributo é aplicado a um método de ação no HomeController :
// Route: /Home/MyCoolAction
[CustomActionName("MyCoolAction")]
public string SomeName()
{
return ControllerContext.ActionDescriptor.ActionName;
}
Mesmo que o nome do método seja SomeName , o atributo substitui a convenção do MVC de uso do nome do
método e substitui o nome da ação por MyCoolAction . Portanto, a rota usada para acessar essa ação é
/Home/MyCoolAction .
NOTE
Esse exemplo é basicamente o mesmo que usar o atributo ActionName interno.
Amostra: convenção de roteamento personalizada

Use uma IApplicationModelConvention para personalizar como funciona o roteamento. Por exemplo, a seguinte
convenção incorporará namespaces dos Controladores em suas rotas, substituindo . no namespace por / na
rota:
using System.Linq;
{
public class NamespaceRoutingConvention : IApplicationModelConvention
{
{
foreach (var controller in application.Controllers)
{
var hasAttributeRouteModels = controller.Selectors
.Any(selector => selector.AttributeRouteModel != null);
if (!hasAttributeRouteModels
&& controller.ControllerName.Contains("Namespace")) // affect one controller in this sample
{
// Replace the . in the namespace with a / to create the attribute route
// Ex: MySite.Admin namespace will correspond to MySite/Admin attribute route
// Then attach [controller], [action] and optional {id?} token.
// [Controller] and [action] is replaced with the controller and action
// name to generate the final template
controller.Selectors[0].AttributeRouteModel = new AttributeRouteModel()
{
Template = controller.ControllerType.Namespace.Replace('.', '/') +
"/[controller]/[action]/{id?}"
};
}
}
// You can continue to put attribute route templates for the controller actions depending on the
way you want them to behave
}
}
}
A convenção é adicionada como uma opção na classe Startup.

{
{
options.Conventions.Add(new ApplicationDescription("My Application Description"));
options.Conventions.Add(new NamespaceRoutingConvention());
//options.Conventions.Add(new IdsMustBeInRouteParameterModelConvention());
});
}
TIP
Adicione convenções ao middleware acessando MvcOptions com
services.Configure<MvcOptions>(c => c.Conventions.Add(YOURCONVENTION));
Esta amostra aplica essa convenção às rotas que não estão usando o roteamento de atributo, nas quais o
controlador tem "Namespace" em seu nome. O seguinte controlador demonstra essa convenção:
namespace AppModelSample.Controllers
{
public class NamespaceRoutingController : Controller
{
// using NamespaceRoutingConvention
// route: /AppModelSample/Controllers/NamespaceRouting/Index
{
return "This demonstrates namespace routing.";
}
}
}
Uso do modelo de aplicativo em WebApiCompatShim

O ASP.NET Core MVC usa um conjunto diferente de convenções da API Web ASP.NET 2. Usando convenções
personalizadas, você pode modificar o comportamento de um aplicativo ASP.NET Core MVC para que ele seja
consistente com o comportamento de um aplicativo de API Web. A Microsoft fornece o WebApiCompatShim
especificamente para essa finalidade.
NOTE
Saiba mais sobre migração da API Web ASP.NET.
Para usar o Shim de Compatibilidade de API Web, você precisa adicionar o pacote ao projeto e, em seguida,
adicionar as convenções ao MVC chamando AddWebApiConventions em Startup :
services.AddMvc().AddWebApiConventions();
As convenções fornecidas pelo shim são aplicadas apenas às partes do aplicativo que tiveram determinados
atributos aplicados a elas. Os seguintes quatro atributos são usados para controlar quais controladores devem ter
suas convenções modificadas pelas convenções do shim:
UseWebApiActionConventionsAttribute
UseWebApiOverloadingAttribute
UseWebApiParameterConventionsAttribute
UseWebApiRoutesAttribute
Convenções de ação
O UseWebApiActionConventionsAttribute é usado para mapear o método HTTP para ações com base em seu nome
(por exemplo, Get será mapeado para HttpGet ). Ele se aplica somente a ações que não usam o roteamento de
atributo.
Sobrecarga
O UseWebApiOverloadingAttribute é usado para aplicar a convenção WebApiOverloadingApplicationModelConvention .
Essa convenção adiciona uma OverloadActionConstraint ao processo de seleção de ação, o que limita as ações de
candidato àquelas para as quais a solicitação atende a todos os parâmetros não opcionais.
Convenções de parâmetro
O UseWebApiParameterConventionsAttribute é usado para aplicar a convenção de ação
WebApiParameterConventionsApplicationModelConvention . Essa convenção especifica que tipos simples usados como
parâmetros de ação são associados por meio do URI por padrão, enquanto tipos complexos são associados por
meio do corpo da solicitação.
Rotas
O UseWebApiRoutesAttribute controla se a convenção de controlador WebApiApplicationModelConvention é aplicada.
Quando habilitada, essa convenção é usada para adicionar suporte de áreas à rota.
Além de um conjunto de convenções, o pacote de compatibilidade inclui uma classe base
System.Web.Http.ApiController que substitui aquela fornecida pela API Web. Isso permite que os controladores
escritos para a API Web e que herdam de seu ApiController funcionem como foram criados, enquanto são
executados no ASP.NET Core MVC. Essa classe base de controlador é decorada com todos os atributos
UseWebApi* listados acima. O ApiController expõe propriedades, métodos e tipos de resultado compatíveis com
aqueles encontrados na API Web.
Usando o ApiExplorer para documentar o aplicativo

O modelo de aplicativo expõe uma propriedade ApiExplorer em cada nível, que pode ser usada para percorrer a
estrutura do aplicativo. Isso pode ser usado para gerar páginas da Ajuda para as APIs Web usando ferramentas
como o Swagger. A propriedade ApiExplorer expõe uma propriedade IsVisible que pode ser definida para
especificar quais partes do modelo do aplicativo devem ser expostas. Defina essa configuração usando uma
convenção:
{
public class EnableApiExplorerApplicationConvention : IApplicationModelConvention
{
{
application.ApiExplorer.IsVisible = true;
}
}
}
Usando essa abordagem (e convenções adicionais, se necessário), você pode habilitar ou desabilitar a visibilidade
da API em qualquer nível no aplicativo.
Filtros no ASP.NET Core
Por Rick Anderson, Tom Dykstra e Steve Smith

Os Filtros no ASP.NET Core MVC permitem executar código antes ou depois de determinados estágios do
pipeline de processamento de solicitações.
IMPORTANT
Este tópico não se aplica a Páginas Razor. O ASP.NET Core 2.1 e posterior dão suporte a IPageFilter e
IAsyncPageFilter nas Páginas do Razor. Para obter mais informações, confira Métodos de filtro para Páginas Razor.
O filtros internos lidam com tarefas como:

Autorização (impedir o acesso a recursos aos quais o usuário não está autorizado).
Garantir que todas as solicitações usem HTTPS.
Cache de resposta (causar um curto-circuito do pipeline de solicitação para retornar uma resposta
armazenada em cache).
É possível criar filtros personalizados para lidar com interesses paralelos. Os filtros podem evitar a
duplicação de código entre as ações. Por exemplo, um filtro de exceção de tratamento de erro poderia
consolidar o tratamento de erro.
Como os filtros funcionam?

Os filtros são executados dentro do pipeline de invocação de ações do MVC, às vezes chamado de pipeline
de filtros. O pipeline de filtros é executado após o MVC selecionar a ação a ser executada.
Tipos de filtro
Cada tipo de filtro é executado em um estágio diferente no pipeline de filtros.
Filtros de autorização são executados primeiro e são usados para determinar se o usuário atual tem
autorização para a solicitação atual. Eles podem fazer um curto-circuito do pipeline quando uma
solicitação não é autorizada.
Filtros de recurso são os primeiros a lidar com uma solicitação após a autorização. Eles podem
executar código antes do restante do pipeline de filtros e após o restante do pipeline ser concluído.
Esses filtros são úteis para implementar o cache ou para, de alguma forma, fazer o curto-circuito do
pipeline de filtros por motivos de desempenho. Eles são executados antes do model binding,
portanto, podem influenciar o model binding.
Filtros de ação podem executar código imediatamente antes e depois de um método de ação
individual ser chamado. Eles podem ser usados para manipular os argumentos passados para uma
ação, bem como o resultado da ação.
Filtros de exceção são usados para aplicar políticas globais para exceções sem tratamento que
ocorrem antes que qualquer coisa tenha sido gravada no corpo da resposta.
Filtros de resposta podem executar código imediatamente antes e depois da execução de resultados
de ações individuais. Eles são executados somente quando o método de ação é executado com êxito.
Eles são úteis para a lógica que precisa envolver a execução da exibição ou do formatador.
O diagrama a seguir mostra como esses tipos de filtro interagem no pipeline de filtros.
Implementação
Os filtros dão suporte a implementações síncronas e assíncronas por meio de diferentes definições de
interface.
Filtros síncronos que podem executar código antes e depois do estágio do pipeline definem os métodos
OnStageExecuting e OnStageExecuted. Por exemplo, OnActionExecuting é chamado antes que o método de
ação seja chamado e OnActionExecuted é chamado após o método de ação retornar.
using FiltersSample.Helper;
namespace FiltersSample.Filters
{
public class SampleActionFilter : IActionFilter
{
public void OnActionExecuting(ActionExecutingContext context)
{
// do something before the action executes
}
public void OnActionExecuted(ActionExecutedContext context)

{
// do something after the action executes
}
}
}
Filtros assíncronos definem um único método OnStageExecutionAsync. Esse método usa um delegado
FilterTypeExecutionDelegate, que executa o estágio de pipeline do filtro. Por exemplo,
ActionExecutionDelegate chama o método de ação ou o próximo filtro de ação, e você pode executar código
antes e depois de chamá-lo.
{
public class SampleAsyncActionFilter : IAsyncActionFilter
{
public async Task OnActionExecutionAsync(
ActionExecutingContext context,
ActionExecutionDelegate next)
{
var resultContext = await next();
// do something after the action executes; resultContext.Result will be set
}
}
}
É possível implementar interfaces para vários estágios do filtro em uma única classe. Por exemplo, a classe
ActionFilterAttribute implementa IActionFilter , IResultFilter e seus equivalentes assíncronos.
NOTE
Implemente ou a versão assíncrona ou a versão síncrona de uma interface de filtro, não ambas. Primeiro, a estrutura
verifica se o filtro implementa a interface assíncrona e, se for esse o caso, a chama. Caso contrário, ela chama os
métodos da interface síncrona. Se você implementasse as duas interfaces em uma classe, somente o método
assíncrono seria chamado. Ao usar classes abstratas como ActionFilterAttribute, você substituiria apenas os métodos
síncronos ou o método assíncrono para cada tipo de filtro.
IFilterFactory
IFilterFactory implementa IFilterMetadata. Portanto, uma instância IFilterFactory pode ser usada como
uma instância IFilterMetadata em qualquer parte do pipeline de filtro. Quando se prepara para invocar o
filtro, a estrutura tenta convertê-lo em um IFilterFactory . Se essa conversão for bem-sucedida, o método
CreateInstance será chamado para criar a instância IFilterMetadata que será invocada. Isso fornece um
design flexível, porque o pipeline de filtro preciso não precisa ser definido explicitamente quando o
aplicativo é iniciado.
Você pode implementar IFilterFactory em suas próprias implementações de atributo como outra
abordagem à criação de filtros:
public class AddHeaderWithFactoryAttribute : Attribute, IFilterFactory
{
// Implement IFilterFactory
public IFilterMetadata CreateInstance(IServiceProvider serviceProvider)
{
return new InternalAddHeaderFilter();
}
private class InternalAddHeaderFilter : IResultFilter

{
{
"Internal", new string[] { "Header Added" });
}

{
}
}
public bool IsReusable

{
get
{
return false;
}
}
}
Atributos de filtro internos

A estrutura inclui filtros internos baseados em atributos que você pode organizar em subclasses e
personalizar. Por exemplo, o seguinte Filtro de resultado adiciona um cabeçalho à resposta.
{
{
private readonly string _value;
public AddHeaderAttribute(string name, string value)

{
_name = name;
_value = value;
}

{
_name, new string[] { _value });
base.OnResultExecuting(context);
}
}
}
Os atributos permitem que os filtros aceitem argumentos, conforme mostrado no exemplo acima. Você
adicionaria esse atributo a um método de ação ou controlador e especificaria o nome e o valor do
cabeçalho HTTP:
[AddHeader("Author", "Steve Smith @ardalis")]
public class SampleController : Controller
{
{
return Content("Examine the headers using developer tools.");
}
[ShortCircuitingResourceFilter]
public IActionResult SomeResource()
{
return Content("Successful access to resource - header should be set.");
}
O resultado da ação Index é mostrado abaixo – os cabeçalhos de resposta são exibidos na parte inferior
direita.
Várias interfaces de filtro têm atributos correspondentes que podem ser usados como classes base para
implementações personalizadas.
Atributos de filtro:
ActionFilterAttribute
ExceptionFilterAttribute
ResultFilterAttribute
FormatFilterAttribute
ServiceFilterAttribute
TypeFilterAttribute
TypeFilterAttribute e ServiceFilterAttribute são explicados posteriormente neste artigo.
Escopos e ordem de execução dos filtros

Um filtro pode ser adicionado ao pipeline com um de três escopos. É possível adicionar um filtro a um
método de ação específico ou a uma classe de controlador usando um atributo. Ou você pode registrar um
filtro globalmente para todos os controladores e ações. Os filtros são adicionados globalmente quando são
adicionados à coleção MvcOptions.Filters em ConfigureServices :
{
{
options.Filters.Add(new AddHeaderAttribute("GlobalAddHeader",
"Result filter added to MvcOptions.Filters")); // an instance
options.Filters.Add(typeof(SampleActionFilter)); // by type
options.Filters.Add(new SampleGlobalActionFilter()); // an instance
});
services.AddScoped<AddHeaderFilterWithDi>();
}
Ordem padrão de execução

Quando há vários filtros para um determinado estágio do pipeline, o escopo determina a ordem padrão de
execução dos filtros. Filtros globais circundam filtros de classe, que, por sua vez, circundam filtros de
método. Isso é, às vezes, chamado de aninhamento de "bonecas russas", pois cada aumento de escopo é
encapsulado em torno do escopo anterior, como uma matriosca. Normalmente, você obtém o
comportamento de substituição desejado sem precisar determinar uma ordem explicitamente.
Como resultado desse aninhamento, o código posterior dos filtros é executado na ordem inversa do código
anterior. A sequência é semelhante a esta:
O código anterior de filtros aplicados globalmente
O código anterior de filtros aplicados a controladores
O código anterior de filtros aplicados a métodos de ação
O código posterior de filtros aplicados a métodos de ação
O código posterior de filtros aplicados a controladores
O código posterior de filtros aplicados globalmente
Este é um exemplo que ilustra a ordem na qual métodos de filtro são chamados para filtros de ação
síncronos.
SEQUÊNCIA ESCOPO DO FILTRO MÉTODO DO FILTRO
1 Global OnActionExecuting
2 Controlador OnActionExecuting
3 Método OnActionExecuting
4 Método OnActionExecuted
5 Controlador OnActionExecuted
6 Global OnActionExecuted
Esta sequência mostra:

O filtro de método está aninhado no filtro de controlador.
O filtro de controlador está aninhado no filtro global.
Para colocar de outra forma, se você estiver dentro do método OnStageExecutionAsync de um filtro
assíncrono, todos os filtros com escopo mais estreito serão executados enquanto seu código estiver na
pilha.
NOTE
Cada controlador que herda da classe base Controller inclui os métodos OnActionExecuting e
OnActionExecuted . Esses métodos encapsulam os filtros que são executados para uma determinada ação:
OnActionExecuting é chamado antes de qualquer um dos filtros e OnActionExecuted é chamado após todos os
filtros.
Substituindo a ordem padrão

É possível substituir a sequência padrão de execução implementando IOrderedFilter . Essa interface expõe
uma propriedade Order que tem precedência sobre o escopo para determinar a ordem de execução. Um
filtro com um valor mais baixo de Order terá seu código anterior executado antes que um filtro com um
valor mais alto de Order . Um filtro com um valor mais baixo de Order terá seu código posterior executado
depois que um filtro com um valor mais alto de Order . Você pode definir a propriedade Order usando um
parâmetro de construtor:
[MyFilter(Name = "Controller Level Attribute", Order=1)]
Se você tiver os mesmos três filtros de ação mostrados no exemplo anterior, mas definir a propriedade
Order dos filtros de controlador e global como 1 e 2 respectivamente, a ordem de execução será invertida.
SEQUÊNCIA ESCOPO DO FILTRO PROPRIEDADE ORDER MÉTODO DO FILTRO
1 Método 0 OnActionExecuting
2 Controlador 1 OnActionExecuting
3 Global 2 OnActionExecuting
4 Global 2 OnActionExecuted
5 Controlador 1 OnActionExecuted
6 Método 0 OnActionExecuted
A propriedade Order tem precedência sobre o escopo ao determinar a ordem na qual os filtros serão
executados. Os filtros são classificados primeiro pela ordem e o escopo é usado para desempatar. Todos os
filtros internos implementam IOrderedFilter e definem o valor de Order padrão como 0. Para os filtros
internos, o escopo determina a ordem, a menos que você defina Order com um valor diferente de zero.
Cancelamento e curto-circuito
Você pode fazer um curto-circuito no pipeline de filtros a qualquer momento, definindo a propriedade
Result no parâmetro context fornecido ao método do filtro. Por exemplo, o filtro de recurso a seguir
impede que o resto do pipeline seja executado.
using System;
{
public class ShortCircuitingResourceFilterAttribute : Attribute,
IResourceFilter
{
public void OnResourceExecuting(ResourceExecutingContext context)
{
context.Result = new ContentResult()
{
Content = "Resource unavailable - header should not be set"
};
}
public void OnResourceExecuted(ResourceExecutedContext context)

{
}
}
}
No código a seguir, os filtros ShortCircuitingResourceFilter e AddHeader têm como destino o método de

ação SomeResource . O ShortCircuitingResourceFilter :
É executado primeiro, porque ele é um filtro de recurso e AddHeader é um filtro de ação.
Causa um curto-circuito no restante do pipeline.
Portanto, o filtro AddHeader nunca é executado para a ação SomeResource . Esse comportamento seria o
mesmo se os dois filtros fossem aplicados no nível do método de ação, desde que
ShortCircuitingResourceFilter fosse executado primeiro. O ShortCircuitingResourceFilter é executado
primeiro, devido ao seu tipo de filtro ou pelo uso explícito da propriedade Order .
[AddHeader("Author", "Steve Smith @ardalis")]

public class SampleController : Controller
{
{
return Content("Examine the headers using developer tools.");
}
[ShortCircuitingResourceFilter]
public IActionResult SomeResource()
{
return Content("Successful access to resource - header should be set.");
}
Filtros podem ser adicionados por tipo ou por instância. Se você adicionar uma instância, ela será usada
para cada solicitação. Se você adicionar um tipo, ele será ativado pelo tipo, o que significa que uma
instância será criada para cada solicitação e as dependências de construtor serão populadas pela DI (injeção
de dependência). Adicionar um filtro por tipo é equivalente a
filters.Add(new TypeFilterAttribute(typeof(MyFilter))) .
Filtros que são implementados como atributos e adicionados diretamente a classes de controlador ou
métodos de ação não podem ter dependências de construtor fornecidas pela DI (injeção de dependência).
Isso ocorre porque os atributos precisam ter os parâmetros de construtor fornecidos quando eles são
aplicados. Essa é uma limitação do funcionamento dos atributos.
Se seus filtros tiverem dependências que você precisa acessar da DI, há várias abordagens com suporte. É
possível aplicar o filtro a um método de ação ou classe usando uma das opções a seguir:
TypeFilterAttribute
IFilterFactory implementado em seu atributo
NOTE
Uma dependência que talvez você queira obter da DI é um agente. No entanto, evite criar e usar filtros apenas para
fins de registro em log, pois é possível que os recursos de registro em log da estrutura interna já forneçam o que
você precisa. Se você for adicionar o registro em log a seus filtros, ele deve se concentrar em questões referentes ao
domínio de negócios ou ao comportamento específico de seu filtro, em vez de ações do MVC ou outros eventos da
estrutura.
Tipos de implementação do filtro de serviço são registrados em DI. Um ServiceFilterAttribute recupera
uma instância do filtro da DI. Adicione o ServiceFilterAttribute ao contêiner em
Startup.ConfigureServices e faça uma referência a ele em um atributo [ServiceFilter] :

{
{
options.Filters.Add(new AddHeaderAttribute("GlobalAddHeader",
"Result filter added to MvcOptions.Filters")); // an instance
options.Filters.Add(typeof(SampleActionFilter)); // by type
options.Filters.Add(new SampleGlobalActionFilter()); // an instance
});
services.AddScoped<AddHeaderFilterWithDi>();
}
[ServiceFilter(typeof(AddHeaderFilterWithDi))]
{
return View();
}
Ao usar ServiceFilterAttribute , configurar IsReusable é uma dica de que a instância de filtro pode ser
reutilizada fora do escopo de solicitação em que ele foi criada. A estrutura não fornece garantias de que
uma única instância do filtro vá ser criada ou que o filtro não será solicitado novamente do contêiner de DI
em algum momento posterior. Evite usar IsReusable ao usar um filtro que dependa dos serviços com um
tempo de vida diferente de singleton.
Usar ServiceFilterAttribute sem registrar o tipo de filtro gera uma exceção:
System.InvalidOperationException: No service for type

'FiltersSample.Filters.AddHeaderFilterWithDI' has been registered.
ServiceFilterAttribute implementa IFilterFactory . IFilterFactory expõe o método CreateInstance

para criar uma instância de IFilterMetadata . O método CreateInstance carrega o tipo especificado do
contêiner de serviços (DI).
TypeFilterAttribute
O TypeFilterAttribute é semelhante ao ServiceFilterAttribute , mas seu tipo não é resolvido diretamente
por meio do contêiner de DI. Ele cria uma instância do tipo usando
Microsoft.Extensions.DependencyInjection.ObjectFactory .
Por causa dessa diferença:

Os tipos que são referenciados usando o TypeFilterAttribute não precisam ser registrados no
contêiner primeiro. As dependências deles são atendidas pelo contêiner.
Opcionalmente, o TypeFilterAttribute pode aceitar argumentos de construtor para o tipo.
Ao usar TypeFilterAttribute , configurar IsReusable é uma dica de que a instância de filtro pode ser
reutilizada fora do escopo de solicitação em que ele foi criada. A estrutura não fornece nenhuma garantia
de que uma única instância do filtro será criada. Evite usar IsReusable ao usar um filtro que dependa dos
serviços com um tempo de vida diferente de singleton.
O exemplo a seguir demonstra como passar argumentos para um tipo usando TypeFilterAttribute :
[TypeFilter(typeof(AddHeaderAttribute),
Arguments = new object[] { "Author", "Steve Smith (@ardalis)" })]
public IActionResult Hi(string name)
{
return Content($"Hi {name}");
}
IFilterFactory implementado em seu atributo

Se você tiver um filtro que:
Não exija nenhum argumento.
Tenha dependências de construtor que precisem ser atendidas pela DI.
Você pode usar seu próprio atributo nomeado em classes e métodos em vez de
[TypeFilter(typeof(FilterType))] ). O filtro a seguir mostra como isso pode ser implementado:
public class SampleActionFilterAttribute : TypeFilterAttribute
{
public SampleActionFilterAttribute():base(typeof(SampleActionFilterImpl))
{
}
private class SampleActionFilterImpl : IActionFilter

{
public SampleActionFilterImpl(ILoggerFactory loggerFactory)
{
_logger = loggerFactory.CreateLogger<SampleActionFilterAttribute>();
}

{
_logger.LogInformation("Business action starting...");
// perform some business logic work

{
// perform some business logic work
_logger.LogInformation("Business action completed.");
}
}
}
Esse filtro pode ser aplicado a classes ou métodos usando a sintaxe [SampleActionFilter] , em vez de
precisar usar [TypeFilter] ou [ServiceFilter] .
Filtros de autorização
*Filtros de autorização:
Controlam o acesso aos métodos de ação.
São os primeiros filtros a serem executados no pipeline de filtro.
Têm um método anterior, mas não têm um método posterior.
Você deve escrever somente um filtro de autorização personalizado se estiver escrevendo sua própria
estrutura de autorização. Prefira configurar suas políticas de autorização ou escrever uma política de
autorização personalizada em vez de escrever um filtro personalizado. A implementação do filtro interno é
responsável somente por chamar o sistema de autorização.
Você não deve gerar exceções dentro de filtros de autorização, pois nada tratará a exceção (os filtros de
exceção não as tratarão). Considere a possibilidade de emitir um desafio quando ocorrer uma exceção.
Saiba mais sobre Autorização.
Filtros de recurso
Implementam a interface IResourceFilter ou IAsyncResourceFilter .
Suas execuções encapsulam a maior parte do pipeline de filtro.
Somente os Filtros de autorização são executados antes dos Filtros de recurso.
Os filtros de recursos são úteis para causar um curto-circuito na maior parte do trabalho que uma
solicitação faz. Por exemplo, um filtro de cache poderá evitar o restante do pipeline se a resposta estiver no
cache.
O filtro de recurso com curto-circuito mostrado anteriormente é um exemplo de filtro de recurso. Outro
exemplo é DisableFormValueModelBindingAttribute:
Essa opção impedirá o model binding de acessar os dados do formulário.
Ela é útil para uploads de arquivos grandes e para impedir que o formulário seja lido na memória.
Filtros de ação
Filtros de ação:
Implementam a interface IActionFilter ou IAsyncActionFilter .
A execução deles envolve a execução de métodos de ação.
Veja um exemplo de filtro de ação:
public class SampleActionFilter : IActionFilter

{
{
}

{
// do something after the action executes
}
}
ActionExecutingContext fornece as seguintes propriedades:

ActionArguments – permite manipular as entradas para a ação.
Controller – permite manipular a instância do controlador.
Result – defini-lo faz um curto-circuito da execução do método de ação e dos filtros de ação
posteriores. Apresentar uma exceção também impete a execução do método de ação e dos filtros
posteriores, mas isso é tratado como uma falha, e não como um resultado bem-sucedido.
ActionExecutedContext fornece Controller e Result , bem como as seguintes propriedades:
Canceled – será verdadeiro se a execução da ação tiver sofrido curto-circuito por outro filtro.
Exception – não será nulo se a ação ou um filtro de ação posterior tiver apresentado uma exceção.
Definir essa propriedade como nula “manipula” uma exceção efetivamente e Result será executado
como se tivesse sido retornado do método de ação normalmente.
Para um IAsyncActionFilter , uma chamada para o ActionExecutionDelegate :
Executa todos os próximos filtros de ação e o método de ação.
Retorna ActionExecutedContext .
Para fazer um curto-circuito, atribua ActionExecutingContext.Result a uma instância de resultado e não
chame o ActionExecutionDelegate .
A estrutura fornece um ActionFilterAttribute abstrato que você pode colocar em uma subclasse.
Você poderá usar um filtro de ação para validar o estado do modelo e retornar erros se o estado for
inválido:
{
public class ValidateModelAttribute : ActionFilterAttribute
{
public override void OnActionExecuting(ActionExecutingContext context)
{
if (!context.ModelState.IsValid)
{
context.Result = new BadRequestObjectResult(context.ModelState);
}
}
}
}
O método OnActionExecuted é executado depois do método de ação e pode ver e manipular os resultados
da ação por meio da propriedade ActionExecutedContext.Result . ActionExecutedContext.Canceled será
definido como verdadeiro se a execução da ação tiver sofrido curto-circuito por outro filtro.
ActionExecutedContext.Exception será definido como um valor não nulo se a ação ou um filtro de ação
posterior tiver apresentado uma exceção. Definindo ActionExecutedContext.Exception como nulo:
'Trata' efetivamente uma exceção.
ActionExectedContext.Result é executado como se fosse retornado normalmente do método de ação.
Filtros de exceção
Filtros de exceção implementam a interface IExceptionFilter ou IAsyncExceptionFilter . Eles podem ser
usados para implementar políticas de tratamento de erro comuns para um aplicativo.
O exemplo de filtro de exceção a seguir usa uma exibição de erro do desenvolvedor personalizada para
exibir detalhes sobre exceções que ocorrem quando o aplicativo está em desenvolvimento:
public class CustomExceptionFilterAttribute : ExceptionFilterAttribute

{
private readonly IHostingEnvironment _hostingEnvironment;
private readonly IModelMetadataProvider _modelMetadataProvider;
public CustomExceptionFilterAttribute(
IHostingEnvironment hostingEnvironment,
IModelMetadataProvider modelMetadataProvider)
{
_hostingEnvironment = hostingEnvironment;
_modelMetadataProvider = modelMetadataProvider;
}
public override void OnException(ExceptionContext context)

{
if (!_hostingEnvironment.IsDevelopment())
{
// do nothing
return;
}
var result = new ViewResult {ViewName = "CustomError"};
result.ViewData = new ViewDataDictionary(_modelMetadataProvider,context.ModelState);
result.ViewData.Add("Exception", context.Exception);
// TODO: Pass additional detailed data via ViewData
context.Result = result;
}
}
Filtros de exceção:
Não têm eventos anteriores nem posteriores.
Implementam OnException ou OnExceptionAsync .
Tratam as exceções sem tratamento que ocorrem na criação do controlador, no model binding, nos
filtros de ação ou nos métodos de ação.
Não capturam as exceções que ocorrem em Filtros de recurso, em Filtros de resultado ou na execução
do Resultado de MVC.
Para tratar uma exceção, defina a propriedade ExceptionContext.ExceptionHandled como verdadeiro ou
grave uma resposta. Isso interrompe a propagação da exceção. Um Filtro de exceção não pode transformar
uma exceção em "êxito". Somente um filtro de ação pode fazer isso.
NOTE
No ASP.NET Core 1.1, a resposta não será enviada se você definir ExceptionHandled como true e gravar uma
resposta. Nesse cenário, o ASP.NET Core 1.0 envia a resposta e o ASP.NET Core 1.1.2 retorna ao comportamento do
1.0. Para obter mais informações, consulte problema #5594 no repositório do GitHub.
Filtros de exceção:
São bons para interceptar as exceções que ocorrem nas ações de MVC.
Não são tão flexíveis quanto o middleware de tratamento de erro.
Prefira o middleware para tratamento de exceção. Use filtros de exceção somente quando você precisar
fazer o tratamento de erro de forma diferente com base na ação de MVC escolhida. Por exemplo, seu
aplicativo pode ter métodos de ação para os pontos de extremidade da API e para modos de
exibição/HTML. Os pontos de extremidade da API podem retornar informações de erro como JSON,
enquanto as ações baseadas em modo de exibição podem retornar uma página de erro como HTML.
O ExceptionFilterAttribute pode tornar-se uma subclasse.
Filtros de resultado
Implementam a interface IResultFilter ou IAsyncResultFilter .
A execução deles envolve a execução de resultados de ação.
Veja um exemplo de um filtro de resultado que adiciona um cabeçalho HTTP.
public class AddHeaderFilterWithDi : IResultFilter
{
private ILogger _logger;
public AddHeaderFilterWithDi(ILoggerFactory loggerFactory)
{
_logger = loggerFactory.CreateLogger<AddHeaderFilterWithDi>();
}

{
var headerName = "OnResultExecuting";
headerName, new string[] { "ResultExecutingSuccessfully" });
_logger.LogInformation($"Header added: {headerName}");
}

{
// Can't add to headers here because response has already begun.
}
}
O tipo de resultado que está sendo executado depende da ação em questão. Uma ação de MVC que retorna
um modo de exibição incluiria todo o processamento de Razor como parte do ViewResult em execução.
Um método de API pode executar alguma serialização como parte da execução do resultado. Saiba mais
sobre resultados de ação
Filtros de resultado são executados somente para resultados bem-sucedidos – quando a ação ou filtros da
ação produzem um resultado de ação. Filtros de resultado não são executados quando filtros de exceção
tratam uma exceção.
O método OnResultExecuting pode fazer o curto-circuito da execução do resultado da ação e dos filtros de
resultados posteriores definindo ResultExecutingContext.Cancel como verdadeiro. De modo geral, você
deve gravar no objeto de resposta ao fazer um curto-circuito para evitar gerar uma resposta vazia. A
geração de uma exceção vai:
Impedir a execução do resultado da ação e dos próximos filtros.
Ser tratada como uma falha e não como um resultado com êxito.
Quando o método OnResultExecuted é executado, a resposta provavelmente foi enviada ao cliente e não
pode mais ser alterada (a menos que uma exceção tenha sido apresentada).
ResultExecutedContext.Canceled será definido como verdadeiro se a execução do resultado da ação tiver
sofrido curto-circuito por outro filtro.
ResultExecutedContext.Exception será definido como um valor não nulo se o resultado da ação ou um filtro
de resultado posterior tiver apresentado uma exceção. Definir Exception para como nulo “trata” uma
exceção com eficiência e impede que a exceção seja apresentada novamente pelo MVC posteriormente no
pipeline. Quando está tratando uma exceção em um filtro de resultado, talvez você não possa gravar dados
na resposta. Se o resultado da ação for apresentado durante sua execução e os cabeçalhos já tiverem sido
liberados para o cliente, não haverá nenhum mecanismo confiável para enviar um código de falha.
Para um IAsyncResultFilter , uma chamada para await next no ResultExecutionDelegate executa
qualquer filtro de resultado posterior e o resultado da ação. Para fazer um curto-circuito, defina
ResultExecutingContext.Cancel para verdadeiro e não chame ResultExectionDelegate .
A estrutura fornece um ResultFilterAttribute abstrato que você pode colocar em uma subclasse. A classe
AddHeaderAttribute mostrada anteriormente é um exemplo de atributo de filtro de resultado.
Usando middleware no pipeline de filtros
Filtros de recursos funcionam como middleware, no sentido em que envolvem a execução de tudo o que
vem depois no pipeline. Mas os filtros diferem do middleware porque fazem parte do MVC, o que significa
que eles têm acesso ao contexto e a constructos do MVC.
No ASP.NET Core 1.1, você pode usar o middleware no pipeline de filtros. Talvez você queira fazer isso se
tiver um componente de middleware que precisa acessar dados de rota do MVC ou que precisa ser
executado somente para determinados controladores ou ações.
Para usar o middleware como um filtro, crie um tipo com um método Configure que especifica o
middleware que você deseja injetar no pipeline de filtros. Veja um exemplo que usa o middleware de
localização para estabelecer a cultura atual para uma solicitação:
public class LocalizationPipeline

{
public void Configure(IApplicationBuilder applicationBuilder)
{
var supportedCultures = new[]
{
new CultureInfo("en-US"),
new CultureInfo("fr")
};
var options = new RequestLocalizationOptions

{
DefaultRequestCulture = new RequestCulture(culture: "en-US", uiCulture: "en-US"),

SupportedCultures = supportedCultures,
SupportedUICultures = supportedCultures
};
options.RequestCultureProviders = new[]
{ new RouteDataRequestCultureProvider() { Options = options } };
applicationBuilder.UseRequestLocalization(options);
}
}
Depois, você pode usar o MiddlewareFilterAttribute para executar o middleware para um controlador ou
ação selecionada ou para executá-lo globalmente:
[Route("{culture}/[controller]/[action]")]
[MiddlewareFilter(typeof(LocalizationPipeline))]
public IActionResult CultureFromRouteData()
{
return Content($"CurrentCulture:{CultureInfo.CurrentCulture.Name},"
+ $"CurrentUICulture:{CultureInfo.CurrentUICulture.Name}");
}
Filtros de middleware são executados no mesmo estágio do pipeline de filtros que filtros de recurso, antes
do model binding e depois do restante do pipeline.
Próximas ações
Para fazer experiências com filtros, baixe, teste e modifique o exemplo.
Por Dhananjay Kumar e Rick Anderson

Áreas são um recurso do ASP.NET MVC usado para organizar funcionalidades relacionadas em um grupo
como um namespace separado (para roteamento) e uma estrutura de pastas (para exibições). O uso de áreas
cria uma hierarquia para fins de roteamento, adicionando outro parâmetro de rota, area , a controller e
action .
As áreas fornecem uma maneira de particionar um aplicativo Web ASP.NET Core MVC grande em
agrupamentos funcionais menores. Uma área é efetivamente uma estrutura MVC dentro de um aplicativo. Em
um projeto MVC, componentes lógicos como Modelo, Controlador e Exibição são mantidos em pastas
diferentes e o MVC usa convenções de nomenclatura para criar a relação entre esses componentes. Para um
aplicativo grande, pode ser vantajoso particionar o aplicativo em áreas de nível alto separadas de
funcionalidade. Por exemplo, um aplicativo de comércio eletrônico com várias unidades de negócios, como
check-out, cobrança e pesquisa, etc. Cada uma dessas unidades têm suas próprias exibições de componente
lógico, controladores e modelos. Nesse cenário, você pode usar Áreas para particionar fisicamente os
componentes de negócios no mesmo projeto.
Uma área pode ser definida como as menores unidades funcionais em um projeto do ASP.NET Core MVC com
seu próprio conjunto de controladores, exibições e modelos.
Considere o uso de Áreas em um projeto MVC quando:
O aplicativo é composto por vários componentes funcionais de alto nível que devem ser separados
logicamente
Você deseja particionar o projeto MVC para que cada área funcional possa ser trabalhada de forma
independente
Recursos de área:
Um aplicativo ASP.NET Core MVC pode ter qualquer quantidade de áreas.
Cada área tem seus próprios controladores, modelos e exibições.
As áreas permitem organizar projetos MVC grandes em vários componentes de alto nível que podem ser
trabalhados de forma independente.
As áreas dão suporte a vários controladores com o mesmo nome, desde que eles tenham áreas
diferentes.
Vamos dar uma olhada em um exemplo para ilustrar como as Áreas são criadas e usadas. Digamos que você
tenha um aplicativo de loja que tem dois agrupamentos distintos de controladores e exibições: Produtos e
Serviços. Uma estrutura de pastas comum para isso usando áreas do MVC tem a aparência mostrada abaixo:
Nome do projeto
Áreas
Produtos
Controladores
HomeController.cs
ManageController.cs
Exibições
Home
Index.cshtml
Gerenciar
Index.cshtml
Serviços
Controladores
HomeController.cs
Exibições
Home
Index.cshtml
Quando o MVC tenta renderizar uma exibição em uma Área, por padrão, ele tenta procurar nos seguintes
locais:
/Areas/<Area-Name>/Views/<Controller-Name>/<Action-Name>.cshtml
/Areas/<Area-Name>/Views/Shared/<Action-Name>.cshtml
/Views/Shared/<Action-Name>.cshtml
Esses são os locais padrão que podem ser alterados por meio do AreaViewLocationFormats no
Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions .
Por exemplo, no código abaixo, em vez de ter o nome da pasta como 'Areas', ele foi alterado para 'Categories'.
services.Configure<RazorViewEngineOptions>(options =>
{
options.AreaViewLocationFormats.Clear();
options.AreaViewLocationFormats.Add("/Categories/{2}/Views/{1}/{0}.cshtml");
options.AreaViewLocationFormats.Add("/Categories/{2}/Views/Shared/{0}.cshtml");
options.AreaViewLocationFormats.Add("/Views/Shared/{0}.cshtml");
});
Uma coisa importante a ser observada é que a estrutura da pasta Views é a única que é considerada importante
aqui e, o conteúdo do restante das pastas como Controllers e Models não importa. Por exemplo, você não
precisa ter uma pasta Controllers e Models. Isso funciona porque o conteúdo de Controllers e Models é apenas
um código que é compilado em uma .dll, enquanto o conteúdo de Views não é, até que uma solicitação para
essa exibição seja feita.
Depois de definir a hierarquia de pastas, você precisa informar ao MVC que cada controlador está associado a
uma área. Faça isso decorando o nome do controlador com o atributo [Area] .
...
namespace MyStore.Areas.Products.Controllers
{
[Area("Products")]
{
// GET: /Products/Home/Index
{
return View();
}
// GET: /Products/Home/Create
{
return View();
}
}
}
Configure uma definição de rota que funciona com as áreas recém-criadas. O artigo Rota para ações do
controlador apresenta detalhes de como criar definições de rota, incluindo o uso de rotas convencionais versus
rotas de atributo. Neste exemplo, usaremos uma rota convencional. Para fazer isso, abra o arquivo Startup.cs e
modifique-o adicionando a definição de rota nomeada areaRoute abaixo.
...
{
routes.MapRoute(
name: "areaRoute",
template: "{area:exists}/{controller=Home}/{action=Index}/{id?}");
routes.MapRoute(
name: "default",
});
Navegando para http://<yourApp>/products , o método de ação Index do HomeController na área Products

será invocado.
Geração de link
Geração de links em uma ação dentro de um controlador baseado em área para outra ação no mesmo
controlador.
Digamos que o caminho da solicitação atual seja semelhante a /Products/Home/Create
Sintaxe de HtmlHelper: @Html.ActionLink("Go to Product's Home Page", "Index")
Sintaxe de TagHelper: <a asp-action="Index">Go to Product's Home Page</a>
Observe que não é necessário fornecer os valores 'area' e 'controller' aqui, pois já estão disponíveis no
contexto da solicitação atual. Esses tipos de valores são chamados valores ambient .
Geração de links em uma ação dentro de um controlador baseado em área para outra ação em outro
controlador
Sintaxe de HtmlHelper: @Html.ActionLink("Go to Manage Products Home Page", "Index", "Manage")

Sintaxe de TagHelper:
<a asp-controller="Manage" asp-action="Index">Go to Manage Products Home Page</a>
Observe que aqui o valor de ambiente de uma "area" é usado, mas o valor de 'controller' é especificado
de forma explícita acima.
controlador e outra área.
Sintaxe de HtmlHelper:
@Html.ActionLink("Go to Services Home Page", "Index", "Home", new { area = "Services" })
<a asp-area="Services" asp-controller="Home" asp-action="Index">Go to Services Home Page</a>
Observe que aqui nenhum valor de ambiente é usado.

controlador e não em uma área.
Sintaxe de HtmlHelper:
@Html.ActionLink("Go to Manage Products Home Page", "Index", "Home", new { area = "" })
<a asp-area="" asp-controller="Manage" asp-action="Index">Go to Manage Products Home Page</a>
Como queremos gerar links para uma ação do controlador não baseada em área, esvaziamos o valor de
ambiente para 'area' aqui.
Publicando áreas
Todos os arquivos *.cshtml e wwwroot/** são publicados na saída quando
<Project Sdk="Microsoft.NET.Sdk.Web"> é incluído no arquivo .csproj.
Partes do aplicativo no ASP.NET Core

Uma Parte do aplicativo é uma abstração dos recursos de um aplicativo, da qual recursos de MVC como
controladores, componentes de exibição ou auxiliares de marca podem ser descobertos. Um exemplo de uma parte
do aplicativo é um AssemblyPart, que encapsula uma referência de assembly e expõe tipos e referências de
compilação. Provedores de recursos funcionam com as partes do aplicativo para preencher os recursos de um
aplicativo do ASP.NET Core MVC. O caso de uso principal das partes do aplicativo é permitir que você configure
seu aplicativo para descobrir (ou evitar o carregamento) recursos de MVC de um assembly.
Introdução às partes do aplicativo

Aplicativos de MVC carregam seus recursos das partes do aplicativo. Em particular, a classe AssemblyPart
representa uma parte de aplicativo que é apoiada por um assembly. Você pode usar essas classes para descobrir e
carregar recursos de MVC, como controladores, componentes de exibição, auxiliares de marca e fontes de
compilação do Razor. O ApplicationPartManager é responsável por controlar as partes do aplicativo e os
provedores de recursos disponíveis para o aplicativo MVC. Você pode interagir com o ApplicationPartManager em
Startup quando configura o MVC:
// create an assembly part from a class's assembly

var assembly = typeof(Startup).GetTypeInfo().Assembly;
services.AddMvc()
.AddApplicationPart(assembly);
// OR
var assembly = typeof(Startup).GetTypeInfo().Assembly;
var part = new AssemblyPart(assembly);
services.AddMvc()
.ConfigureApplicationPartManager(apm => apm.ApplicationParts.Add(part));
Por padrão, o MVC pesquisa a árvore de dependência e localiza controladores (mesmo em outros assemblies).
Para carregar um assembly arbitrário (por exemplo, de um plug-in que não é referenciado em tempo de
compilação), você pode usar uma parte do aplicativo.
Você pode usar as partes do aplicativo para evitar pesquisar controladores em um determinado assembly ou local.
Você pode controlar quais partes (ou assemblies) ficam disponíveis para o aplicativo modificando a coleção
ApplicationParts do ApplicationPartManager . A ordem das entradas na coleção ApplicationParts não é
importante. É importante configurar totalmente o ApplicationPartManager antes de usá-lo para configurar serviços
no contêiner. Por exemplo, você deve configurar totalmente o ApplicationPartManager antes de invocar
AddControllersAsServices . Se isso não for feito, os controladores em partes do aplicativo adicionadas depois da
chamada de método não serão afetados (não serão registrados como serviços), o que poderá resultar em um
comportamento incorreto do aplicativo.
Se tiver um assembly que contém controladores que você não deseja usar, remova-o do ApplicationPartManager :
services.AddMvc()
.ConfigureApplicationPartManager(apm =>
{
var dependentLibrary = apm.ApplicationParts
.FirstOrDefault(part => part.Name == "DependentLibrary");
if (dependentLibrary != null)
{
apm.ApplicationParts.Remove(dependentLibrary);
}
})
Além do assembly de seu projeto e de seus assemblies dependentes, o ApplicationPartManager incluirá partes para
Microsoft.AspNetCore.Mvc.TagHelpers e Microsoft.AspNetCore.Mvc.Razor por padrão.
Provedores de recursos do aplicativo

Os Provedores de recursos do aplicativo examinam as partes do aplicativo e fornece recursos para essas partes. Há
provedores de recursos internos para os seguintes recursos de MVC:
Controladores
Referência de metadados
Provedores de recursos herdam de IApplicationFeatureProvider<T> , em que T é o tipo do recurso. Você pode
implementar seus próprios provedores de recursos para qualquer um dos tipos de recurso do MVC listados acima.
A ordem dos provedores de recursos na coleção ApplicationPartManager.FeatureProviders pode ser importante,
pois provedores posteriores podem reagir às ações tomadas por provedores anteriores.
Exemplo: recurso de controlador genérico
Por padrão, o ASP.NET Core MVC ignora controladores genéricos (por exemplo, SomeController<T> ). Este
exemplo usa um provedor de recursos de controlador que é executado depois do provedor padrão e adiciona
instâncias de controlador genérico a uma lista de tipos especificados (definidos em EntityTypes.Types ):
public class GenericControllerFeatureProvider : IApplicationFeatureProvider<ControllerFeature>

{
public void PopulateFeature(IEnumerable<ApplicationPart> parts, ControllerFeature feature)
{
// This is designed to run after the default ControllerTypeProvider,
// so the list of 'real' controllers has already been populated.
foreach (var entityType in EntityTypes.Types)
{
var typeName = entityType.Name + "Controller";
if (!feature.Controllers.Any(t => t.Name == typeName))
{
// There's no 'real' controller for this entity, so add the generic version.
var controllerType = typeof(GenericController<>)
.MakeGenericType(entityType.AsType()).GetTypeInfo();
feature.Controllers.Add(controllerType);
}
}
}
}
Os tipos de entidade:
public static class EntityTypes
{
public static IReadOnlyList<TypeInfo> Types => new List<TypeInfo>()
{
typeof(Sprocket).GetTypeInfo(),
typeof(Widget).GetTypeInfo(),
};
public class Sprocket { }

public class Widget { }
}
O provedor de recursos é adicionado em Startup :
services.AddMvc()
.ConfigureApplicationPartManager(apm =>
apm.FeatureProviders.Add(new GenericControllerFeatureProvider()));
Por padrão, os nomes do controlador genérico usados para roteamento seriam no formato GenericController'1
[Widget] em vez de Widget. O atributo a seguir é usado para modificar o nome para que ele corresponda ao tipo
genérico usado pelo controlador:
using System;
namespace AppPartsSample
{
// Used to set the controller name for routing purposes. Without this convention the
// names would be like 'GenericController`1[Widget]' instead of 'Widget'.
//
// Conventions can be applied as attributes or added to MvcOptions.Conventions.
[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = true)]
public class GenericControllerNameConvention : Attribute, IControllerModelConvention
{
public void Apply(ControllerModel controller)
{
if (controller.ControllerType.GetGenericTypeDefinition() !=
typeof(GenericController<>))
{
// Not a GenericController, ignore.
return;
}
var entityType = controller.ControllerType.GenericTypeArguments[0];

controller.ControllerName = entityType.Name;
}
}
}
A classe GenericController :
namespace AppPartsSample
{
[GenericControllerNameConvention] // Sets the controller name based on typeof(T).Name
public class GenericController<T> : Controller
{
{
return Content($"Hello from a generic {typeof(T).Name} controller.");
}
}
}
O resultado, quando uma rota correspondente é solicitada:
Exemplo: exibir recursos disponíveis

Você pode iterar nos recursos preenchidos disponíveis para seu aplicativo solicitando um ApplicationPartManager
por meio da injeção de dependência e usando-o para preencher as instâncias dos recursos apropriados:
using AppPartsSample.ViewModels;
using Microsoft.AspNetCore.Mvc.ApplicationParts;
using Microsoft.AspNetCore.Mvc.Controllers;
using System.Linq;
using Microsoft.AspNetCore.Mvc.Razor.Compilation;
using Microsoft.AspNetCore.Mvc.ViewComponents;
namespace AppPartsSample.Controllers
{
public class FeaturesController : Controller
{
private readonly ApplicationPartManager _partManager;
public FeaturesController(ApplicationPartManager partManager)

{
_partManager = partManager;
}

{
var viewModel = new FeaturesViewModel();
var controllerFeature = new ControllerFeature();

_partManager.PopulateFeature(controllerFeature);
viewModel.Controllers = controllerFeature.Controllers.ToList();
var metaDataReferenceFeature = new MetadataReferenceFeature();

_partManager.PopulateFeature(metaDataReferenceFeature);
viewModel.MetadataReferences = metaDataReferenceFeature.MetadataReferences
.ToList();
var tagHelperFeature = new TagHelperFeature();

_partManager.PopulateFeature(tagHelperFeature);
viewModel.TagHelpers = tagHelperFeature.TagHelpers.ToList();
var viewComponentFeature = new ViewComponentFeature();

_partManager.PopulateFeature(viewComponentFeature);
viewModel.ViewComponents = viewComponentFeature.ViewComponents.ToList();
}
}
}
Saída de exemplo:
Model binding personalizado no ASP.NET Core
Por Steve Smith

O model binding permite que as ações do controlador funcionem diretamente com tipos de modelo (passados
como argumentos de método), em vez de solicitações HTTP. O mapeamento entre os dados de solicitação de
entrada e os modelos de aplicativo é manipulado por associadores de modelos. Os desenvolvedores podem
estender a funcionalidade de model binding interna implementando associadores de modelos personalizados
(embora, normalmente, você não precise escrever seu próprio provedor).
Exibir ou baixar a amostra do GitHub
Limitações dos associadores de modelos padrão

Os associadores de modelos padrão dão suporte à maioria dos tipos de dados comuns do .NET Core e devem
atender à maior parte das necessidades dos desenvolvedores. Eles esperam associar a entrada baseada em texto
da solicitação diretamente a tipos de modelo. Talvez seja necessário transformar a entrada antes de associá-la. Por
exemplo, quando você tem uma chave que pode ser usada para pesquisar dados de modelo. Use um associador
de modelos personalizado para buscar dados com base na chave.
Análise do model binding

O model binding usa definições específicas para os tipos nos quais opera. Um tipo simples é convertido de uma
única cadeia de caracteres na entrada. Um tipo complexo é convertido de vários valores de entrada. A estrutura
determina a diferença de acordo com a existência de um TypeConverter . Recomendamos que você crie um
conversor de tipo se tiver um mapeamento string -> SomeType simples que não exige recursos externos.
Antes de criar seu próprio associador de modelos personalizado, vale a pena analisar como os associadores de
modelos existentes são implementados. Considere o ByteArrayModelBinder, que pode ser usado para converter
cadeias de caracteres codificadas em Base64 em matrizes de bytes. As matrizes de bytes costumam ser
armazenadas como arquivos ou campos BLOB do banco de dados.
Trabalhando com o ByteArrayModelBinder
Cadeias de caracteres codificadas em Base64 podem ser usadas para representar dados binários. Por exemplo, a
imagem a seguir pode ser codificada como uma cadeia de caracteres.
Uma pequena parte da cadeia de caracteres codificada é mostrada na seguinte imagem:

Siga as instruções do LEIAME da amostra para converter a cadeia de caracteres codificada em Base64 em um
arquivo.
O ASP.NET Core MVC pode usar uma cadeia de caracteres codificada em Base64 e usar um
ByteArrayModelBinder para convertê-la em uma matriz de bytes. O ByteArrayModelBinderProvider que
implementa IModelBinderProvider mapeia argumentos byte[] para ByteArrayModelBinder :
public IModelBinder GetBinder(ModelBinderProviderContext context)

{
{
}
if (context.Metadata.ModelType == typeof(byte[]))
{
return new ByteArrayModelBinder();
}
return null;
}
Ao criar seu próprio associador de modelos personalizado, você pode implementar seu próprio tipo
IModelBinderProvider ou usar o ModelBinderAttribute.
O seguinte exemplo mostra como usar ByteArrayModelBinder para converter uma cadeia de caracteres codificada
em Base64 em um byte[] e salvar o resultado em um arquivo:
// POST: api/image
[HttpPost]
public void Post(byte[] file, string filename)
{
string filePath = Path.Combine(_env.ContentRootPath, "wwwroot/images/upload", filename);
if (System.IO.File.Exists(filePath)) return;
System.IO.File.WriteAllBytes(filePath, file);
}
Execute POST em uma cadeia de caracteres codificada em Base64 para esse método de API usando uma
ferramenta como o Postman:
Desde que o associador possa associar dados de solicitação a propriedades ou argumentos nomeados de forma
adequada, o model binding terá êxito. O seguinte exemplo mostra como usar ByteArrayModelBinder com um
modelo de exibição:
[HttpPost("Profile")]
public void SaveProfile(ProfileViewModel model)
{
string filePath = Path.Combine(_env.ContentRootPath, "wwwroot/images/upload", model.FileName);
if (System.IO.File.Exists(model.FileName)) return;
System.IO.File.WriteAllBytes(filePath, model.File);
}
public class ProfileViewModel

{
public byte[] File { get; set; }
public string FileName { get; set; }
}
Amostra de associador de modelos personalizado

Nesta seção, implementaremos um associador de modelos personalizado que:
Converte dados de solicitação de entrada em argumentos de chave fortemente tipados.
Usa o Entity Framework Core para buscar a entidade associada.
Passa a entidade associada como um argumento para o método de ação.
A seguinte amostra usa o atributo ModelBinder no modelo Author :
using CustomModelBindingSample.Binders;
using System;
using System.Linq;
namespace CustomModelBindingSample.Data
{
[ModelBinder(BinderType = typeof(AuthorEntityBinder))]
public class Author
{
public string GitHub { get; set; }
public string Twitter { get; set; }
public string BlogUrl { get; set; }
}
}
No código anterior, o atributo ModelBinder especifica o tipo de IModelBinder que deve ser usado para associar
parâmetros de ação Author .
O AuthorEntityBinder é usado para associar um parâmetro Author buscando a entidade de uma fonte de dados
usando o Entity Framework Core e uma authorId :
public class AuthorEntityBinder : IModelBinder
{
public AuthorEntityBinder(AppDbContext db)
{
_db = db;
}
public Task BindModelAsync(ModelBindingContext bindingContext)

{
if (bindingContext == null)
{
throw new ArgumentNullException(nameof(bindingContext));
}
// Specify a default argument name if none is set by ModelBinderAttribute

var modelName = bindingContext.BinderModelName;
if (string.IsNullOrEmpty(modelName))
{
modelName = "authorId";
}
// Try to fetch the value of the argument by name

var valueProviderResult =
bindingContext.ValueProvider.GetValue(modelName);
if (valueProviderResult == ValueProviderResult.None)
{
}
bindingContext.ModelState.SetModelValue(modelName,
valueProviderResult);
var value = valueProviderResult.FirstValue;
// Check if the argument value is null or empty

if (string.IsNullOrEmpty(value))
{
}
int id = 0;
if (!int.TryParse(value, out id))
{
// Non-integer arguments result in model state errors
bindingContext.ModelState.TryAddModelError(
bindingContext.ModelName,
"Author Id must be an integer.");
}
// Model will be null if not found, including for

// out of range id values (0, -3, etc.)
var model = _db.Authors.Find(id);
bindingContext.Result = ModelBindingResult.Success(model);
}
}
O seguinte código mostra como usar o AuthorEntityBinder em um método de ação:

[HttpGet("get/{authorId}")]
public IActionResult Get(Author author)
{
return Ok(author);
}
O atributo ModelBinder pode ser usado para aplicar o AuthorEntityBinder aos parâmetros que não usam
convenções padrão:
[HttpGet("{id}")]
public IActionResult GetById([ModelBinder(Name = "id")]Author author)
{
if (author == null)
{
return NotFound();
}
{
}
return Ok(author);
}
Neste exemplo, como o nome do argumento não é o authorId padrão, ele é especificado no parâmetro com o
atributo ModelBinder . Observe que o controlador e o método de ação são simplificados, comparado à pesquisa da
entidade no método de ação. A lógica para buscar o autor usando o Entity Framework Core é movida para o
associador de modelos. Isso pode ser uma simplificação considerável quando há vários métodos associados ao
modelo Author e pode ajudá-lo a seguir o princípio DRY.
Aplique o atributo ModelBinder a propriedades de modelo individuais (como em um viewmodel) ou a parâmetros
de método de ação para especificar um associador de modelos ou nome de modelo específico para apenas esse
tipo ou essa ação.
Implementando um ModelBinderProvider
Em vez de aplicar um atributo, você pode implementar IModelBinderProvider . É assim que os associadores de
estrutura interna são implementados. Quando você especifica o tipo no qual o associador opera, você especifica o
tipo de argumento que ele produz, não a entrada aceita pelo associador. O provedor de associador a seguir
funciona com o AuthorEntityBinder . Quando ele é adicionado à coleção do MVC de provedores, você não precisa
usar o atributo ModelBinder em Author ou parâmetros tipados Author .
using CustomModelBindingSample.Data;
using Microsoft.AspNetCore.Mvc.ModelBinding.Binders;
using System;
namespace CustomModelBindingSample.Binders
{
public class AuthorEntityBinderProvider : IModelBinderProvider
{
public IModelBinder GetBinder(ModelBinderProviderContext context)
{
{
}
if (context.Metadata.ModelType == typeof(Author))
{
return new BinderTypeModelBinder(typeof(AuthorEntityBinder));
}
return null;
}
}
}
Observação: o código anterior retorna um BinderTypeModelBinder . O BinderTypeModelBinder atua como um

alocador para associadores de modelos e fornece a DI (injeção de dependência). O AuthorEntityBinder exige
que a DI acesse o EF Core. Use BinderTypeModelBinder se o associador de modelos exigir serviços da DI.
Para usar um provedor de associador de modelos personalizado, adicione-o a ConfigureServices :

{
services.AddDbContext<AppDbContext>(options => options.UseInMemoryDatabase());
{
// add custom binder to beginning of collection
options.ModelBinderProviders.Insert(0, new AuthorEntityBinderProvider());
});
}
Ao avaliar associadores de modelos, a coleção de provedores é examinada na ordem. O primeiro provedor que
retorna um associador é usado.
A imagem a seguir mostra os associadores de modelos padrão do depurador.
A adição do provedor ao final da coleção pode resultar na chamada a um associador de modelos interno antes que
o associador personalizado tenha uma oportunidade. Neste exemplo, o provedor personalizado é adicionado ao
início da coleção para garantir que ele é usado para argumentos de ação Author .

{
services.AddDbContext<AppDbContext>(options => options.UseInMemoryDatabase());
{
// add custom binder to beginning of collection
options.ModelBinderProviders.Insert(0, new AuthorEntityBinderProvider());
});
}
Recomendações e melhores práticas

Associadores de modelos personalizados:
Não devem tentar definir códigos de status ou retornar resultados (por exemplo, 404 Não Encontrado). Se o
model binding falhar, um filtro de ação ou uma lógica no próprio método de ação deverá resolver a falha.
São muito úteis para eliminar código repetitivo e interesses paralelos de métodos de ação.
Normalmente, não devem ser usados para converter uma cadeia de caracteres em um tipo personalizado; um
TypeConverter geralmente é uma opção melhor.
Versão de compatibilidade do ASP.NET Core MVC
Por Rick Anderson

O método SetCompatibilityVersion permite que um aplicativo aceite ou recuse as possíveis alterações da falha
de comportamento introduzidas no ASP.NET Core MVC 2.1 ou posteriores. Essas possíveis alterações da falha
de comportamento geralmente afetam como o subsistema MVC se comporta e como o código do usuário é
chamado pelo tempo de execução. Ao aceitar, você obtém o comportamento mais recente e o comportamento
de longo prazo do ASP.NET Core.
O código a seguir define o modo de compatibilidade para o ASP.NET Core 2.1:

{
services.AddMvc()
}
É recomendável que você teste seu aplicativo usando a versão mais recente ( CompatibilityVersion.Version_2_1 ).
Estimamos que a maioria dos aplicativos não terão alterações da falha de comportamento usando a versão mais
recente.
Os aplicativos que chamam SetCompatibilityVersion(CompatibilityVersion.Version_2_0) são protegidos contra as
possíveis alterações da falha de comportamento apresentadas no ASP.NET Core 2.1 MVC e nas versões 2.x
posteriores. Essa proteção:
Não se aplica a todas as alterações da 2.1 e posteriores, ela é direcionada às possíveis alterações da falha de
comportamento do tempo de execução do ASP.NET Core no subsistema de MVC.
Não se estende à próxima versão principal.
A compatibilidade padrão para aplicativos ASP.NET Core 2.1 e 2.x posteriores que não é chamada é a
SetCompatibilityVersion compatibilidade 2.0. Ou seja, não chamar SetCompatibilityVersion é o mesmo que
chamar SetCompatibilityVersion(CompatibilityVersion.Version_2_0) .
O código a seguir define o modo de compatibilidade para o ASP.NET Core 2.1, exceto para os seguintes
comportamentos:
AllowCombiningAuthorizeFilters
InputFormatterExceptionPolicy
{
services.AddMvc()
// Include the 2.1 behaviors
// Except for the following.
.AddMvcOptions(options =>
{
// Don't combine authorize filters (keep 2.0 behavior).
options.AllowCombiningAuthorizeFilters = false;
// All exceptions thrown by an IInputFormatter are treated
// as model state errors (keep 2.0 behavior).
options.InputFormatterExceptionPolicy =
InputFormatterExceptionPolicy.AllExceptions;
});
}
Para aplicativos que encontram alterações da falha de comportamento, o uso das opções de compatibilidade
apropriadas:
Permite que você use a versão mais recente e recuse alterações da falha de comportamento específicas.
Tenha tempo para atualizar seu aplicativo para que ele funcione com as alterações mais recentes.
Os comentários do código-fonte da classe MvcOptions têm uma boa explicação sobre o que mudou e por que as
alterações são uma melhoria para a maioria dos usuários.
Futuramente, haverá uma versão 3.0 do ASP.NET Core. Os comportamentos antigos compatíveis por meio de
opções de compatibilidade serão removidos na versão 3.0. Consideramos que essas são alterações positivas que
beneficiam quase todos os usuários. Com a introdução dessas alterações, a maioria dos aplicativos poderá se
beneficiar agora e os demais terão tempo para serem atualizados.
Por Scott Addie

Este documento explica como criar uma API Web no ASP.NET Core e quando é mais adequado usar cada
recurso.
Derivar a classe por meio do ControllerBase

Herde da classe ControllerBase em um controlador destinado a funcionar como uma API Web. Por exemplo:
[Produces("application/json")]
public class PetsController : ControllerBase
{
private readonly PetsRepository _repository;
public PetsController(PetsRepository repository)

{
_repository = repository;
}
[HttpGet]
public async Task<ActionResult<List<Pet>>> GetAllAsync()
{
return await _repository.GetPetsAsync();
}
[HttpGet("{id}")]
public async Task<ActionResult<Pet>> GetByIdAsync(int id)
{
var pet = await _repository.GetPetAsync(id);
if (pet == null)
{
return NotFound();
}
return pet;
}
[HttpPost]
public async Task<ActionResult<Pet>> CreateAsync(Pet pet)
{
{
}
await _repository.AddPetAsync(pet);
return CreatedAtAction(nameof(GetByIdAsync),
new { id = pet.Id }, pet);
}
}
public class PetsController : ControllerBase
{
private readonly PetsRepository _repository;
public PetsController(PetsRepository repository)

{
}
[HttpGet]
[ProducesResponseType(typeof(IEnumerable<Pet>), 200)]
public async Task<IActionResult> GetAllAsync()
{
var pets = await _repository.GetPetsAsync();
return Ok(pets);
}
[HttpGet("{id}")]
[ProducesResponseType(typeof(Pet), 200)]
public async Task<IActionResult> GetByIdAsync(int id)
{
var pet = await _repository.GetPetAsync(id);
if (pet == null)
{
return NotFound();
}
return Ok(pet);
}
[HttpPost]
[ProducesResponseType(typeof(Pet), 201)]
public async Task<IActionResult> CreateAsync([FromBody] Pet pet)
{
{
}
await _repository.AddPetAsync(pet);
return CreatedAtAction(nameof(GetByIdAsync),
new { id = pet.Id }, pet);
}
}
A classe ControllerBase fornece acesso a várias propriedades e métodos. No código anterior, os exemplos
incluem BadRequest(ModelStateDictionary) e CreatedAtAction(String, Object, Object). Esses métodos são
chamados em métodos de ação para retornar os códigos de status HTTP 400 e 201, respectivamente. A
propriedade ModelState, também fornecida pelo ControllerBase , é acessada para executar a validação do
modelo de solicitação.
Anotação com o ApiControllerAttribute

O ASP.NET Core 2.1 apresenta o atributo [ApiController] para denotar uma classe do controlador API Web. Por
exemplo:
[ApiController]
public class ProductsController : ControllerBase
Uma versão de compatibilidade do 2.1 ou posterior, definida por meio de SetCompatibilityVersion, é necessária
para usar esse atributo no nível do controlador. Por exemplo, o código realçado em Startup.ConfigureServices
define o sinalizador de compatibilidade 2.1:
services.AddMvc()
No ASP.NET Core 2.2 ou posterior, o atributo [ApiController] pode ser aplicado a um assembly. A anotação
dessa maneira aplica o comportamento da API Web para todos os controladores no assembly. Lembre-se de que
não é possível recusar controladores individuais. Como uma recomendação, os atributos de nível de assembly
devem ser aplicados à classe Startup :
[assembly: ApiController]
namespace WebApiSample.Api._22
{
{
Uma versão de compatibilidade do 2.2 ou posterior, definida por meio de SetCompatibilityVersion, é necessária
para usar esse atributo no nível do assembly.
Geralmente, o atributo [ApiController] é associado ao ControllerBase para habilitar o comportamento
específico de REST para controladores. ControllerBase fornece acesso a métodos como NotFound e File.
Outra abordagem é criar uma classe de base de controlador personalizada anotada com o atributo
[ApiController] :
[ApiController]
public class MyBaseController
{
}
As seções a seguir descrevem os recursos de conveniência adicionados pelo atributo.

Respostas automáticas do HTTP 400
Os erros de validação disparam uma resposta HTTP 400 automaticamente. O código a seguir se torna
desnecessário em suas ações:
{
}
Use InvalidModelStateResponseFactory para personalizar a saída da resposta resultante.

O comportamento padrão é desabilitado quando a propriedade SuppressModelStateInvalidFilter está definida
como true . Adicione o seguinte código em Startup.ConfigureServices após
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_<version_number>); :
services.AddMvc()
.ConfigureApiBehaviorOptions(options =>
{
options.SuppressConsumesConstraintForFormFileParameters = true;
options.SuppressInferBindingSourcesForParameters = true;
options.SuppressModelStateInvalidFilter = true;
options.SuppressMapClientErrors = true;
options.ClientErrorMapping[404].Link =
"https://httpstatuses.com/404";
});
services.Configure<ApiBehaviorOptions>(options =>
{
});
Com um sinalizador de compatibilidade do 2.2 ou posterior, o tipo de resposta padrão para respostas HTTP 400 é
ValidationProblemDetails. O tipo ValidationProblemDetails está em conformidade com a especificação RFC
7807. Defina a propriedade SuppressUseValidationProblemDetailsForInvalidModelStateResponses como true para
retornar o formato de erro do ASP.NET Core 2.1 de SerializableError. Adicione o seguinte código em
services.AddMvc()
{
options
.SuppressUseValidationProblemDetailsForInvalidModelStateResponses = true;
});
Inferência de parâmetro de origem de associação

Um atributo de origem de associação define o local no qual o valor do parâmetro de uma ação é encontrado. Os
seguintes atributos da origem da associação existem:
ATRIBUTO FONTE DE ASSOCIAÇÃO
[FromBody] Corpo da solicitação
[FromForm] Dados do formulário no corpo da solicitação
[FromHeader] Cabeçalho da solicitação
[FromQuery] Parâmetro de cadeia de caracteres de consulta de solicitação
[FromRoute] Dados de rota da solicitação atual
[FromServices] O serviço de solicitação inserido como um parâmetro de ação

WARNING
Não use [FromRoute] quando os valores puderem conter %2f (ou seja, / ). %2f não ficará sem escape para / . Use
[FromQuery] , se o valor puder conter %2f .
Sem o atributo [ApiController] , os atributos da origem da associação são definidos explicitamente. No exemplo
a seguir, o atributo [FromQuery] indica que o valor do parâmetro discontinuedOnly é fornecido na cadeia de
caracteres de consulta da URL de solicitação:
[HttpGet]
public async Task<ActionResult<List<Product>>> GetAsync(
[FromQuery] bool discontinuedOnly = false)
{
List<Product> products = null;
if (discontinuedOnly)
{
products = await _repository.GetDiscontinuedProductsAsync();
}
else
{
products = await _repository.GetProductsAsync();
}
return products;
}
Regras de inferência são aplicadas para as fontes de dados padrão dos parâmetros de ação. Essas regras
configuram as origens da associação que você provavelmente aplicaria manualmente aos parâmetros de ação. Os
atributos da origem da associação se comportam da seguinte maneira:
[FromBody] é inferido para parâmetros de tipo complexo. Uma exceção a essa regra é qualquer tipo interno
complexo com um significado especial, como IFormCollection e CancellationToken. O código de inferência da
origem da associação ignora esses tipos especiais. [FromBody] não é inferido para tipos simples, como
string ou int . Portanto, o atributo [FromBody] deve ser usado para tipos simples quando essa
funcionalidade for necessária. Quando uma ação tiver mais de um parâmetro especificado explicitamente (via
[FromBody] ) ou inferido como limite do corpo da solicitação, uma exceção será lançada. Por exemplo, as
seguintes assinaturas de ação causam uma exceção:
// Don't do this. All of the following actions result in an exception.

[HttpPost]
public IActionResult Action1(Product product,
Order order) => null;
[HttpPost]
public IActionResult Action2(Product product,
[FromBody] Order order) => null;
[HttpPost]
public IActionResult Action3([FromBody] Product product,
[FromBody] Order order) => null;
[FromForm ] é inferido para parâmetros de ação do tipo IFormFile e IFormFileCollection. Ele não é inferido
para qualquer tipo simples ou definido pelo usuário.
[FromRoute] é inferido para qualquer nome de parâmetro de ação correspondente a um parâmetro no
modelo de rota. Quando mais de uma rota correspondem a um parâmetro de ação, qualquer valor de rota é
considerado [FromRoute] .
[FromQuery] é inferido para todos os outros parâmetros de ação.
As regras de inferência padrão são desabilitadas quando a propriedade

SuppressInferBindingSourcesForParameters está definida como true . Adicione o seguinte código em
Startup.ConfigureServices após
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_<version_number>); :
services.AddMvc()
{
});
{
});
Inferência de solicitação de várias partes/dados de formulário

Quando um parâmetro de ação é anotado com o atributo [FromForm], o tipo de conteúdo de solicitação
multipart/form-data é inferido.
O comportamento padrão é desabilitado quando a propriedade

SuppressConsumesConstraintForFormFileParameters está definida como true .
Adicione o seguinte código em Startup.ConfigureServices :
services.AddMvc()
{
});
Adicione o seguinte código em Startup.ConfigureServices após

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1); :
{
});
Requisito de roteamento de atributo
O roteamento de atributo se torna um requisito. Por exemplo:
[ApiController]
As ações são inacessíveis por meio de rotas convencionais definidas em UseMvc ou por
UseMvcWithDefaultRoute em Startup.Configure .
Respostas de detalhes de problema para códigos de status de erro
No ASP.NET Core 2.2 ou posterior, o MVC transforma um resultado de erro (um resultado com o código de
status 400 ou superior) em um resultado com ProblemDetails. ProblemDetails é:
Um tipo baseado na especificação RFC 7807.
Um formato padronizado para especificar detalhes do erro legível por computador em uma resposta HTTP.
Considere o seguinte código em uma ação do controlador:
if (product == null)
{
return NotFound();
}
A resposta HTTP para NotFound tem um código de status 404 com um corpo ProblemDetails . Por exemplo:
{
type: "https://tools.ietf.org/html/rfc7231#section-6.5.4",
title: "Not Found",
status: 404,
traceId: "0HLHLV31KRN83:00000001"
}
O recurso de detalhes do problema requer um sinalizador de compatibilidade de 2.2 ou posterior. O

comportamento padrão é desabilitado quando a propriedade SuppressMapClientErrors está definida como true .
Adicione o seguinte código em Startup.ConfigureServices :
services.AddMvc()
{
});
Use a propriedade ClientErrorMapping para configurar o conteúdo da resposta ProblemDetails . Por exemplo, o
código a seguir atualiza a propriedade type para respostas 404:
services.AddMvc()
{
});
Recursos adicionais
Tipos de retorno de ação do controlador na API Web ASP.NET Core
Formatadores personalizados na API Web ASP.NET Core
Formatar dados de resposta na API Web ASP.NET Core
Páginas de ajuda da API Web ASP.NET Core com o Swagger/OpenAPI
Roteamento para ações do controlador no ASP.NET Core
Studio

Este tutorial compilará uma API Web para gerenciar uma lista de itens de “tarefas pendentes”. Uma interface
do usuário (UI) não será criada.
Windows: API Web com o Visual Studio para Windows (este tutorial)
Visão geral

PUT /api/todo/{id} Atualizar um item Item de tarefas pendentes Nenhum

existente
Um modelo é um objeto que representa os dados no aplicativo. Nesse caso, o único modelo é um item
de tarefas pendentes. Os modelos são representados como classes C#, também conhecidas como
POCOs ( Plain Old CLR Objects, ou objetos CRL básicos).
Um controlador é um objeto que manipula solicitações HTTP e cria a resposta HTTP. Este aplicativo tem
um único controlador.
Para manter o tutorial simples, o aplicativo não usa um banco de dados persistente. O aplicativo de
exemplo armazena os itens de tarefas pendentes em um banco de dados em memória.
Pré-requisitos
Criar o projeto
Siga estas etapas no Visual Studio:
Selecione o modelo Aplicativo Web ASP.NET Core. Nomeie o projeto como TodoApi e clique em OK.
Na caixa de diálogo Novo aplicativo Web ASP.NET Core – TodoApi e escolha a versão do ASP.NET
Core. Selecione o modelo API e clique em OK. Não selecione Habilitar Suporte ao Docker.
No Visual Studio, pressione CTRL + F5 para iniciar o aplicativo. O Visual Studio inicia um navegador e navega
para http://localhost:<port>/api/values , em que <port> é um número de porta escolhido aleatoriamente. O
Chrome, Microsoft Edge e Firefox exibem a seguinte saída:
["value1","value2"]
Se usar o Internet Explorer, você deverá salvar um arquivo values.json.

tarefas pendentes.
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto. Selecione Adicionar > Nova
Pasta. Nomeie a pasta Models.
NOTE
As classes de modelo podem ficar em qualquer lugar no projeto. A pasta Modelos é usada por convenção para as classes
de modelo.
Classe. Nomeie a classe como TodoItem e clique em Adicionar.
Atualize a classe TodoItem com o código a seguir:
{
{
}
}

um determinado modelo de dados. Essa classe é criada derivando-a da classe
Classe. Nomeie a classe como TodoContext e clique em Adicionar.
{
{
: base(options)
{
}

}
}

(como o contexto do banco de dados) que são registrados com o contêiner de injeção de dependência (DI)
estão disponíveis para os controladores.
namespace TodoApi
{
{
{
services.AddMvc()
}

{
app.UseMvc();
}
}
}
namespace TodoApi
{
{
{
services.AddMvc();
}

{
app.UseMvc();
}
}
}
O código anterior:
No Gerenciador de Soluções, clique com o botão direito do mouse na pasta Controladores. Selecione
Adicionar > Novo Item. Na caixa de diálogo Adicionar Novo Item, selecione o modelo Classe do
Controlador de API. Nomeie a classe como TodoController e clique em Adicionar.
using System.Linq;
{
{

{
_context = context;
{
}
}
}
}
O código anterior define uma classe de controlador de API sem métodos. Nas próximas seções, os métodos
serão adicionados para implementar a API.
using System.Linq;
{
[ApiController]
{

{
_context = context;
{
}
}
}
}
O código anterior:
Cria um novo item de Tarefas pendentes quando TodoItems está vazio. Você não poderá excluir todos os
itens de Tarefas pendentes porque o construtor cria um novo se TodoItems estiver vazio.
Nas próximas seções, os métodos serão adicionados para implementar a API. A classe é anotada com um
atributo [ApiController] para habilitar alguns recursos convenientes. Para obter informações sobre os
recursos habilitados pelo atributo, confira Anotar classe com o ApiControllerAttribute.
O construtor do controlador usa a Injeção de Dependência para injetar o contexto de banco de dados (
TodoContext ) no controlador. O contexto de banco de dados é usado em cada um dos métodos CRUD no
controlador. O construtor adiciona um item no banco de dados em memória, caso ele não exista.

[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}
[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return item;
}

GET /api/todo
GET /api/todo/{id}
[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
O atributo [HttpGet] indica um método que responde a uma solicitação HTTP GET. O caminho da URL de
cada método é construído da seguinte maneira:
{
{
{
[ApiController]
{
"Controlador". Para esta amostra, o nome de classe do controlador é TodoController e o nome da raiz é
“todo”. O roteamento do ASP.NET Core não diferencia maiúsculas de minúsculas.
Se o atributo [HttpGet] tiver um modelo de rota (como [HttpGet("/products")] ), acrescente isso ao
caminho. Esta amostra não usa um modelo. Para obter mais informações, confira Roteamento de atributo
com atributos Http[Verb].
No método GetById a seguir, "{id}" é uma variável de espaço reservado para o identificador exclusivo do
item pendente. Quando GetById é invocado, ele atribui o valor de "{id}" na URL ao parâmetro id do
método.

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Valores de retorno
supondo que não haja nenhuma exceção sem tratamento. As exceções sem tratamento são convertidas em
erros 5xx.
Se nenhum item corresponder à ID solicitada, o método retornará um erro 404. O retorno NotFound
retorna uma resposta HTTP 404.
resposta HTTP 200.
Se nenhum item corresponder à ID solicitada, o método retornará um erro 404. O retorno NotFound
retorna uma resposta HTTP 404.
resposta HTTP 200.
No Visual Studio, pressione CTRL + F5 para iniciar o aplicativo. O Visual Studio inicia um navegador e navega
para http://localhost:<port>/api/values , em que <port> é um número de porta escolhido aleatoriamente.
Navegue até o controlador Todo no http://localhost:<port>/api/todo .

Create
[HttpPost]
{
if (item == null)
{
}

}
O código anterior é um método HTTP POST, conforme indicado pelo atributo [HttpPost]. O atributo
[HttpPost]
{

}
O código anterior é um método HTTP POST, conforme indicado pelo atributo [HttpPost]. O MVC obtém o
valor do item pendente no corpo da solicitação HTTP.
Adiciona um cabeçalho Local à resposta. O cabeçalho Location especifica o URI do item de tarefas
pendentes recém-criado. Consulte 10.2.2 201 criado.

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Abra o Postman.
{
"name":"walk dog",
"isComplete":true
}
TIP

Atualização
[HttpPut("{id}")]
{
{
}

if (todo == null)
{
return NotFound();
}
return NoContent();
}
[HttpPut("{id}")]
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
Update é semelhante a Create , exceto pelo uso de HTTP PUT. A resposta é 204 (Sem conteúdo). De acordo
com a especificação de HTTP, uma solicitação PUT requer que o cliente envie a entidade atualizada inteira, não
apenas os deltas. Para dar suporte a atualizações parciais, use HTTP PATCH.
Excluir
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}


{
app.UseMvc();
}
Adicione um arquivo HTML, chamado index.html, ao diretório wwwroot do projeto. Substitua seu conteúdo
pela seguinte marcação:
<!DOCTYPE html>
<html>
<head>
<style>
cursor: pointer;
}
#spoiler {
display: none;
}
table {
border: 1px solid;
}
th {
color: white;
}
td {
border: 1px solid;
padding: 5px;
}
</style>
</head>
<body>
<h1>To-do CRUD</h1>
<h3>Add</h3>
</form>
<div id="spoiler">
<h3>Edit</h3>
</form>
</div>
<table>
<tr>
<th>Name</th>
<th>Name</th>
<th></th>
<th></th>
</tr>
</table>
</body>
</html>
código a seguir:

let todos = null;
let name = 'to-do';
if (data) {
if (data > 1) {
name = 'to-dos';
}
} else {
}
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
url: uri,
alert('here');
},
getData();
}
});
}
$.ajax({
type: 'DELETE',
getData();
}
});
}
}
});
}
const item = {
};
$.ajax({
type: 'PUT',
getData();
}
});
closeInput();
return false;
});
}
Pode ser necessário realizar uma alteração nas configurações de inicialização do projeto do ASP.NET Core
para testar a página HTML localmente. Abra launchSettings.json no diretório Propriedades do projeto. Remova
a propriedade launchUrl para forçar o aplicativo a ser aberto em index.html, o arquivo padrão do projeto.
Há várias maneiras de obter o jQuery. No trecho de código anterior, a biblioteca é carregada de uma CDN. Este
é um exemplo completo de CRUD ao chamar a API com o jQuery. Existem recursos adicionais neste exemplo
para enriquecer a experiência. Abaixo estão as explicações relacionadas às chamadas à API.
A função ajax do jQuery envia uma solicitação AJAX para a API, que retorna o JSON que representa um objeto
ou uma matriz. Essa função pode lidar com todas as formas de interação de HTTP, enviando uma solicitação
HTTP à url especificada. GET é usado como o type . A função de retorno de chamada success será
invocada se a solicitação for bem-sucedida. No retorno de chamada, o DOM é atualizado com as informações
do item pendente.
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}

Para adicionar um item pendente, envie uma solicitação HTTP POST para /api/todo/. O corpo da solicitação
deve conter um objeto pendente. A função ajax está usando o POST para chamar a API. Para as solicitações
POST e PUT , o corpo da solicitação representa os dados enviados para a API. A API está esperando um corpo
de solicitação JSON. As opções accepts e contentType são definidas como application/json para classificar
o tipo de mídia que está sendo recebido e enviado, respectivamente. Os dados são convertidos em um objeto
JSON usando JSON.stringify . Quando a API retorna um código de status de êxito, a função getData é
invocada para atualizar a tabela HTML.
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}

Atualizar um item pendente é muito semelhante a adicionar um item pendente, pois ambas as ações contam
com um corpo da solicitação. Nesse caso, a única diferença real entre as duas é que a url é alterada para
adicionar o identificador exclusivo do item e o type é PUT .
$.ajax({
type: 'PUT',
getData();
}
});

A exclusão de um item pendente é feita definindo o type na chamada do AJAX como DELETE e especificando
o identificador exclusivo do item na URL.
$.ajax({
type: 'DELETE',
getData();
}
});
Próximas etapas
Studio Code

Neste tutorial, crie uma API Web para gerenciar uma lista de itens de "tarefas pendentes". Uma interface do
usuário não é construída.
macOS, Linux, Windows: API Web com o Visual Studio Code (Este tutorial)
Visão geral

Pré-requisitos
Instale o seguinte:
Visual Studio Code
Visual Studio Code
Consulte Ajuda do Visual Studio Code para obter dicas sobre como usar o VS Code.
Criar o projeto
Em um console, execute os seguintes comandos:
dotnet new webapi -o TodoApi

code TodoApi
A pasta TodoApi é aberta no VS Code (Visual Studio Code). Selecione o arquivo Startup.cs.
Selecione Sim para a mensagem de Aviso “Os ativos necessários para compilar e depurar estão ausentes em
'TodoApi'. Deseja adicioná-los?”
Pressione Depurar (F5) para compilar e executar o programa. Em um navegador, navegue até
http://localhost:5000/api/values. É exibida a saída a seguir:
["value1","value2"]

A criação de um projeto no ASP.NET Core 2.1 ou posterior adiciona o metapacote Microsoft.AspNetCore.App
ao arquivo de projeto:
<ItemGroup>
</ItemGroup>
A criação de um projeto no ASP.NET Core 2.0 ou posterior adiciona o metapacote Microsoft.AspNetCore.All ao

arquivo de projeto:
<ItemGroup>
</ItemGroup>
Não é necessário instalar o provedor de banco de dados Entity Framework Core InMemory separadamente. Este
provedor de banco de dados permite que o Entity Framework Core seja usado com um banco de dados em
memória.

tarefas pendentes.
Adicione uma pasta chamada Models. Você pode colocar as classes de modelo em qualquer lugar no projeto,
mas a pasta Models é usada por convenção.
Adicione uma classe TodoItem com o seguinte código:
{
{
}
}

Adicione uma classe TodoContext à pasta Models:
{
{
: base(options)
{
}

}
}

namespace TodoApi
{
{
{
services.AddMvc()
}

{
app.UseMvc();
}
}
}
namespace TodoApi
{
{
{
services.AddMvc();
}

{
app.UseMvc();
}
}
}
O código anterior:
Na pasta Controllers, crie uma classe chamada TodoController . Substitua seu conteúdo pelo código a seguir:
using System.Linq;
{
{

{
_context = context;
{
}
}
}
}
using System.Linq;
{
[ApiController]
{

{
_context = context;
{
}
}
}
}
O código anterior:
atributo [ApiController] para habilitar alguns recursos convenientes. Para obter informações sobre os recursos
habilitados pelo atributo, confira Anotar classe com o ApiControllerAttribute.

[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}
[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return item;
}

GET /api/todo
GET /api/todo/{id}
[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
{
{
{
[ApiController]
{

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Valores de retorno
5xx.
resposta HTTP 200.
resposta HTTP 200.
No VS Code, pressione F5 para iniciar o aplicativo. Navegue até http://localhost:5000/api/todo (o controlador
Todo que nós criamos).


{
app.UseMvc();
}
<!DOCTYPE html>
<html>
<head>
<style>
cursor: pointer;
}
#spoiler {
display: none;
}
table {
border: 1px solid;
}
th {
color: white;
}
td {
border: 1px solid;
padding: 5px;
}
</style>
</head>
<body>
<h1>To-do CRUD</h1>
<h3>Add</h3>
</form>
<div id="spoiler">
<h3>Edit</h3>
</form>
</div>
<table>
<tr>
<th>Name</th>
<th></th>
<th></th>
</tr>
</table>
</body>
</html>
código a seguir:

let todos = null;
let name = 'to-do';
if (data) {
if (data > 1) {
name = 'to-dos';
}
} else {
}
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}
$.ajax({
type: 'DELETE',
getData();
}
});
}
}
});
}
const item = {
};
$.ajax({
type: 'PUT',
getData();
}
});
closeInput();
return false;
});
}
HTTP à url especificada. GET é usado como o type . A função de retorno de chamada success será invocada
se a solicitação for bem-sucedida. No retorno de chamada, o DOM é atualizado com as informações do item
pendente.
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}

POST e PUT , o corpo da solicitação representa os dados enviados para a API. A API está esperando um corpo de
solicitação JSON. As opções accepts e contentType são definidas como application/json para classificar o
tipo de mídia que está sendo recebido e enviado, respectivamente. Os dados são convertidos em um objeto
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}

$.ajax({
type: 'PUT',
getData();
}
});

$.ajax({
type: 'DELETE',
getData();
}
});

Create
[HttpPost]
{
if (item == null)
{
}

}
[HttpPost]
{

}
O código anterior é um método HTTP POST, conforme indicado pelo atributo [HttpPost]. O MVC obtém o valor
do item pendente no corpo da solicitação HTTP.

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Abra o Postman.
{
"name":"walk dog",
"isComplete":true
}
TIP

Atualização
[HttpPut("{id}")]
{
{
}

if (todo == null)
{
return NotFound();
}
return NoContent();
}
[HttpPut("{id}")]
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
Update é semelhante a Create , exceto pelo uso de HTTP PUT. A resposta é 204 (Sem conteúdo). De acordo
com a especificação de HTTP, uma solicitação PUT requer que o cliente envie a entidade atualizada inteira, não
apenas os deltas. Para dar suporte a atualizações parciais, use HTTP PATCH.
Excluir
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}


Introdução
Depuração
Terminal integrado
Atalhos de teclado
Próximas etapas
Studio para Mac

Neste tutorial, crie uma API Web para gerenciar uma lista de itens de "tarefas pendentes". A interface do usuário
não é construída.
macOS: API Web com o Visual Studio para Mac (este tutorial)
Visão geral

PUT /api/todo/{id} Atualizar um item Item de tarefas pendentes Nenhum

existente
Confira Introdução ao ASP.NET Core MVC no Mac ou Linux para obter um exemplo que usa um banco de
dados persistente.
Pré-requisitos
Criar o projeto
Selecione Aplicativo .NET Core > API Web ASP.NET Core > Avançar.
Digite TodoApi para o Nome do Projeto e, em seguida, clique em Criar.
um navegador e navega para http://localhost:5000 . Você obtém um erro de HTTP 404 (Não Encontrado).
Altere a URL para http://localhost:<port>/api/values . Os dados do ValuesController são exibidos:
["value1","value2"]
Instalar o provedor de banco de dados Entity Framework Core InMemory. Este provedor de banco de dados
permite que o Entity Framework Core seja usado com um banco de dados em memória.
No menu Projeto, selecione Adicionar pacotes do NuGet.
Como alternativa, clique com o botão direito do mouse em Dependências e, em seguida, selecione
Adicionar Pacotes.
Digite EntityFrameworkCore.InMemory na caixa de pesquisa.
Selecione Microsoft.EntityFrameworkCore.InMemory e, em seguida, selecione Adicionar Pacote.
tarefas pendentes.
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto. Selecione Adicionar > Nova
Pasta. Nomeie a pasta como Modelos.
NOTE
Você pode colocar as classes de modelo em qualquer lugar no projeto, mas a pasta Models é usada por convenção.
Clique com o botão direito do mouse na pasta Modelos e selecione Adicionar > Novo Arquivo > Geral >
Classe Vazia. Nomeie a classe como TodoItem e, em seguida, clique em Novo.
Substitua o código gerado por:
{
{
}
}

Adicione uma classe denominada TodoContext à pasta Modelos.
{
{
: base(options)
{
}

}
}

namespace TodoApi
{
{
{
services.AddMvc()
}

{
app.UseMvc();
}
}
}
namespace TodoApi
{
{
{
services.AddMvc();
}

{
app.UseMvc();
}
}
}
O código anterior:
No Gerenciador de Soluções, na pasta Controladores, adicione a classe TodoController .
Substitua o código gerado pelo seguinte:
using System.Linq;
{
{

{
_context = context;
{
}
}
}
}
using System.Linq;
{
[ApiController]
{

{
_context = context;
{
}
}
}
}
O código anterior:
atributo [ApiController] para habilitar alguns recursos convenientes. Para obter informações sobre os recursos
habilitados pelo atributo, confira Anotar classe com o ApiControllerAttribute.

[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}
[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return item;
}

GET /api/todo
GET /api/todo/{id}
[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
{
{
{
[ApiController]
{

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Valores de retorno
5xx.
resposta HTTP 200.
resposta HTTP 200.
um navegador e navega para http://localhost:<port> , em que <port> é um número de porta escolhido
aleatoriamente. Você obtém um erro de HTTP 404 (Não Encontrado). Altere a URL para
http://localhost:<port>/api/values . Os dados do ValuesController são exibidos:
["value1","value2"]
Navegue até o controlador Todo no http://localhost:<port>/api/todo . O seguinte JSON é retornado:
[{"key":1,"name":"Item1","isComplete":false}]

Adicionaremos os métodos Create , Update e Delete ao controlador. Esses métodos são variações de um
mesmo tema e, portanto, mostrarei apenas o código e realçarei as principais diferenças. Compile o projeto
depois de adicionar ou alterar o código.
Create
[HttpPost]
{
if (item == null)
{
}

}
O método anterior responde a um HTTP POST, conforme indicado pelo atributo [HttpPost]. O atributo
[HttpPost]
{

}
O método anterior responde a um HTTP POST, conforme indicado pelo atributo [HttpPost]. O MVC obtém o
valor do item pendente no corpo da solicitação HTTP.
O método CreatedAtRoute retorna uma resposta 201. Essa é a resposta padrão para um método HTTP POST
que cria um novo recurso no servidor. CreatedAtRoute também adiciona um cabeçalho Local à resposta. O
cabeçalho Location especifica o URI do item de tarefas pendentes recém-criado. Consulte 10.2.2 201 criado.
Inicie o aplicativo (Executar > Iniciar com Depuração).
Abra o Postman.
{
"name":"walk dog",
"isComplete":true
}
TIP

É possível usar o URI do cabeçalho Local para acessar o recurso que você criou. O método Create retorna
CreatedAtRoute. O primeiro parâmetro passado para CreatedAtRoute representa a rota nomeada a ser usada
para gerar a URL. Lembre-se de que o método GetById criou a rota nomeada "GetTodo" :
Atualização
[HttpPut("{id}")]
{
{
}

if (todo == null)
{
return NotFound();
}
return NoContent();
}
[HttpPut("{id}")]
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
Update é semelhante a Create , mas usa HTTP PUT. A resposta é 204 (Sem conteúdo). De acordo com a
especificação HTTP, uma solicitação PUT exige que o cliente envie a entidade atualizada inteira, não apenas os
{
"key": 1,
"name": "walk dog",
"isComplete": true
}
Excluir
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
A resposta é 204 (Sem conteúdo).

{
app.UseMvc();
}
<!DOCTYPE html>
<html>
<head>
<style>
cursor: pointer;
}
#spoiler {
display: none;
}
table {
border: 1px solid;
}
th {
color: white;
}
td {
border: 1px solid;
padding: 5px;
}
</style>
</head>
<body>
<h1>To-do CRUD</h1>
<h3>Add</h3>
</form>
<div id="spoiler">
<h3>Edit</h3>
</form>
</div>
<table>
<tr>
<th>Name</th>
<th>Name</th>
<th></th>
<th></th>
</tr>
</table>
</body>
</html>
código a seguir:

let todos = null;
let name = 'to-do';
if (data) {
if (data > 1) {
name = 'to-dos';
}
} else {
}
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
url: uri,
alert('here');
},
getData();
}
});
}
$.ajax({
type: 'DELETE',
getData();
}
});
}
}
});
}
const item = {
};
$.ajax({
type: 'PUT',
getData();
}
});
closeInput();
return false;
});
}
Há várias maneiras de obter o jQuery. No trecho de código anterior, a biblioteca é carregada de uma CDN. Este
é um exemplo completo de CRUD ao chamar a API com o jQuery. Existem recursos adicionais neste exemplo
para enriquecer a experiência. Abaixo estão as explicações relacionadas às chamadas à API.
HTTP à url especificada. GET é usado como o type . A função de retorno de chamada success será invocada
se a solicitação for bem-sucedida. No retorno de chamada, o DOM é atualizado com as informações do item
pendente.
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}

POST e PUT , o corpo da solicitação representa os dados enviados para a API. A API está esperando um corpo
de solicitação JSON. As opções accepts e contentType são definidas como application/json para classificar o
tipo de mídia que está sendo recebido e enviado, respectivamente. Os dados são convertidos em um objeto
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}

$.ajax({
type: 'PUT',
getData();
}
});

$.ajax({
type: 'DELETE',
getData();
}
});
Próximas etapas
Criar serviços de back-end para aplicativos móveis
nativos com o ASP.NET Core
Por Steve Smith

Os aplicativos móveis podem se comunicar com facilidade com os serviços de back-end do ASP.NET Core.
Exibir ou baixar o código de exemplo dos serviços de back-end
Exemplo do aplicativo móvel nativo

Este tutorial demonstra como criar serviços de back-end usando o ASP.NET Core MVC para dar suporte a
aplicativos móveis nativos. Ele usa o aplicativo Xamarin Forms ToDoRest como seu cliente nativo, que inclui
clientes nativos separados para dispositivos Android, iOS, Universal do Windows e Windows Phone. Siga o
tutorial com links para criar o aplicativo nativo (e instale as ferramentas do Xamarin gratuitas necessárias), além de
baixar a solução de exemplo do Xamarin. A amostra do Xamarin inclui um projeto de serviços do ASP.NET Web
API 2, que substitui o aplicativo ASP.NET Core deste artigo (sem nenhuma alteração exigida pelo cliente).
Recursos
O aplicativo ToDoRest é compatível com listagem, adição, exclusão e atualização de itens de tarefas pendentes.
Cada item tem uma ID, um Nome, Observações e uma propriedade que indica se ele já foi Concluído.
A exibição principal dos itens, conforme mostrado acima, lista o nome de cada item e indica se ele foi concluído
com uma marca de seleção.
Tocar no ícone + abre uma caixa de diálogo de adição de itens:
Tocar em um item na tela da lista principal abre uma caixa de diálogo de edição, na qual o Nome do item,
Observações e configurações de Concluído podem ser modificados, ou o item pode ser excluído:
Esta amostra é configurada por padrão para usar os serviços de back-end hospedados em developer.xamarin.com,
que permitem operações somente leitura. Para testá-la por conta própria no aplicativo ASP.NET Core criado na
próxima seção em execução no computador, você precisará atualizar a constante RestUrl do aplicativo. Navegue
para o projeto ToDoREST e abra o arquivo Constants.cs. Substitua o RestUrl por uma URL que inclui o endereço
IP do computador (não localhost ou 127.0.0.1, pois esse endereço é usado no emulador do dispositivo, não no
computador). Inclua o número da porta também (5000). Para testar se os serviços funcionam com um dispositivo,
verifique se você não tem um firewall ativo bloqueando o acesso a essa porta.
// URL of REST service (Xamarin ReadOnly Service)

//public static string RestUrl = "http://developer.xamarin.com:8081/api/todoitems{0}";
// use your machine's IP address

public static string RestUrl = "http://192.168.1.207:5000/api/todoitems/{0}";
Criando o projeto ASP.NET Core

Crie um novo aplicativo Web do ASP.NET Core no Visual Studio. Escolha o modelo de Web API sem autenticação.
Nomeie o projeto como ToDoApi.
O aplicativo deve responder a todas as solicitações feitas através da porta 5000. Atualize o Program.cs para incluir
.UseUrls("http://*:5000") para ficar assim:

.UseKestrel()
.Build();
NOTE
Execute o aplicativo diretamente, em vez de por trás do IIS Express, que ignora solicitações não local por padrão. Execute
dotnet run em um prompt de comando ou escolha o perfil de nome do aplicativo no menu suspenso Destino de Depuração
na barra de ferramentas do Visual Studio.
Adicione uma classe de modelo para representar itens pendentes. Marque os campos obrigatórios usando o
atributo [Required] :
namespace ToDoApi.Models
{
{
[Required]
public string ID { get; set; }
[Required]
[Required]
public string Notes { get; set; }
public bool Done { get; set; }

}
}
Os métodos da API exigem alguma maneira de trabalhar com dados. Use a mesma interface IToDoRepository nos
usos de exemplo originais do Xamarin:
namespace ToDoApi.Interfaces
{
public interface IToDoRepository
{
bool DoesItemExist(string id);
IEnumerable<ToDoItem> All { get; }
ToDoItem Find(string id);
void Insert(ToDoItem item);
void Update(ToDoItem item);
void Delete(string id);
}
}
Para esta amostra, a implementação apenas usa uma coleção particular de itens:
using System.Linq;
namespace ToDoApi.Services
{
public class ToDoRepository : IToDoRepository
{
private List<ToDoItem> _toDoList;
public ToDoRepository()
{
InitializeData();
}
public IEnumerable<ToDoItem> All

{
get { return _toDoList; }
}
public bool DoesItemExist(string id)

{
}
public ToDoItem Find(string id)

{
return _toDoList.FirstOrDefault(item => item.ID == id);
}
public void Insert(ToDoItem item)

{
_toDoList.Add(item);
}
public void Update(ToDoItem item)

{
var todoItem = this.Find(item.ID);
var index = _toDoList.IndexOf(todoItem);
_toDoList.RemoveAt(index);
_toDoList.Insert(index, item);
}
public void Delete(string id)

{
_toDoList.Remove(this.Find(id));
}
private void InitializeData()

{
_toDoList = new List<ToDoItem>();

{
ID = "6bb8a868-dba1-4f1a-93b7-24ebce87e243",
Name = "Learn app development",
Notes = "Attend Xamarin University",
Done = true
};

{
ID = "b94afb54-a1cb-4313-8af3-b7511551b33b",
Name = "Develop apps",
Notes = "Use Xamarin Studio/Visual Studio",
Done = false
};

{
ID = "ecfa6f80-3671-4911-aabe-63cc442c1ecf",
Name = "Publish apps",
Notes = "All app stores",
Done = false,
};
}
}
}
Configure a implementação em Startup.cs:

{
services.AddMvc();
services.AddSingleton<IToDoRepository,ToDoRepository>();
}
Neste ponto, você está pronto para criar o ToDoItemsController.
TIP
Saiba mais sobre como criar APIs Web em Criar sua primeira API Web com o ASP.NET Core MVC e o Visual Studio.
Criando o controlador
Adicione um novo controlador ao projeto, ToDoItemsController. Ele deve herdar de
Microsoft.AspNetCore.Mvc.Controller. Adicione um atributo Route para indicar que o controlador manipulará as
solicitações feitas para caminhos que começam com api/todoitems . O token [controller] na rota é substituído
pelo nome do controlador (com a omissão do sufixo Controller ) e é especialmente útil para rotas globais. Saiba
mais sobre o roteamento.
O controlador requer um IToDoRepository para a função; solicite uma instância desse tipo usando o construtor do
controlador. No tempo de execução, esta instância será fornecida com suporte do framework parainjeção de
dependência.
using System;
namespace ToDoApi.Controllers
{
public class ToDoItemsController : Controller
{
private readonly IToDoRepository _toDoRepository;
public ToDoItemsController(IToDoRepository toDoRepository)

{
_toDoRepository = toDoRepository;
}
Essa API é compatível com quatro verbos HTTP diferentes para executar operações CRUD (Criar, Ler, Atualizar,
Excluir) na fonte de dados. A mais simples delas é a operação Read, que corresponde a uma solicitação HTTP GET.
Lendo itens
A solicitação de uma lista de itens é feita com uma solicitação GET ao método List . O atributo [HttpGet] no
método List indica que esta ação só deve lidar com as solicitações GET. A rota para esta ação é a rota
especificada no controlador. Você não precisa necessariamente usar o nome da ação como parte da rota. Você
precisa garantir que cada ação tem uma rota exclusiva e não ambígua. Os atributos de roteamento podem ser
aplicados nos níveis de método e controlador para criar rotas específicas.
[HttpGet]
public IActionResult List()
{
return Ok(_toDoRepository.All);
}
O método List retorna um código de resposta OK 200 e todos os itens de tarefas, serializados como JSON.
Você pode testar o novo método de API usando uma variedade de ferramentas, como Postman. Veja abaixo:
Criando itens
Por convenção, a criação de novos itens de dados é mapeada para o verbo HTTP POST. O método Create tem
um atributo [HttpPost] aplicado a ele e aceita uma instância ToDoItem . Como o argumento item será enviado
no corpo de POST, este parâmetro será decorado com o atributo [FromBody] .
Dentro do método, o item é verificado quanto à validade e existência anterior no armazenamento de dados e, se
nenhum problema ocorrer, ele será adicionado usando o repositório. A verificação de ModelState.IsValid executa
a validação do modelo e deve ser feita em todos os métodos de API que aceitam a entrada do usuário.
[HttpPost]
public IActionResult Create([FromBody] ToDoItem item)
{
try
{
{
}
bool itemExists = _toDoRepository.DoesItemExist(item.ID);
if (itemExists)
{
return StatusCode(StatusCodes.Status409Conflict, ErrorCode.TodoItemIDInUse.ToString());
}
_toDoRepository.Insert(item);
}
catch (Exception)
{
return BadRequest(ErrorCode.CouldNotCreateItem.ToString());
}
return Ok(item);
}
A amostra usa uma enumeração que contém códigos de erro que são passados para o cliente móvel:
public enum ErrorCode

{
TodoItemNameAndNotesRequired,
TodoItemIDInUse,
RecordNotFound,
CouldNotCreateItem,
CouldNotUpdateItem,
CouldNotDeleteItem
}
Teste a adição de novos itens usando Postman escolhendo o verbo POST fornecendo o novo objeto no formato
JSON no corpo da solicitação. Você também deve adicionar um cabeçalho de solicitação que especifica um
Content-Type de application/json .
O método retorna o item recém-criado na resposta.
Atualizando itens
A modificação de registros é feita com as solicitações HTTP PUT. Além desta mudança, o método Edit é quase
idêntico ao Create . Observe que, se o registro não for encontrado, a ação Edit retornará uma resposta NotFound
(404).
[HttpPut]
public IActionResult Edit([FromBody] ToDoItem item)
{
try
{
{
}
var existingItem = _toDoRepository.Find(item.ID);
if (existingItem == null)
{
}
_toDoRepository.Update(item);
}
catch (Exception)
{
return BadRequest(ErrorCode.CouldNotUpdateItem.ToString());
}
return NoContent();
}
Para testar com Postman, altere o verbo para PUT. Especifique os dados do objeto atualizado no corpo da
solicitação.
Este método retornará uma resposta NoContent (204) quando obtiver êxito, para manter a consistência com a API
já existente.
Excluindo itens
A exclusão de registros é feita por meio da criação de solicitações de exclusão para o serviço e por meio do envio
do ID do item a ser excluído. Assim como as atualizações, as solicitações de itens que não existem receberão
respostas NotFound . Caso contrário, uma solicitação bem-sucedida receberá uma resposta NoContent (204).
public IActionResult Delete(string id)
{
try
{
var item = _toDoRepository.Find(id);
if (item == null)
{
}
_toDoRepository.Delete(id);
}
catch (Exception)
{
return BadRequest(ErrorCode.CouldNotDeleteItem.ToString());
}
return NoContent();
}
Observe que, ao testar a funcionalidade de exclusão, nada é necessário no Corpo da solicitação.
Convenções de Web API comuns

À medida que você desenvolve serviços de back-end para seu aplicativo, desejará criar um conjunto consistente de
convenções ou políticas para lidar com preocupações paralelas. Por exemplo, no serviço mostrado acima, as
solicitações de registros específicos que não foram encontrados receberam uma resposta NotFound , em vez de
uma resposta BadRequest . Da mesma forma, os comandos feitos para esse serviço que passaram tipos associados
a um modelo sempre verificaram ModelState.IsValid e retornaram um BadRequest para tipos de modelo
inválidos.
Depois de identificar uma diretiva comum para suas APIs, você geralmente pode encapsulá-la em um filtro. Saiba
mais sobre como encapsular políticas comuns da API em aplicativos ASP.NET Core MVC.
Recursos adicionais
Páginas de ajuda da API Web ASP.NET Core com o
Swagger/OpenAPI
Por Christoph Nienaber e Rico Suter

Ao consumir uma API Web, entender seus vários métodos pode ser um desafio para um desenvolvedor. O
Swagger, também conhecido como OpenAPI, resolve o problema da geração de páginas de ajuda e de
documentação úteis para APIs Web. Ele oferece benefícios, como documentação interativa, geração de SDK de
cliente e capacidade de descoberta de API.
Neste artigo, são exibidas as implementações do .NET do Swagger Swashbuckle.AspNetCore e NSwag:
O Swashbuckle.AspNetCore é um projeto de software livre para geração de documentos do Swagger
para APIs Web ASP.NET Core.
O NSwag é outro projeto de software livre para geração de documentos do Swagger e a integração da
interface do usuário do Swagger ou do ReDoc em APIs Web ASP.NET Core. Além disso, o NSwag
oferece abordagens para gerar o código de cliente C# e TypeScript para sua API.
O que é o Swagger / OpenAPI?

O Swagger é uma especificação independente de linguagem para descrever APIs REST. O projeto de Swagger
foi doado para a Iniciativa OpenAPI, na qual agora é chamado de OpenAPI. Ambos os nomes são
intercambiáveis, mas OpenAPI é o preferencial. Ele permite que computadores e pessoas entendam os recursos
de um serviço sem nenhum acesso direto à implementação (código-fonte, acesso à rede, documentação). Uma
meta é minimizar a quantidade de trabalho necessário para conectar-se a serviços desassociados. Outra meta é
reduzir o período de tempo necessário para documentar um serviço com precisão.
Especificação do Swagger (swagger.json)

O ponto central para o fluxo do Swagger é a especificação do Swagger que é, por padrão, um documento
chamado swagger.json. Ele é gerado pela cadeia de ferramentas do Swagger (ou por implementações de
terceiros) com base no seu serviço. Ele descreve os recursos da API e como acessá-lo com HTTP. Ele gera a
interface do usuário do Swagger e é usado pela cadeia de ferramentas para habilitar a geração e a descoberta de
código de cliente. Aqui está um exemplo de uma especificação do Swagger, resumida:
{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "API V1"
},
"basePath": "/",
"paths": {
"/api/Todo": {
"get": {
"tags": [
"Todo"
],
"operationId": "ApiTodoGet",
"consumes": [],
"produces": [
"text/plain",
"application/json",
"text/json"
],
"responses": {
"200": {
"description": "Success",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/TodoItem"
}
}
}
}
},
"post": {
...
}
},
"/api/Todo/{id}": {
"get": {
...
},
"put": {
...
},
"delete": {
...
},
"definitions": {
"TodoItem": {
"type": "object",
"properties": {
"id": {
"format": "int64",
"type": "integer"
},
"name": {
"type": "string"
},
"isComplete": {
"default": false,
"type": "boolean"
}
}
}
},
"securityDefinitions": {}
}
Interface do usuário do Swagger
A Interface do usuário do Swagger oferece uma interface do usuário baseada na Web que conta com
informações sobre o serviço, usando a especificação do Swagger gerada. O Swashbuckle e o NSwag incluem
uma versão incorporada da interface do usuário do Swagger, para que ele possa ser hospedado em seu
aplicativo ASP.NET Core usando uma chamada de registro de middleware. A interface do usuário da Web tem
esta aparência:
Todo método de ação pública nos controladores pode ser testado da interface do usuário. Clique em um nome
de método para expandir a seção. Adicione os parâmetros necessários e, em seguida, clique em Experimente!.
NOTE
A versão da interface do usuário do Swagger usada para as capturas de tela é a versão 2. Para obter um exemplo da
versão 3, confira Exemplo Petstore.
Próximas etapas
Introdução ao Swashbuckle
Introdução ao NSwag
Introdução ao Swashbuckle e ao ASP.NET Core
Por Shayne Boyer e Scott Addie

Há três componentes principais bo Swashbuckle:
Swashbuckle.AspNetCore.Swagger: um modelo de objeto e um middleware do Swagger para expor objetos
SwaggerDocument como pontos de extremidade JSON.
Swashbuckle.AspNetCore.SwaggerGen: um gerador do Swagger cria objetos SwaggerDocument diretamente

de modelos, controladores e rotas. Normalmente, ele é combinado com o middleware de ponto de
extremidade do Swagger para expor automaticamente o JSON do Swagger.
Swashbuckle.AspNetCore.SwaggerUI: uma versão incorporada da ferramenta de interface do usuário do
Swagger. Ele interpreta o JSON do Swagger para criar uma experiência rica e personalizável para descrever
a funcionalidade da API da Web. Ela inclui o agente de teste interno para os métodos públicos.
Instalação do pacote
O Swashbuckle pode ser adicionado com as seguintes abordagens:
Visual Studio
Visual Studio Code
CLI do .NET Core
Da janela Console do Gerenciador de Pacotes:
Acesse Exibição > Outras Janelas > Console do Gerenciador de Pacotes
Navegue para o diretório no qual o arquivo TodoApi.csproj está localizado
Install-Package Swashbuckle.AspNetCore
Da caixa de diálogo Gerenciar Pacotes NuGet:

Clique com o botão direito do mouse no projeto em Gerenciador de Soluções > Gerenciar Pacotes
NuGet
Defina a Origem do pacote para "nuget.org"
Insira "Swashbuckle.AspNetCore" na caixa de pesquisa
Selecione o pacote "Swashbuckle.AspNetCore" na guia Procurar e clique em Instalar
Adicionar e configurar o middleware do Swagger

Adicione o gerador do Swagger à coleção de serviços no método Startup.ConfigureServices :
{
services.AddMvc();
// Register the Swagger generator, defining 1 or more Swagger documents

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
}

{
services.AddMvc()

{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
}
Importe o namespace a seguir para usar a classe Info :
using Swashbuckle.AspNetCore.Swagger;
No método Startup.Configure , habilite o middleware para atender ao documento JSON gerado e à interface do
usuário do Swagger:

{
// Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();
// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),

// specifying the Swagger JSON endpoint.
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
app.UseMvc();
}
A chamada de método UseSwaggerUI anterior habilita o Middleware de arquivos estáticos. Se você estiver
direcionando ao .NET Framework ou ao .NET Core 1.x, adicione o pacote NuGet Microsoft.AspNetCore.StaticFiles
ao projeto.
Inicie o aplicativo e navegue até http://localhost:<port>/swagger/v1/swagger.json . O documento gerado que
descreve os pontos de extremidade é exibido conforme é mostrado na Especificação do Swagger (swagger.json).
A interface do usuário do Swagger pode ser encontrada em http://localhost:<port>/swagger . Explore a API por
meio da interface do usuário do Swagger e incorpore-a em outros programas.
TIP
Para atender à interface do usuário do Swagger na raiz do aplicativo ( http://localhost:<port>/ ), defina a propriedade
RoutePrefix como uma cadeia de caracteres vazia:
{
c.RoutePrefix = string.Empty;
});
Personalizar e estender
O Swagger fornece opções para documentar o modelo de objeto e personalizar a interface do usuário para
corresponder ao seu tema.
Descrição e informações da API
A ação de configuração passada para o método AddSwaggerGen adiciona informações como o autor, a licença e a
descrição:

{
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "ToDo API",
Description = "A simple example ASP.NET Core Web API",
TermsOfService = "None",
Contact = new Contact
{
Name = "Shayne Boyer",
Email = string.Empty,
Url = "https://twitter.com/spboyer"
},
License = new License
{
Name = "Use under LICX",
Url = "https://example.com/license"
}
});
});
A interface do usuário do Swagger exibe as informações da versão:

comentários XML
Comentários XML podem ser habilitados com as seguintes abordagens:
Visual Studio
Visual Studio Code
Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Editar
<nome_do_projeto>.csproj.
Manualmente, adicione as linhas destacadas ao arquivo .csproj:
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Propriedades.
Marque a caixa Arquivo de documentação XML na seção Saída da guia Build.
A habilitação de comentários XML fornece informações de depuração para os membros e os tipos públicos não
documentados. Os membros e tipos não documentados são indicados por mensagem de aviso. Por exemplo, a
seguinte mensagem indica uma violação do código de aviso 1591:
warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'
Para suprimir os avisos de todo o projeto, defina uma lista separada por ponto e vírgula dos códigos de aviso a
serem ignorados no arquivo do projeto. Acrescentar os códigos de aviso ao $(NoWarn); também aplica os valores
padrão C#.
<PropertyGroup>
</PropertyGroup>
<PropertyGroup>
<DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
</PropertyGroup>
Para suprimir avisos somente para membros específicos, coloque o código nas diretivas de pré-processador
#pragma warning. Essa abordagem é útil para o código que não deve ser exposto por meio dos documentos da
API. No exemplo a seguir, o código de aviso CS1591 é ignorado para toda a classe Program . A imposição do
código de aviso é restaurada no fechamento da definição de classe. Especifique vários códigos de aviso com uma
lista delimitada por vírgulas.
namespace TodoApi
{
#pragma warning disable CS1591
{
public static void Main(string[] args) =>

.Build();
}
#pragma warning restore CS1591
}
Configure o Swagger para usar o arquivo XML gerado. Para sistemas operacionais Linux ou que não sejam
Windows, os caminhos e nomes de arquivo podem diferenciar maiúsculas de minúsculas. Por exemplo, um
arquivo TodoApi.XML é válido no Windows, mas não no CentOS.
{
services.AddMvc()

{
{
Version = "v1",
Title = "ToDo API",
{
},
{
}
});
// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
}
{
services.AddMvc();

{
{
Version = "v1",
Title = "ToDo API",
{
},
{
}
});
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
});
}
{
services.AddMvc();

{
{
Version = "v1",
Title = "ToDo API",
{
},
{
}
});
var xmlFile = $"{Assembly.GetEntryAssembly().GetName().Name}.xml";
});
}
No código anterior, a Reflexão é usada para criar um nome de arquivo XML correspondente ao do projeto de API
da Web. A propriedade AppContext.BaseDirectory é usada para construir um caminho para o arquivo XML.
Adicionar comentários de barra tripla a uma ação aprimora a interface do usuário do Swagger adicionando a
descrição ao cabeçalho da seção. Adicione um elemento <summary> acima da ação Delete :
/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
A interface do usuário do Swagger exibe o texto interno do elemento <summary> do código anterior:
A interface do usuário é controlada pelo esquema JSON gerado:
"delete": {
"tags": [
"Todo"
],
"summary": "Deletes a specific TodoItem.",
"operationId": "ApiTodoByIdDelete",
"consumes": [],
"produces": [],
"parameters": [
{
"name": "id",
"in": "path",
"description": "",
"required": true,
"type": "integer",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Success"
}
}
}
Adicione um elemento <remarks> na documentação do método da ação Create . Ele complementa as

informações especificadas no elemento <summary> e fornece uma interface de usuário do Swagger mais robusta.
O conteúdo do elemento <remarks> pode consistir em texto, JSON ou XML.
/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
/// POST /Todo
/// {
/// "id": 1,
/// "name": "Item1",
/// "isComplete": true
/// }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(typeof(TodoItem), 201)]
{
if (item == null)
{
}

}
/// <summary>
/// </summary>
/// <remarks>
/// Sample request:
///
/// POST /Todo
/// {
/// "id": 1,
/// }
///
/// </remarks>
[HttpPost]
public ActionResult<TodoItem> Create(TodoItem item)
{

}
Observe os aprimoramentos da interface do usuário com esses comentários adicionais:

Anotações de dados
Decore o modelo com atributos, encontrados no namespace System.ComponentModel.DataAnnotations, para
ajudar a gerar os componentes da interface do usuário do Swagger.
Adicione o atributo [Required] à propriedade Name da classe TodoItem :
using System.ComponentModel;
{
{
[Required]
[DefaultValue(false)]
}
}
A presença desse atributo altera o comportamento da interface do usuário e altera o esquema JSON subjacente:
"definitions": {
"TodoItem": {
"required": [
"name"
],
"type": "object",
"properties": {
"id": {
"format": "int64",
"type": "integer"
},
"name": {
"type": "string"
},
"isComplete": {
"default": false,
"type": "boolean"
}
}
}
},
Adicione o atributo [Produces("application/json")] ao controlador da API. Sua finalidade é declarar que as ações
do controlador permitem o tipo de conteúdo de resposta application/json:
{
[ApiController]
{
A lista suspensa Tipo de Conteúdo de Resposta seleciona esse tipo de conteúdo como o padrão para ações GET
do controlador:
À medida que aumenta o uso de anotações de dados na API Web, a interface do usuário e as páginas de ajuda da
API se tornam mais descritivas e úteis.
Descrever os tipos de resposta
Os desenvolvedores de consumo estão mais preocupados com o que é retornado, especificamente, o tipos de
resposta e o códigos de erro (se eles não forem padrão). Os tipos de resposta e os códigos de erro são indicados
nos comentários XML e nas anotações de dados.
A ação Create retorna um código de status HTTP 201 em caso de sucesso. Um código de status HTTP 400 é
retornado quando o corpo da solicitação postada é nulo. Sem a documentação adequada na interface do usuário
do Swagger, o consumidor não tem conhecimento desses resultados esperados. Corrija esse problema
adicionando as linhas realçadas no exemplo a seguir:
/// <summary>
/// </summary>
/// <remarks>
/// Sample request:
///
/// POST /Todo
/// {
/// "id": 1,
/// }
///
/// </remarks>
[HttpPost]
[ProducesResponseType(typeof(TodoItem), 201)]
{
if (item == null)
{
}

}
/// <summary>
/// </summary>
/// <remarks>
/// Sample request:
///
/// POST /Todo
/// {
/// "id": 1,
/// }
///
/// </remarks>
[HttpPost]
{

}
A interface do usuário do Swagger agora documenta claramente os códigos de resposta HTTP esperados:
Personalizar a interface do usuário
A interface do usuário de estoque é apresentável e funcional. No entanto, as páginas de documentação da API
devem representar a sua marca ou o seu tema. Para inserir sua marca nos componentes do Swashbuckle é
necessário adicionar recursos para atender aos arquivos estáticos e criar a estrutura de pasta para hospedar esses
arquivos.
Se você estiver direcionando ao .NET Framework ou ao .NET Core 1.x, adicione o pacote do NuGet
Microsoft.AspNetCore.StaticFiles ao projeto:
O pacote do NuGet anterior já estará instalado se você estiver direcionando ao .NET Core 2.x e usando o
metapackage.
Habilite o middleware de arquivos estáticos:

{
// Enable middleware to serve generated Swagger as a JSON endpoint.

app.UseSwagger();
// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),

// specifying the Swagger JSON endpoint.
{
});
app.UseMvc();
}
Adquira o conteúdo da pasta dist do repositório GitHub da interface do usuário do Swagger. Essa pasta contém os
ativos necessários para a página da interface do usuário do Swagger.
Crie uma pasta swagger/wwwroot/ui e copie para ela o conteúdo da pasta dist.
Crie um arquivo custom.css em swagger/wwwroot/ui, com o seguinte CSS para personalizar o cabeçalho da
página:
.swagger-ui .topbar {
background-color: #000;
border-bottom: 3px solid #547f00;
}
Referencie custom.css no arquivo index.html depois de todos os outros arquivos CSS:
<link href="https://fonts.googleapis.com/css?
family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="./swagger-ui.css">
<link rel="stylesheet" type="text/css" href="custom.css">
Navegue até a página index.html em http://localhost:<port>/swagger/ui/index.html . Digite

http://localhost:<port>/swagger/v1/swagger.json na caixa de texto do cabeçalho e clique no botão Explorar. A
página resultante será semelhante ao seguinte:
Há muito mais que você pode fazer com a página. Consulte as funcionalidades completas para os recursos de
interface do usuário no repositório GitHub da interface do usuário do Swagger.
Introdução ao NSwag e ao ASP.NET Core
Por Christoph Nienaber e Rico Suter

Registre os middlewares NSwag para:
Gerar a especificação do Swagger para a API Web implementada.
Oferecer a interface do usuário do Swagger para navegar e testar a API Web.
Para usar os middlewares ASP.NET Core do NSwag, instale o pacote do NuGet NSwag.AspNetCore. Este pacote
contém os middlewares para gerar e oferecer a especificação do Swagger, interface do usuário do Swagger (v2 e
v3) e a interface do usuário do ReDoc.
Além disso, é altamente recomendável usar as funcionalidades de geração de código do NSwag. Escolha uma das
seguintes opções para usar as funcionalidades de geração de código:
Use o NSwagStudio, um aplicativo da área de trabalho do Windows para a geração de código do cliente em C#
e em TypeScript para sua API.
Use os pacotes do NuGet NSwag.CodeGeneration.CSharp ou NSwag.CodeGeneration.TypeScript para a
geração de código dentro do projeto.
Use o NSwag na linha de comando.
Use o pacote NuGet NSwag.MSBuild.
Recursos
O principal motivo para usar o NSwag é que, além de apresentar a interface do usuário do Swagger e o gerador do
Swagger, também é possível usar recursos flexíveis para geração de código. Você não precisa de uma API existente.
É possível usar APIs de terceiros que incorporam o Swagger e permitem que o NSwag gere uma implementação
de cliente. De qualquer forma, o ciclo de desenvolvimento é acelerado e você pode se adaptar às alterações da API
com mais facilidade.
O pacote do NuGet do NSwag pode ser adicionado com as seguintes abordagens:
Visual Studio
Visual Studio Code
CLI do .NET Core
Da janela Console do Gerenciador de Pacotes:
Acesse Exibição > Outras Janelas > Console do Gerenciador de Pacotes
Navegue para o diretório no qual o arquivo TodoApi.csproj está localizado
Install-Package NSwag.AspNetCore
Da caixa de diálogo Gerenciar Pacotes NuGet:

Clique com o botão direito do mouse no projeto em Gerenciador de Soluções > Gerenciar Pacotes
NuGet
Defina a Origem do pacote para "nuget.org"
Insira "NSwag.AspNetCore" na caixa de pesquisa
Selecione o pacote "NSwag.AspNetCore" na guia Procurar e clique em Instalar
Adicionar e configurar o middleware do Swagger

Importe os seguintes namespaces na classe Startup :
using NJsonSchema;
using NSwag.AspNetCore;
No método Startup.ConfigureServices , registre os serviços obrigatórios do Swagger:

{
services.AddMvc();
// Register the Swagger services

services.AddSwagger();
}
No método Startup.Configure , habilite o middleware para atender à especificação do Swagger gerado e à interface
do usuário do Swagger v3:

{
// Register the Swagger generator and the Swagger UI middlewares

app.UseSwaggerUi3WithApiExplorer(settings =>
{
settings.GeneratorSettings.DefaultPropertyNameHandling =
PropertyNameHandling.CamelCase;
});
app.UseMvc();
}
Inicie o aplicativo. Navegue até http://localhost:<port>/swagger para exibir a interface do usuário do Swagger.
Navegue até http://localhost:<port>/swagger/v1/swagger.json para exibir a especificação do Swagger.
Geração de código
Por meio do NSwagStudio
Instale o NSwagStudio por meio do repositório GitHub oficial.
Inicie o NSwagStudio. Insira a URL do arquivo swagger.json na caixa de texto URL de Especificação do
Swagger e clique no botão Criar Cópia local.
Selecione o tipo de saída do cliente Cliente do CSharp. Outras opções incluem Cliente do TypeScript e
Controlador da API Web do CSharp. O uso de um controlador da API Web é basicamente uma geração
inversa. Ele usa uma especificação de um serviço para recriar o serviço.
Clique no botão Gerar Saídas. Uma implementação completa de cliente em C# do projeto TodoApi.NSwag é
produzida. Clique na guia Cliente do CSharp da seção Saídas para ver o código de cliente gerado:
//----------------------
// <auto-generated>
// Generated using the NSwag toolchain v11.17.3.0 (NJsonSchema v9.10.46.0 (Newtonsoft.Json v9.0.0.0))
(http://NSwag.org)
// </auto-generated>
//----------------------
namespace MyNamespace
{
#pragma warning disable // Disable all warnings
[System.CodeDom.Compiler.GeneratedCode("NSwag",
"11.17.3.0 (NJsonSchema v9.10.46.0 (Newtonsoft.Json v9.0.0.0))")]
public partial class TodoClient
{
private string _baseUrl = "http://localhost:50499";
private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;
public TodoClient()
{
_settings = new System.Lazy
<Newtonsoft.Json.JsonSerializerSettings>(() =>
{
var settings = new Newtonsoft.Json.JsonSerializerSettings();
UpdateJsonSerializerSettings(settings);
return settings;
});
}
public string BaseUrl

{
get { return _baseUrl; }
set { _baseUrl = value; }
}
// code omitted for brevity
TIP
O código de cliente em C# é gerado com base nas configurações definidas na guia Configurações da guia Cliente do
CSharp. Modifique as configurações para executar tarefas como geração de método síncrono e renomeação de namespace
padrão.
Copie o código C# gerado para um arquivo em um projeto de cliente (por exemplo, um aplicativo
Xamarin.Forms).
Inicie o consumo da API Web:
var todoClient = new TodoClient();
// Gets all to-dos from the API

var allTodos = await todoClient.GetAllAsync();
// Create a new TodoItem, and save it in the API

var createdTodo = await todoClient.CreateAsync(new TodoItem());
// Get a single to-do by ID

var foundTodo = await todoClient.GetByIdAsync(1);
NOTE
Você pode injetar uma URL base e/ou um cliente HTTP no cliente da API. A melhor prática é sempre reutilizar o HttpClient.
Outras maneiras de gerar o código do cliente

Você pode gerar o código de cliente de outras maneiras mais adequadas ao seu fluxo de trabalho:
MSBuild
No código
Modelos T4
Personalizar
O Swagger fornece opções para documentar o modelo de objeto para facilitar o consumo da API Web.
Descrição e informações da API
No método Startup.Configure , uma ação de configuração passada para o método UseSwagger adiciona
informações como o autor, a licença e a descrição:
// Register the Swagger generator middleware

app.UseSwaggerWithApiExplorer(settings =>
{
settings.PostProcess = document =>
{
document.Info.Version = "v1";
document.Info.Title = "ToDo API";
document.Info.Description = "A simple ASP.NET Core web API";
document.Info.TermsOfService = "None";
document.Info.Contact = new NSwag.SwaggerContact
{
};
document.Info.License = new NSwag.SwaggerLicense
{
};
};
});
A interface do usuário do Swagger exibe as informações da versão:

comentários XML
Os comentários XML podem ser habilitados com as seguintes abordagens:
Visual Studio
Visual Studio Code
Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Editar
<nome_do_projeto>.csproj.
Manualmente, adicione as linhas destacadas ao arquivo .csproj:
<PropertyGroup>
</PropertyGroup>
Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Propriedades
Marque a caixa Arquivo de documentação XML na seção Saída da guia Build
Anotações de dados
O NSwag usa Reflection e o tipo de retorno recomendado para as ações da API Web é IActionResult.
Consequentemente, o NSwag não consegue inferir o que a sua ação está executando e o que ela retorna. Considere
o exemplo a seguir:
[HttpPost]
{
if (item == null)
{
}

}
A ação anterior retorna IActionResult , mas dentro da ação, ela está retornando CreatedAtRoute ou BadRequest.
As anotações de dados são usadas para informar os clientes de quais códigos de status HTTP essa ação deverá
retornar. Decore a ação com os seguintes atributos:
[ProducesResponseType(typeof(TodoItem), 201)] // Created

[ProducesResponseType(400)] // BadRequest
O NSwag usa Reflection e o tipo de retorno recomendado para as ações da API Web é ActionResult<T>.
Consequentemente, o NSwag pode inferir apenas o tipo de retorno definido por T . Outros tipos de retorno
possíveis na ação não podem ser inferidos. Considere o exemplo a seguir:
[HttpPost]
{

}
A ação anterior retorna ActionResult<T> , mas dentro da ação, ela está retornando CreatedAtRoute. Como o
controlador está decorado com o atributo [ApiController], uma resposta BadRequest também é possível. Confira
Respostas automáticas HTTP 400 para obter mais informações. As anotações de dados são usadas para informar
os clientes de quais códigos de status HTTP essa ação deverá retornar. Decore a ação com os seguintes atributos:
[ProducesResponseType(201)] // Created
[ProducesResponseType(400)] // BadRequest
O gerador do Swagger agora pode descrever essa ação precisamente e os clientes gerados conseguem saber o que
recebem ao chamar o ponto de extremidade. É altamente recomendável decorar todas as ações com esses
atributos. Para obter diretrizes sobre quais respostas HTTP as ações da API devem retornar, confira a Especificação
RFC 7231.
Tipos de retorno de ação do controlador na API
Web ASP.NET Core
Por Scott Addie

O ASP.NET Core oferece as seguintes opções para os tipos de retorno da ação do controlador da API Web:
Tipo específico
IActionResult
ActionResult<T>
Tipo específico
IActionResult
Este documento explica quando é mais adequado usar cada tipo de retorno.
Tipo específico
A ação mais simples retorna um tipo de dados complexo ou primitivo (por exemplo, string ou um tipo de
objeto personalizado). Considere a seguinte ação, que retorna uma coleção de objetos Product personalizados:
[HttpGet]
public IEnumerable<Product> Get()
{
return _repository.GetProducts();
}
Sem condições conhecidas contra as quais se proteger durante a execução da ação, retornar um tipo específico
pode ser suficiente. A ação anterior não aceita parâmetros, assim, validação de restrições de parâmetro não é
necessária.
Quando condições conhecidas precisarem ser incluídas em uma ação, vários caminhos de retorno serão
introduzidos. Nesse caso, é comum combinar um tipo de retorno ActionResult com o tipo de retorno primitivo
ou complexo. IActionResult ou ActionResult<T > é necessário para acomodar esse tipo de ação.
Tipo IActionResult
O tipo de retorno IActionResult é apropriado quando vários tipos de retorno ActionResult são possíveis em uma
ação. Os tipos ActionResult representam vários códigos de status HTTP. Alguns tipos de retorno comuns que se
enquadram nessa categoria são BadRequestResult (400) NotFoundResult (404) e OkObjectResult (200).
Porque há vários tipos de retorno e caminhos na ação, o uso liberal do atributo [ProducesResponseType] é
necessário. Esse atributo produz detalhes de resposta mais descritivos para páginas de ajuda da API geradas por
ferramentas como Swagger. [ProducesResponseType] indica os tipos conhecidos e os códigos de status HTTP a
serem retornados pela ação.
Ação síncrona
Considere a seguinte ação síncrona em que há dois tipos de retorno possíveis:
[HttpGet("{id}")]
[ProducesResponseType(200, Type = typeof(Product))]
public IActionResult GetById(int id)
{
if (!_repository.TryGetProduct(id, out var product))
{
return NotFound();
}
return Ok(product);
}
Na ação anterior, um código de status 404 é retornado quando o produto representado por id não existe no
armazenamento de dados subjacente. O método auxiliar NotFound é invocado como um atalho para
return new NotFoundResult(); . Se o produto existir, um objeto Product que representa o conteúdo será
retornado com um código de status 200. O método auxiliar OK é invocado como a forma abreviada de
return new OkObjectResult(product); .
Ação assíncrona
Considere a seguinte ação assíncrona em que há dois tipos de retorno possíveis:
[HttpPost]
[ProducesResponseType(201, Type = typeof(Product))]
public async Task<IActionResult> CreateAsync([FromBody] Product product)
{
{
}
await _repository.AddProductAsync(product);
return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);

}
Na ação anterior, um código de status 400 é retornado quando há falha na validação do modelo e o método
auxiliar BadRequest é invocado. Por exemplo, o modelo a seguir indica que as solicitações devem fornecer a
propriedade Name e um valor. Portanto, a falha em fornecer um Name adequado na solicitação causa falha na
validação de modelo.

{
[Required]

}
O outro código de retorno conhecido da ação anterior é 201, que é gerado pelo método auxiliar
CreatedAtAction. Nesse caminho, o objeto Product é retornado.
Tipo ActionResult<T>
O ASP.NET Core 2.1 apresenta o tipo de retorno ActionResult<T > para ações do controlador de API Web.
Permite que você retorne um tipo derivado de ActionResult ou retorne um tipo específico. ActionResult<T>
oferece os seguintes benefícios em relação ao tipo IActionResult:
O atributo [ProducesResponseType] pode ter sua propriedade Type excluída. Por exemplo,
[ProducesResponseType(200, Type = typeof(Product))] é simplificado para [ProducesResponseType(200)] . O tipo
de retorno esperado da ação é inferido do T em ActionResult<T> .
Operadores de conversão implícita são compatíveis com a conversão de T e ActionResult em
ActionResult<T> . T converte em ObjectResult, o que significa que return new ObjectResult(T); é
simplificado para return T; .
C# não dá suporte a operadores de conversão implícita em interfaces. Consequentemente, a conversão da
interface para um tipo concreto é necessário para usar ActionResult<T> . Por exemplo, o uso de IEnumerable no
exemplo a seguir não funciona:
[HttpGet]
public ActionResult<IEnumerable<Product>> Get()
{
return _repository.GetProducts();
}
Uma opção para corrigir o código anterior é retornar a _repository.GetProducts().ToList(); .

A maioria das ações tem um tipo de retorno específico. Condições inesperadas podem ocorrer durante a
execução da ação, caso em que o tipo específico não é retornado. Por exemplo, o parâmetro de entrada de uma
ação pode falhar na validação do modelo. Nesse caso, é comum retornar o tipo ActionResult adequado, em vez
do tipo específico.
Ação síncrona
Considere uma ação síncrona em que há dois tipos de retorno possíveis:
[HttpGet("{id}")]
public ActionResult<Product> GetById(int id)
{
if (!_repository.TryGetProduct(id, out var product))
{
return NotFound();
}
return product;
}
No código anterior, um código de status 404 é retornado quando o produto não existe no banco de dados. Se o
produto existir, o objeto Product correspondente será retornado. Antes do ASP.NET Core 2.1, a linha
return product; teria sido return Ok(product); .
TIP
Do ASP.NET Core 2.1 em diante, a inferência de origem de associação de parâmetro de ação é habilitada quando uma
classe de controlador é decorada com o atributo [ApiController] . Um nome de parâmetro correspondente a um nome
do modelo de rota é associado automaticamente usando os dados de rota de solicitação. Consequentemente, o parâmetro
id da ação anterior não é explicitamente anotado com o atributo [FromRoute].
Ação assíncrona
Considere uma ação assíncrona em que há dois tipos de retorno possíveis:
[HttpPost]
public async Task<ActionResult<Product>> CreateAsync(Product product)
{
{
}
await _repository.AddProductAsync(product);
return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);

}
Se a validação do modelo falhar, o método BadRequest será chamado para retornar um código de status 400. A
propriedade ModelState que contém os erros de validação específicos que são passados para ela. Se a validação
do modelo for bem-sucedida, o produto será criado no banco de dados. Um código de status 201 é retornado.
TIP
Do ASP.NET Core 2.1 em diante, a inferência de origem de associação de parâmetro de ação é habilitada quando uma
classe de controlador é decorada com o atributo [ApiController] . Parâmetros de tipo complexo são vinculados
automaticamente usando o corpo da solicitação. Consequentemente, o parâmetro product da ação anterior não é
explicitamente anotado com o atributo [FromBody].
Recursos adicionais
Tratar solicitações com controladores no ASP.NET Core MVC
Páginas de ajuda da API Web ASP.NET Core com o Swagger/OpenAPI
Formatar dados de resposta na API Web ASP.NET
Core
Por Steve Smith

O ASP.NET Core MVC tem suporte interno para formatação de dados de resposta, usando formatos fixos ou em
resposta às especificações do cliente.
Resultados da ação específicos a um formato

Alguns tipos de resultado de ação são específicos a um formato específico, como JsonResult e ContentResult .
As ações podem retornar resultados específicos que são sempre formatados de determinada maneira. Por
exemplo, o retorno de um JsonResult retornará dados formatados em JSON, independentemente das
preferências do cliente. Da mesma forma, o retorno de um ContentResult retornará dados de cadeia de
caracteres formatados como texto sem formatação (assim como o simples retorno de uma cadeia de caracteres).
NOTE
Uma ação não precisa retornar nenhum tipo específico; o MVC dá suporte a qualquer valor retornado de objeto. Se uma
ação retorna uma implementação IActionResult e o controlador herda de Controller , os desenvolvedores têm
muitos métodos auxiliares correspondentes a muitas das opções. Os resultados de ações que retornam objetos que não
são tipos IActionResult serão serializados usando a implementação IOutputFormatter apropriada.
Para retornar dados em um formato específico de um controlador que herda da classe base Controller , use o
método auxiliar interno Json para retornar JSON e Content para texto sem formatação. O método de ação
deve retornar o tipo de resultado específico (por exemplo, JsonResult ) ou IActionResult .
Retornando dados formatados em JSON:
// GET: api/authors
[HttpGet]
public JsonResult Get()
{
return Json(_authorRepository.List());
}
Resposta de exemplo desta ação:

Observe que o tipo de conteúdo da resposta é application/json , conforme mostrado na lista de solicitações de
rede e na seção Cabeçalhos de Resposta. Além disso, observe a lista de opções apresentada pelo navegador
(nesse caso, Microsoft Edge) no cabeçalho Accept da seção Cabeçalhos de Solicitação. A técnica atual é ignorar
esse cabeçalho. Abaixo, abordamos como obedecê-lo.
Para retornar dados formatados como texto sem formatação, use ContentResult e o auxiliar Content :
// GET api/authors/about
[HttpGet("About")]
public ContentResult About()
{
return Content("An API listing authors of docs.asp.net.");
}
Uma resposta dessa ação:

Observe, neste caso, que o Content-Type retornado é text/plain . Também obtenha esse mesmo
comportamento usando apenas um tipo de resposta de cadeia de caracteres:
// GET api/authors/version
[HttpGet("version")]
public string Version()
{
return "Version 1.0.0";
}
TIP
Para ações não triviais com vários tipos de retorno ou várias opções (por exemplo, códigos de status HTTP diferentes com
base no resultado das operações executadas), prefira IActionResult como o tipo de retorno.
Negociação de conteúdo
A negociação de conteúdo (conneg de forma abreviada) ocorre quando o cliente especifica um cabeçalho Accept.
O formato padrão usado pelo ASP.NET Core MVC é JSON. A negociação de conteúdo é implementada por
ObjectResult . Ela também foi desenvolvida com base nos resultados de ação específica de código de status
retornados dos métodos auxiliares (que se baseiam em ObjectResult ). Também retorne um tipo de modelo (uma
classe que você definiu como o tipo de transferência de dados) e a estrutura o encapsulará automaticamente em
um ObjectResult para você.
O seguinte método de ação usa os métodos auxiliares Ok e NotFound :
// GET: api/authors/search?namelike=th
[HttpGet("Search")]
public IActionResult Search(string namelike)
{
var result = _authorRepository.GetByNameSubstring(namelike);
if (!result.Any())
{
return NotFound(namelike);
}
return Ok(result);
}
Uma resposta formatada em JSON será retornada, a menos que outro formato tenha sido solicitado e o servidor
possa retornar o formato solicitado. Use uma ferramenta como o Fiddler para criar uma solicitação que inclui um
cabeçalho Accept e especifique outro formato. Nesse caso, se o servidor tiver um formatador que pode produzir
uma resposta no formato solicitado, o resultado será retornado no formato preferencial do cliente.
Na captura de tela acima, o Fiddler Composer foi usado para gerar uma solicitação, especificando
Accept: application/xml . Por padrão, o ASP.NET Core MVC dá suporte apenas ao JSON e, portanto, mesmo
quando outro formato é especificado, o resultado retornado ainda é formatado em JSON. Você verá como
adicionar outros formatadores na próxima seção.
As ações do controlador podem retornar POCOs (Objetos CLR Básicos); nesse caso, o ASP.NET Core MVC
criará automaticamente um ObjectResult que encapsula o objeto. O cliente receberá o objeto serializado
formatado (o formato JSON é o padrão; você pode configurar XML ou outros formatos). Se o objeto que está
sendo retornado for null , a estrutura retornará uma resposta 204 No Content .
Retornando um tipo de objeto:
// GET api/authors/ardalis
[HttpGet("{alias}")]
public Author Get(string alias)
{
return _authorRepository.GetByAlias(alias);
}
Na amostra, uma solicitação para um alias de autor válido receberá uma resposta 200 OK com os dados do
autor. Uma solicitação para um alias inválido receberá uma resposta 204 Sem Conteúdo. Capturas de tela
mostrando a resposta nos formatos XML e JSON são mostradas abaixo.
Processo de negociação de conteúdo
A negociação de conteúdo ocorre apenas se um cabeçalho Accept é exibido na solicitação. Quando uma
solicitação contiver um cabeçalho Accept, a estrutura enumerará os tipos de mídia no cabeçalho Accept na ordem
de preferência e tentará encontrar um formatador que pode produzir uma resposta em um dos formatos
especificados pelo cabeçalho Accept. Caso nenhum formatador que pode atender à solicitação do cliente seja
encontrado, a estrutura tentará encontrar o primeiro formatador que pode produzir uma resposta (a menos que
o desenvolvedor tenha configurado a opção em MvcOptions para retornar 406 Não Aceitável). Se a solicitação
especificar XML, mas o formatador XML não tiver sido configurado, o formatador JSON será usado. Geralmente,
se nenhum formatador que pode fornecer o formato solicitado for configurado, o primeiro formatador que pode
formatar o objeto será usado. Se nenhum cabeçalho for fornecido, o primeiro formatador que pode manipular o
objeto a ser retornado será usado para serializar a resposta. Nesse caso, não ocorre nenhuma negociação – o
servidor determina qual formato será usado.
NOTE
Se o cabeçalho Accept contiver */* , o Cabeçalho será ignorado, a menos que RespectBrowserAcceptHeader seja
definido como verdadeiro em MvcOptions .
Navegadores e negociação de conteúdo

Ao contrário dos clientes de API típicos, os navegadores da Web tendem a fornecer cabeçalhos Accept que
incluem uma ampla variedade de formatos, incluindo caracteres curinga. Por padrão, quando a estrutura detectar
que a solicitação é proveniente de um navegador, ela ignorará o cabeçalho Accept e retornará o conteúdo no
formato padrão configurado do aplicativo (JSON, a menos que outro formato seja configurado). Isso fornece
uma experiência mais consistente no uso de diferentes navegadores para consumir APIs.
Se preferir que o aplicativo respeite os cabeçalhos Accept do navegador, defina isso como parte da configuração
do MVC definindo RespectBrowserAcceptHeader como true no método ConfigureServices em Startup.cs.
{
options.RespectBrowserAcceptHeader = true; // false by default
});
Configurando formatadores
Se o aplicativo precisar dar suporte a outros formatos além do padrão de JSON, adicione pacotes NuGet e
configure o MVC para dar suporte a eles. Há formatadores separados para entrada e saída. Os formatadores de
entrada são usados pelo Model Binding; os formatadores de saída são usados para formatar as respostas.
Também configure Formatadores Personalizados.
Adicionando suporte para o formato XML
Para adicionar suporte para a formatação XML, instale o pacote NuGet Microsoft.AspNetCore.Mvc.Formatters.Xml .
Adicione os XmlSerializerFormatters à configuração do MVC em Startup.cs:
services.AddMvc()
.AddXmlSerializerFormatters();
Como alternativa, você pode adicionar apenas o formatador de saída:
{
options.OutputFormatters.Add(new XmlSerializerOutputFormatter());
});
Essas duas abordagens serializarão os resultados usando System.Xml.Serialization.XmlSerializer . Se preferir,

use o System.Runtime.Serialization.DataContractSerializer adicionando seu formatador associado:
{
options.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter());
});
Depois de adicionar suporte para a formatação XML, os métodos do controlador deverão retornar o formato
apropriado com base no cabeçalho Accept da solicitação, como demonstra este exemplo do Fiddler:
Na guia Inspetores, é possível ver que a solicitação GET Bruta foi feita com um conjunto de cabeçalhos
Accept: application/xml . O painel de resposta mostra o cabeçalho Content-Type: application/xml e o objeto
Author foi serializado em XML.
Use a guia Criador para modificar a solicitação para especificar application/json no cabeçalho Accept . Execute
a solicitação e a resposta será formatada como JSON:
Nessa captura de tela, é possível ver a solicitação definir um cabeçalho Accept: application/json e a resposta
especificar o mesmo como seu Content-Type . O objeto Author é mostrado no corpo da resposta, em formato
JSON.
Forçando um formato específico
Caso deseje restringir os formatos de resposta de uma ação específica, aplique o filtro [Produces] . O filtro
[Produces] especifica os formatos de resposta de uma ação específica (ou o controlador ). Como a maioria dos
Filtros, isso pode ser aplicado no escopo da ação, do controlador ou global.
public class AuthorsController
O filtro [Produces] forçará todas as ações em AuthorsController a retornar respostas formatadas em JSON,
mesmo se outros formatadores foram configurados para o aplicativo e o cliente forneceu um cabeçalho Accept
solicitando outro formato disponível. Consulte Filtros para saber mais, incluindo como aplicar filtros
globalmente.
Formatadores de casos especiais
Alguns casos especiais são implementados com formatadores internos. Por padrão, os tipos de retorno string
serão formatados como text/plain (text/html, se solicitado por meio do cabeçalho Accept ). Esse comportamento
pode ser removido com a remoção do TextOutputFormatter . Remova formatadores no método Configure em
Startup.cs (mostrado abaixo). Ações que têm um tipo de retorno de objeto de modelo retornarão uma resposta
204 Sem Conteúdo ao retornar null . Esse comportamento pode ser removido com a remoção do
HttpNoContentOutputFormatter . O código a seguir remove o TextOutputFormatter e o
HttpNoContentOutputFormatter .
{
options.OutputFormatters.RemoveType<TextOutputFormatter>();
options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
});
Sem o TextOutputFormatter , os tipos de retorno string retornam 406 Não Aceitável, por exemplo. Observe que
se um formatador XML existir, ele formatará tipos de retorno string se o TextOutputFormatter for removido.
Sem o HttpNoContentOutputFormatter , os objetos nulos são formatados com o formatador configurado. Por
exemplo, o formatador JSON apenas retornará uma resposta com um corpo null , enquanto o formatador XML
retornará um elemento XML vazio com o atributo xsi:nil="true" definido.
Mapeamentos de URL do formato da resposta

Os clientes podem solicitar um formato específico como parte da URL, como na cadeia de caracteres de consulta
ou parte do caminho, ou usando uma extensão de arquivo específica a um formato, como .xml ou .json. O
mapeamento do caminho da solicitação deve ser especificado na rota que está sendo usada pela API. Por
exemplo:
[FormatFilter]
public class ProductsController
{
[Route("[controller]/[action]/{id}.{format?}")]
public Product GetById(int id)
Essa rota permitirá que o formato solicitado seja especificado como uma extensão de arquivo opcional. O
atributo [FormatFilter] verifica a existência do valor de formato no RouteData e mapeará o formato da resposta
para o formatador adequado quando a resposta for criada.
ROTA FORMATADOR
/products/GetById/5 O formatador de saída padrão
/products/GetById/5.json O formatador JSON (se configurado)

ROTA FORMATADOR
/products/GetById/5.xml O formatador XML (se configurado)

Formatadores personalizados na API Web ASP.NET
Core
Por Tom Dykstra

O ASP.NET Core MVC tem suporte interno para troca de dados em APIs Web usando formatos de texto sem
formatação, XML ou JSON. Este artigo mostra como adicionar suporte para formatos adicionais criando
formatadores personalizados.
Quando usar formatadores personalizados

Use um formatador personalizado quando quiser que o processo de negociação de conteúdo dê suporte a um
tipo de conteúdo que não tem suporte dos formatadores internos (JSON, XML e texto sem formatação).
Por exemplo, se alguns dos clientes de sua API Web puderem usar o formato Protobuf, talvez você queira usar
Protobuf com esses clientes porque é mais eficiente. Ou talvez você queira que sua API Web envie endereços e
nomes de contato no formato vCard, um formato usado normalmente para troca de dados de contato. O
aplicativo de exemplo fornecido com este artigo implementa um formatador vCard simples.
Visão geral de como usar um formatador personalizado

Estas são as etapas para criar e usar um formatador personalizado:
Criar uma classe de formatador de saída se quiser serializar os dados a serem enviados ao cliente.
Criar uma classe de formatador de entrada se quiser desserializar os dados recebidos do cliente.
Adicionar instâncias de seus formatadores às coleções InputFormatters e OutputFormatters em MvcOptions.
As seções a seguir fornecem diretrizes e exemplos de código para cada uma dessas etapas.
Como criar uma classe de formatador personalizado

Para criar um formatador:
Derive a classe da classe base apropriada.
Especifique codificações e tipos de mídia válidos no construtor.
Substitua os métodos CanReadType / CanWriteType
Substitua os métodos ReadRequestBodyAsync / WriteResponseBodyAsync
Derivar da classe base apropriada
Para tipos de mídia de texto (por exemplo, vCard), derive da classe base TextInputFormatter ou
TextOutputFormatter.
public class VcardOutputFormatter : TextOutputFormatter
Para tipos binários, derive da classe base InputFormatter ou OutputFormatter.

Especifique codificações e tipos de mídia válidos
No construtor, especifique codificações e tipos de mídia válidos adicionando-os às coleções SupportedMediaTypes
e SupportedEncodings .
public VcardOutputFormatter()
{
SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/vcard"));
SupportedEncodings.Add(Encoding.UTF8);
SupportedEncodings.Add(Encoding.Unicode);
}
NOTE
Não é possível fazer a injeção de dependência de construtor em uma classe de formatador. Por exemplo, não é possível
obter um agente adicionando um parâmetro de agente ao construtor. Para acessar serviços, você precisa usar o objeto de
contexto que é passado para seus métodos. O exemplo de código abaixo mostra como isso é feito.
Substituir CanReadType/CanWriteType
Especifique o tipo no qual desserializar ou do qual serializar substituindo os métodos CanReadType ou
CanWriteType . Por exemplo, talvez você só possa criar texto de vCard de um tipo Contact e vice-versa.
protected override bool CanWriteType(Type type)

{
if (typeof(Contact).IsAssignableFrom(type)
|| typeof(IEnumerable<Contact>).IsAssignableFrom(type))
{
return base.CanWriteType(type);
}
return false;
}
O método CanWriteResult
Em alguns cenários, você precisa substituir CanWriteResult em vez de CanWriteType . Use CanWriteResult se as
condições a seguir forem verdadeiras:
O método de ação retorna uma classe de modelo.
Há classes derivadas que podem ser retornadas em tempo de execução.
Você precisa saber em tempo de execução qual classe derivada foi retornada pela ação.
Por exemplo, suponha que sua assinatura do método de ação retorne um tipo Person , mas ele pode retornar um
tipo Student ou Instructor que deriva de Person . Se você quiser que o formatador trate apenas de objetos
Student , verifique o tipo de Objeto no objeto de contexto fornecido ao método CanWriteResult . Observe que
não é necessário usar CanWriteResult quando o método de ação retorna IActionResult ; nesse caso, o método
CanWriteType recebe o tipo de tempo de execução.
Substituir ReadRequestBodyAsync/WriteResponseBodyAsync
Você faz o trabalho real de desserialização ou serialização em ReadRequestBodyAsync ou WriteResponseBodyAsync .
As linhas destacadas no exemplo a seguir mostram como obter serviços do contêiner de injeção de dependência
(não é possível obtê-los dos parâmetros do construtor).
public override Task WriteResponseBodyAsync(OutputFormatterWriteContext context, Encoding selectedEncoding)
{
IServiceProvider serviceProvider = context.HttpContext.RequestServices;
var logger = serviceProvider.GetService(typeof(ILogger<VcardOutputFormatter>)) as ILogger;
var response = context.HttpContext.Response;
var buffer = new StringBuilder();

if (context.Object is IEnumerable<Contact>)
{
foreach (Contact contact in context.Object as IEnumerable<Contact>)
{
FormatVcard(buffer, contact, logger);
}
}
else
{
var contact = context.Object as Contact;
FormatVcard(buffer, contact, logger);
}
return response.WriteAsync(buffer.ToString());
}
private static void FormatVcard(StringBuilder buffer, Contact contact, ILogger logger)

{
buffer.AppendLine("BEGIN:VCARD");
buffer.AppendLine("VERSION:2.1");
buffer.AppendFormat($"N:{contact.LastName};{contact.FirstName}\r\n");
buffer.AppendFormat($"FN:{contact.FirstName} {contact.LastName}\r\n");
buffer.AppendFormat($"UID:{contact.ID}\r\n");
buffer.AppendLine("END:VCARD");
logger.LogInformation($"Writing {contact.FirstName} {contact.LastName}");
}
Como configurar o MVC para usar um formatador personalizado

Para usar um formatador personalizado, adicione uma instância da classe de formatador à coleção
InputFormatters ou OutputFormatters .
{
options.InputFormatters.Insert(0, new VcardInputFormatter());
options.OutputFormatters.Insert(0, new VcardOutputFormatter());
});
Formatadores são avaliados na ordem em que você os insere. O primeiro deles tem precedência.
Próximas etapas
Veja o aplicativo de exemplo, que implementa formatadores de entrada e saída simples de vCard. O aplicativo lê e
grava vCards parecidos com o exemplo a seguir:
BEGIN:VCARD
VERSION:2.1
N:Davolio;Nancy
FN:Nancy Davolio
UID:20293482-9240-4d68-b475-325df4a83728
END:VCARD
Para ver a saída do vCard, execute o aplicativo e envie uma solicitação Get com o cabeçalho de aceitação
"texto/vcard" para http://localhost:63313/api/contacts/ (ao executar com Visual Studio) ou
http://localhost:5000/api/contacts/ (ao executar da linha de comando).
Para adicionar um vCard à coleção de contatos na memória, envie uma solicitação Post para a mesma URL, com
cabeçalho Content-Type "texto/vcard" e com o texto do vCard no corpo, formatado como o exemplo acima.
Introdução ao SignalR do ASP.NET Core
O que é o SignalR?
SignalR do ASP.NET Core é uma biblioteca de software livre que simplifica a adição da funcionalidade da web
em tempo real aos aplicativos. A funcionalidade da web em tempo real permite que o código do lado do servidor
para conteúdo de envio por push aos clientes instantaneamente.
Bons candidatos para o SignalR:
Aplicativos que exigem atualizações de alta frequência do servidor. Exemplos são jogos, redes sociais, de
votação, leilão, mapas e aplicativos GPS.
Os painéis e monitoramento de aplicativos. Exemplos incluem painéis da empresa, atualizações de vendas
instantâneas, ou alertas de viagem.
Aplicativos de colaboração. Quadro de comunicações aplicativos e software de reunião de equipe são
exemplos de aplicativos de colaboração.
Aplicativos que exigem as notificações. Redes sociais, email, bate-papo, jogos, alertas de viagem e muitos
outros aplicativos usam notificações.
O SignalR fornece uma API para a criação de servidor para cliente chamadas de procedimento remoto (RPC ). As
RPCs chamam funções JavaScript em clientes do código do lado do servidor do .NET Core.
Aqui estão alguns recursos do SignalR para ASP.NET Core:
Lida com gerenciamento de conexão automaticamente.
Envia mensagens para todos os clientes conectados simultaneamente. Por exemplo, uma sala de bate-papo.
Envia mensagens para clientes específicos ou grupos de clientes.
É dimensionada para lidar com o aumento de tráfego.
A fonte é hospedada em um SignalR repositório no GitHub.
Transportes
O SignalR dá suporte a várias técnicas para manipular as comunicações em tempo real:
WebSockets
Eventos enviados pelo servidor
Sondagem longa
O SignalR escolhe automaticamente o melhor método de transporte que está dentro de recursos do servidor e
cliente.
Hubs
Usa o SignalR hubs para comunicação entre clientes e servidores.
Um hub é um pipeline de alto nível que permite que um cliente e servidor chamar métodos em si. O SignalR
manipula a expedição entre limites de máquina automaticamente, permitindo que os clientes chamar métodos no
servidor e vice-versa. Você pode passar parâmetros fortemente tipados para métodos, que habilita a associação
de modelo. O SignalR fornece dois protocolos de hub interno: um protocolo de texto com base em JSON e um
protocolo binário, com base em MessagePack. MessagePack geralmente cria mensagens menores em
comparação comparadas JSON. Devem dar suporte a navegadores mais antigos nível XHR 2 para fornecer
suporte de protocolo MessagePack.
Os hubs de chamar o código do lado do cliente enviando mensagens que contêm o nome e parâmetros do
método do lado do cliente. Os objetos enviados como parâmetros de método são desserializados usando o
protocolo configurado. O cliente tenta corresponder o nome a um método no código do lado do cliente. Quando
o cliente encontra uma correspondência, ele chama o método e passa a ele os dados de parâmetro desserializado.
Recursos adicionais
Introdução ao SignalR para ASP.NET Core
Plataformas com suporte
Hubs
Cliente JavaScript
Plataformas com suporte do SignalR do ASP.NET
Core
Requisitos de sistema do servidor

SignalR para ASP.NET Core dá suporte a qualquer plataforma de servidor que dá suporte ao ASP.NET Core.
Cliente JavaScript
O cliente JavaScript é executado no NodeJS 8 e versões posteriores e os seguintes navegadores:
NAVEGADOR VERSÃO
Microsoft Edge atual
Mozilla Firefox atual
Google Chrome; inclui o Android atual
Safari; inclui o iOS atual
Microsoft Internet Explorer 11
Cliente .NET
O cliente .NET é executado em qualquer plataforma de servidor com suporte pelo ASP.NET Core.
Se o servidor executa o IIS, o transporte de WebSockets requer o IIS 8.0 ou superior no Windows Server 2012 ou
superior. Outros transportes têm suporte em todas as plataformas.
Cliente de Java
O cliente Java dá suporte a Java 8 e versões posteriores.
Não há suporte para clientes

Os clientes a seguir estão disponíveis, mas são experimentais ou não oficial. Eles não têm suporte no momento e
nunca podem ser.
Cliente C++
Cliente SWIFT
Tutorial: introdução ao SignalR para ASP.NET Core
Este tutorial ensina as noções básicas da criação de um aplicativo em tempo real usando o SignalR. Você
aprenderá como:
Crie um projeto Web.
Adicione o código que envia mensagens de qualquer cliente para todos os clientes conectados.
No final, você terá um aplicativo de chat funcionando:
Pré-requisitos
Visual Studio
Visual Studio Code
Visual Studio 2017 versão 15.8 ou posterior com a carga de trabalho ASP.NET e desenvolvimento para a
Web
Criar um projeto Web

Visual Studio
Visual Studio Code
No menu, selecione Arquivo > Novo Projeto.
Na caixa de diálogo Novo Projeto, selecione Instalado > Visual C# > Web > Aplicativo Web
ASP.NET Core. Dê ao projeto o nome de SignalRChat.
Selecione Aplicativo Web para criar um projeto que usa Razor Pages.
Selecione uma estrutura de destino do .NET Core, selecione ASP.NET Core 2.1 e clique em OK.
Adicionar a biblioteca de clientes do SignalR

A biblioteca do servidor SignalR está incluída no metapacote Microsoft.AspNetCore.App . A biblioteca de clientes
do JavaScript não é incluída automaticamente no projeto. Neste tutorial, você usará o LibMan (Library Manager)
para obter a biblioteca de clientes de unpkg. unpkg é uma CDN (rede de distribuição de conteúdo) que pode
distribuir qualquer conteúdo do npm, o gerenciador de pacotes do Node.js.
Visual Studio
Visual Studio Code
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Adicionar >
Biblioteca do Lado do Cliente.
Na caixa de diálogo Adicionar Biblioteca do Lado do Cliente, para Provedor, selecione unpkg.
Para Biblioteca, insira @aspnet/signalr@1 e selecione a versão mais recente que não seja uma versão
prévia.
Selecione Escolher arquivos específicos, expanda a pasta distribuidor/navegador e selecione signalr.js e

signalr.min.js.
Defina Localização de Destino como wwwroot/lib/signalr/ e selecione Instalar.
O LibMan cria uma pasta wwwroot/lib/signalr e copia os arquivos selecionados para ela.
Criar um hub do SignalR

Um hub é uma classe que funciona como um pipeline de alto nível que lida com a comunicação entre cliente e
servidor.
Na pasta do projeto SignalRChat, crie uma pasta Hubs.
Na pasta Hubs, crie um arquivo ChatHub.cs com o código a seguir:
namespace SignalRChat.Hubs
{
{
{
}
}
}
A classe ChatHub é herda da classe Hub do SignalR. A classe Hub gerencia conexões, grupos e sistemas
de mensagens.
O método SendMessage pode ser chamado por qualquer cliente conectado. Ele envia a mensagem recebida
para todos os clientes. O código do SignalR é assíncrono para fornecer o máximo de escalabilidade.
Configurar o SignalR
O servidor do SignalR precisa ser configurado para passar solicitações do SignalR ao SignalR.
Adicione o seguinte código realçado ao arquivo Startup.cs.
{
{
{
}
{
{
// This lambda determines whether user consent for non-essential cookies is needed for
a given request.
});
}
pipeline.
{
{
}
else
{
app.UseHsts();
}
{
});
app.UseMvc();
}
}
}
Essas alterações adicionam o SignalR ao sistema de injeção de dependência e ao pipeline do middleware

do ASP.NET Core.
Adicionar o código de cliente do SignalR
Substitua o conteúdo Pages\Index.cshtml pelo código a seguir:
@page
<div class="row"> </div>
<div class="row">
<div class="col-6">
User..........<input type="text" id="userInput" />
<br />
Message...<input type="text" id="messageInput" />
<input type="button" id="sendButton" value="Send Message" />
</div>
</div>
<div class="row">
<div class="col-12">
<hr />
</div>
</div>
<div class="row">
<div class="col-6">
<ul id="messagesList"></ul>
</div>
</div>
</div>
<script src="~/lib/signalr/dist/browser/signalr.js"></script>
<script src="~/js/chat.js"></script>
O código anterior:
Cria as caixas de texto para o nome e a mensagem de texto e um botão Enviar.
Cria uma lista com id="messagesList" para exibir as mensagens recebidas do hub do SignalR.
Inclui referências de script ao SignalR e ao código do aplicativo chat.js que você criará na próxima
etapa.
Na pasta wwwroot/js, crie um arquivo chat.js com o código a seguir:
"use strict";
var connection = new signalR.HubConnectionBuilder().withUrl("/chatHub").build();
connection.on("ReceiveMessage", function (user, message) {

var msg = message.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
var encodedMsg = user + " says " + msg;
});
connection.start().catch(function (err) {
});
document.getElementById("sendButton").addEventListener("click", function (event) {

var user = document.getElementById("userInput").value;
var message = document.getElementById("messageInput").value;
connection.invoke("SendMessage", user, message).catch(function (err) {
});
event.preventDefault();
});
O código anterior:
Cria e inicia uma conexão.
Adiciona no botão Enviar um manipulador que envia mensagens ao hub.
Adiciona no objeto de conexão um manipulador que recebe mensagens do hub e as adiciona à lista.
Visual Studio
Visual Studio Code
Pressione CTRL + F5 para executar o aplicativo sem depuração.
Copie a URL da barra de endereços, abra outra instância ou guia do navegador e cole a URL na barra de
endereços.
Escolha qualquer navegador, insira um nome e uma mensagem e selecione o botão Enviar.
O nome e a mensagem são exibidos em ambas as páginas instantaneamente.
TIP
Se o aplicativo não funcionar, abra as ferramentas para desenvolvedores do navegador (F12) e acesse o console. Você pode
encontrar erros relacionados ao código HTML e JavaScript. Por exemplo, suponha que você coloque signalr.js em uma pasta
diferente daquela direcionada. Nesse caso, a referência a esse arquivo não funcionará e ocorrerá um erro 404 no console.
Próximas etapas
Adicionar o código que usa o hub para enviar mensagens de qualquer cliente para todos os clientes
conectados.
Para saber mais sobre o SignalR, confira a introdução:
Introdução ao ASP.NET Core SignalR
Webpack

em TypeScript.
Pré-requisitos
Visual Studio
CLI do .NET Core
Node.js com npm
a Web

Visual Studio
CLI do .NET Core
2. Selecione a entrada $ (PATH ) na lista. Clique na seta para cima para mover a entrada para a segunda posição
da lista. Como uma reserva, a primeira entrada se refere aos pacotes locais do projeto.

cliente.
npm init -y
{
"version": "1.0.0",
"private": true,
"description": "",
"main": "index.js",
"scripts": {
},
"keywords": [],
"author": "",
"license": "ISC"
}

recentes.
"scripts": {
},

module.exports = {
output: {
publicPath: "/"
},
resolve: {
},
module: {
rules: [
{
test: /\.ts$/,
use: "ts-loader"
},
{
test: /\.css$/,
}
]
},
plugins: [
}),
})
]
};

wwwroot.
projeto.
<!DOCTYPE html>
<html>
<head>
</head>
<body>
</div>
</div>
</body>
</html>

}
html, body {
margin: 0;
padding: 0;
}
.input-zone {
display: flex;
margin: 10px;
}
.input-zone-input {
flex: 1;
margin-right: 10px;
}
.message-author {
font-weight: bold;
}
.messages {
margin: 10px;
max-height: 300px;
min-height: 300px;
overflow-y: auto;
padding: 5px;
}

{
"target": "es5"
}
}
ECMAScript 5.


send();
}
});
function send() {
}

Startup.Configure :
{
});
{
{
}
}

para o servidor.


.withUrl("/hub")
.build();

m.innerHTML =
});

send();
}
});
function send() {
}

específica por meio da função on . Você pode escutar qualquer número de nomes de mensagem. Também é
possível passar parâmetros para a mensagem, como o nome do autor e o conteúdo da mensagem recebida.
Quando o cliente recebe a mensagem, um novo elemento div é criado com o nome do autor e o conteúdo
da mensagem em seu atributo innerHTML . Ele é adicionado ao elemento principal div que exibe as
mensagens.


.withUrl("/hub")
.build();

});

send();
}
});
function send() {
}
{
{
{
}
}
}
Testar o aplicativo
Visual Studio
CLI do .NET Core
npm run release
Recursos adicionais
Usar os hubs no SignalR do ASP.NET Core
Por Rachel Appel e Kevin Griffin

Exibir ou baixar o código de exemplo (como fazer o download)
O que é um hub SignalR

A API de Hubs de SignalR permite chamar métodos em clientes conectados do servidor. No código do servidor,
você define métodos que são chamados pelo cliente. O código do cliente, você define métodos que são
chamados do servidor. SignalR cuida de tudo o que nos bastidores que possibilita a comunicação de servidor
para cliente e servidor-cliente em tempo real.
Configurar os hubs de SignalR

O middleware SignalR requer alguns serviços, que são configurados por meio da chamada services.AddSignalR
.
Ao adicionar a funcionalidade do SignalR para um aplicativo ASP.NET Core, configurar as rotas do SignalR
chamando app.UseSignalR no Startup.Configure método.
app.UseSignalR(route =>
{
route.MapHub<ChatHub>("/chathub");
});
Criar e usar os hubs

Criar um hub, declarando uma classe que herda de Hub e adicione os métodos públicos a ele. Os clientes
poderão chamar métodos que são definidos como public .
{
{
await Clients.All.SendAsync("ReceiveMessage", user,message);
}
public Task SendMessageToCaller(string message)

{
return Clients.Caller.SendAsync("ReceiveMessage", message);
}
public Task SendMessageToGroups(string message)

{
List<string> groups = new List<string>() { "SignalR Users" };
return Clients.Groups(groups).SendAsync("ReceiveMessage", message);
}
public override async Task OnConnectedAsync()

{
await Groups.AddToGroupAsync(Context.ConnectionId, "SignalR Users");
await base.OnConnectedAsync();
}
public override async Task OnDisconnectedAsync(Exception exception)

{
await Groups.RemoveFromGroupAsync(Context.ConnectionId, "SignalR Users");
await base.OnDisconnectedAsync(exception);
}
}
Você pode especificar um tipo de retorno e parâmetros, incluindo tipos complexos e matrizes, como você faria
em qualquer método em c#. O SignalR lida com a serialização e desserialização de objetos complexos e matrizes
em seus valores de retorno e parâmetros.
O objeto de contexto
O Hub classe tem um Context propriedade que contém as propriedades a seguir com informações sobre a
conexão:
ConnectionId Obtém a ID exclusiva para a conexão, atribuído pelo SignalR.

Há uma ID de conexão para cada conexão.
UserIdentifier Obtém o identificador de usuário. Por padrão, o SignalR usa

o ClaimTypes.NameIdentifier do ClaimsPrincipal
associado com a conexão como o identificador de usuário.
User Obtém o ClaimsPrincipal associado ao usuário atual.
Items Obtém uma coleção de chave/valor que pode ser usada para
compartilhar dados dentro do escopo dessa conexão. Dados
podem ser armazenados nessa coleção e ela será mantida
para a conexão entre as invocações de método de hub
diferentes.
Features Obtém a coleção de recursos disponíveis sobre a conexão.

Por enquanto, essa coleção não é necessária na maioria dos
cenários, portanto, ele ainda não está documentado em
detalhes.
ConnectionAborted Obtém um CancellationToken que notifica quando a

conexão será anulada.
Hub.Context também contém os seguintes métodos:
MÉTODO DESCRIÇÃO
GetHttpContext Retorna o HttpContext para a conexão, ou null se a

conexão não está associado uma solicitação HTTP. Para
conexões HTTP, você pode usar esse método para obter
informações como cadeias de caracteres de consulta e
cabeçalhos HTTP.
Abort Anula a conexão.
O objeto de clientes
O Hub classe tem um Clients propriedade que contém as seguintes propriedades para a comunicação entre
cliente e servidor:
All Chama um método em todos os clientes conectados
Caller Chama um método no cliente que invocou o método de hub
Others Chama um método em todos os clientes conectados, exceto

o cliente que invocou o método
Hub.Clients também contém os seguintes métodos:
MÉTODO DESCRIÇÃO
AllExcept Chama um método em todos os clientes conectados, exceto

para as conexões especificadas
Client Chama um método em um cliente conectado específico
Clients Chama um método em clientes conectados específicos
Group Chama um método para todas as conexões no grupo

especificado
GroupExcept Chama um método para todas as conexões do grupo

especificado, exceto as conexões especificadas
Groups Chama um método para vários grupos de conexões

MÉTODO DESCRIÇÃO
OthersInGroup Chama um método a um grupo de conexões, excluindo o

cliente que invocou o método de hub
User Chama um método para todas as conexões associadas a um

usuário específico
Users Chama um método para todas as conexões associadas com

os usuários especificados
Cada propriedade ou método nas tabelas anteriores retorna um objeto com um SendAsync método. O
SendAsync método permite que você forneça o nome e parâmetros do método de cliente para chamar.
Enviar mensagens para os clientes

Para fazer chamadas para clientes específicos, use as propriedades do Clients objeto. No exemplo a seguir, o
SendMessageToCaller método demonstra como enviar uma mensagem para a conexão que invocou o método de
hub. O SendMessageToGroups método envia uma mensagem para os grupos armazenados em um List
denominado groups .

{
return Clients.Caller.SendAsync("ReceiveMessage", message);
}
public Task SendMessageToGroups(string message)

{
List<string> groups = new List<string>() { "SignalR Users" };
return Clients.Groups(groups).SendAsync("ReceiveMessage", message);
}
Hubs com rigidez de tipos

Uma desvantagem de usar SendAsync é que ele se baseia em uma cadeia de caracteres mágica para especificar
o método de cliente a ser chamado. Isso deixa o código aberto para erros de tempo de execução se o nome do
método está incorreto ou ausente do cliente.
Uma alternativa ao uso SendAsync é tipar fortemente os Hub com Hub<T>. No exemplo a seguir, o ChatHub
métodos de cliente foram extraídos por em uma interface chamada IChatClient .
public interface IChatClient

{
Task ReceiveMessage(string user, string message);
Task ReceiveMessage(string message);
}
Essa interface pode ser usada para refatorar anterior ChatHub exemplo.
public class StronglyTypedChatHub : Hub<IChatClient>
{
{
await Clients.All.ReceiveMessage(user, message);
}

{
return Clients.Caller.ReceiveMessage(message);
}
}
Usando Hub<IChatClient> habilita a verificação de tempo de compilação dos métodos do cliente. Isso evita
problemas causados pelo uso de cadeias de caracteres mágicas desde Hub<T> só pode fornecer acesso aos
métodos definidos na interface.
Usando fortemente tipado Hub<T> desabilita a capacidade de usar SendAsync .
Manipular eventos para uma conexão

A API de Hubs de SignalR fornece o OnConnectedAsync e OnDisconnectedAsync métodos virtuais para gerenciar e
controlar conexões. Substituir o OnConnectedAsync método virtual para executar ações quando um cliente se
conecta ao Hub, como adicioná-lo a um grupo.
public override async Task OnConnectedAsync()

{
await Groups.AddToGroupAsync(Context.ConnectionId, "SignalR Users");
await base.OnConnectedAsync();
}
public override async Task OnDisconnectedAsync(Exception exception)

{
await Groups.RemoveFromGroupAsync(Context.ConnectionId, "SignalR Users");
await base.OnDisconnectedAsync(exception);
}
Tratar erros
As exceções geradas em seus métodos de hub são enviadas ao cliente que invocou o método. No cliente
JavaScript, o invoke método retorna um promessa JavaScript. Quando o cliente recebe um erro com um
manipulador anexado à promessa usando catch , ele tem chamado e passado como um JavaScript Error
objeto.
connection.invoke("SendMessage", user, message).catch(err => console.error(err));
Recursos relacionados
Introdução ao SignalR do ASP.NET Core
Cliente JavaScript
Publicar no Azure
Enviar mensagens de fora de um hub
Por Mikael Mengistu

O hub do SignalR é a abstração central para enviar mensagens para os clientes conectados ao servidor SignalR.
Também é possível enviar mensagens de outros lugares no seu aplicativo usando o IHubContext service. Este
artigo explica como acessar um SignalR IHubContext para enviar notificações para clientes externos um hub.
Obtenha uma instância de IHubContext

No SignalR do ASP.NET Core, você pode acessar uma instância de IHubContext por meio da injeção de
dependência. Você pode injetar uma instância do IHubContext em um controlador, middleware ou outro serviço de
injeção de dependência. Use a instância para enviar mensagens para os clientes.
NOTE
Isso é diferente do ASP.NET 4.x SignalR que usado GlobalHost para fornecer acesso ao IHubContext . O ASP.NET Core tem
uma estrutura de injeção de dependência que remove a necessidade de neste singleton global.
Injetar uma instância do IHubContext em um controlador

Você pode injetar uma instância do IHubContext em um controlador, adicionando-o para seu construtor:

{
private readonly IHubContext<NotificationHub> _hubContext;
public HomeController(IHubContext<NotificationHub> hubContext)

{
_hubContext = hubContext;
}
}
Agora, com acesso a uma instância de IHubContext , você pode chamar métodos de hub, como se estivessem no
próprio hub.

{
await _hubContext.Clients.All.SendAsync("Notify", $"Home page loaded at: {DateTime.Now}");
return View();
}
Obtenha uma instância de IHubContext no middleware

Acesso a IHubContext dentro do pipeline de middleware da seguinte forma:
app.Use(next => async (context) =>
{
var hubContext = context.RequestServices
.GetRequiredService<IHubContext<MyHub>>();
//...
});
NOTE
Quando os métodos de hub são chamados de fora do Hub de classe, não há nenhum chamador associado com a invocação.
Portanto, não há nenhum acesso para o ConnectionId , Caller , e Others propriedades.
Injetar um HubContext fortemente tipados

Para injetar um HubContext fortemente tipadas, certifique-se de seu Hub herda de Hub<T> . Injetá-lo usando o
IHubContext<THub, T> interface em vez de IHubContext<THub> .
public class ChatController : Controller

{
public IHubContext<ChatHub, IChatClient> _strongChatHubContext { get; }
public SampleDataController(IHubContext<ChatHub, IChatClient> chatHubContext)

{
_strongChatHubContext = chatHubContext;
}
public async Task SendMessage(string message)

{
await _strongChatHubContext.Clients.All.ReceiveMessage(message);
}
}
Introdução
Hubs
Publicar no Azure
Gerenciar usuários e grupos no SignalR
Por Brennan Conroy

O SignalR permite que mensagens sejam enviadas para todas as conexões associadas a um usuário específico,
bem como grupos de conexões nomeados.
Usuários no SignalR
O SignalR permite enviar mensagens para todas as conexões associadas a um usuário específico. Por padrão, o
SignalR usa o ClaimTypes.NameIdentifier do ClaimsPrincipal associado com a conexão como o identificador de
usuário. Um único usuário pode ter várias conexões a um aplicativo do SignalR. Por exemplo, um usuário pode
ser conectado em sua área de trabalho, bem como seu telefone. Cada dispositivo tem uma conexão SignalR
separado, mas eles são todos associados ao mesmo usuário. Se uma mensagem é enviada para o usuário, todas
as conexões associadas ao usuário recebem a mensagem. O identificador de usuário para uma conexão pode ser
acessado pelo Context.UserIdentifier propriedade em seu hub.
Enviar uma mensagem para um usuário específico, passando o identificador de usuário para o User funcionar no
seu método de hub, conforme mostrado no exemplo a seguir:
NOTE
O identificador de usuário diferencia maiusculas de minúsculas.
public Task SendPrivateMessage(string user, string message)

{
return Clients.User(user).SendAsync("ReceiveMessage", message);
}
O identificador de usuário pode ser personalizado com a criação de um IUserIdProvider e registrá-lo no

ConfigureServices .
public class CustomUserIdProvider : IUserIdProvider

{
public virtual string GetUserId(HubConnectionContext connection)
{
return connection.User?.FindFirst(ClaimTypes.Email)?.Value;
}
}

{
services.AddSingleton<IUserIdProvider, CustomUserIdProvider>();
}
NOTE
AddSignalR deve ser chamado antes de registrar os serviços SignalR personalizados.
Grupos no SignalR
Um grupo é uma coleção de conexões associado com um nome. As mensagens podem ser enviadas para todas as
conexões em um grupo. Grupos são a maneira recomendada para enviar para uma conexão ou várias conexões,
porque os grupos são gerenciados pelo aplicativo. Uma conexão pode ser um membro de vários grupos. Isso
torna grupos ideal para algo como um aplicativo de bate-papo, onde cada sala pode ser representada como um
grupo. Conexões podem ser adicionadas ou removidas de grupos por meio de AddToGroupAsync e
RemoveFromGroupAsync métodos.
public async Task AddToGroup(string groupName)

{
await Groups.AddToGroupAsync(Context.ConnectionId, groupName);
await Clients.Group(groupName).SendAsync("Send", $"{Context.ConnectionId} has joined the group

{groupName}.");
}
public async Task RemoveFromGroup(string groupName)

{
await Groups.RemoveFromGroupAsync(Context.ConnectionId, groupName);
await Clients.Group(groupName).SendAsync("Send", $"{Context.ConnectionId} has left the group

{groupName}.");
}
Associação de grupo não é preservada quando uma conexão se reconecta. A conexão precisa ingressar
novamente o grupo quando é restabelecida. Não é possível contar os membros de um grupo, uma vez que essas
informações não estarão disponíveis se o aplicativo é dimensionado para vários servidores.
Para proteger o acesso a recursos durante o uso de grupos, use autenticação e autorização funcionalidade no
ASP.NET Core. Se você adicionar apenas os usuários a um grupo quando as credenciais são válidas para esse
grupo, as mensagens enviadas a esse grupo só irá para os usuários autorizados. No entanto, os grupos não são
um recurso de segurança. Declarações de autenticação têm recursos que grupos não fizer isso, como a expiração e
a revogação. Se a permissão do usuário para acessar o grupo for revogada, você precisa detectar que e removê-
las manualmente.
NOTE
Nomes de grupo diferenciam maiusculas de minúsculas.
Introdução
Hubs
Publicar no Azure
Publicar um ASP.NET Core aplicativo SignalR em um
aplicativo Web do Azure
Aplicativo Web do Azure é um a computação em nuvem do Microsoft plataforma de serviço para hospedar
aplicativos web, incluindo o ASP.NET Core.
NOTE
Este artigo refere-se a publicação de um aplicativo de SignalR do ASP.NET Core no Visual Studio. Visite serviço SignalR para
o Azure para obter mais informações sobre como usar o SignalR no Azure.
Publique o aplicativo
Visual Studio fornece ferramentas internas para publicação de um aplicativo da Web do Azure. Usuário do Visual
Studio Code pode usar CLI do Azure comandos para publicar aplicativos no Azure. Este artigo aborda a
publicação usando as ferramentas do Visual Studio. Para publicar um aplicativo usando a CLI do Azure, consulte
publicar um aplicativo ASP.NET Core no Azure com ferramentas de linha de comando.
Clique com botão direito no projeto no Gerenciador de soluções e selecione publicar. Confirme criar novo
check-in a escolher um destino de publicação caixa de diálogo e selecione publicar.
Insira as seguintes informações na criar serviço de aplicativo caixa de diálogo e selecione criar.
ITEM DESCRIÇÃO
Nome do aplicativo Um nome exclusivo do aplicativo.
Assinatura A assinatura do Azure que o aplicativo usa.
Grupo de recursos O grupo de recursos relacionados ao qual pertence o

aplicativo.
Plano de hospedagem O plano de preços para o aplicativo web.
Visual Studio conclui as seguintes tarefas:

Cria um perfil de publicação que contém as configurações de publicação.
Cria ou usa um existente aplicativo Web do Azure com os detalhes fornecidos.
Publica o aplicativo.
Inicia um navegador, com o aplicativo web publicado carregado.
Observe o formato da URL para o aplicativo é amp;#42;.azurewebsites.NET {nome do aplicativo } .net. Por
exemplo, um aplicativo chamado SignalRChattR tem uma URL que se parece com
https://signalrchattr.azurewebsites.net .
Se ocorrer um erro de HTTP 502.2, consulte versão de visualização de implantar o ASP.NET Core no serviço de
aplicativo do Azure resolvê-lo.
Configurar o aplicativo web de SignalR

Aplicativos do ASP.NET SignalR Core que são publicados como um aplicativo Web deve ter afinidade ARR
habilitado. WebSockets deve ser habilitada, para permitir que o transporte de WebSockets para a função.
No portal do Azure, navegue até configurações do aplicativo para seu aplicativo web. Definir WebSockets à
nae verifique se afinidade ARR é em.
WebSockets e outros transportes são limitados com base no plano do serviço de aplicativo.
Publicar um aplicativo ASP.NET Core no Azure com ferramentas de linha de comando
Hospedar e implantar aplicativos de visualização do ASP.NET Core no Azure
Cliente de .NET do SignalR do ASP.NET Core
A biblioteca de cliente .NET de SignalR do ASP.NET Core permite que você se comunicar com os hubs de
SignalR em aplicativos .NET.
NOTE
Xamarin tem requisitos especiais para a versão do Visual Studio. Para obter mais informações, consulte cliente SignalR 2.1.1
no Xamarin.

O exemplo de código neste artigo é um aplicativo do WPF que usa o cliente .NET de SignalR do ASP.NET Core.
Instalar o pacote de cliente .NET do SignalR

O Microsoft.AspNetCore.SignalR.Client pacote é necessário para clientes .NET conectar-se aos hubs de SignalR.
Para instalar a biblioteca de cliente, execute o seguinte comando na Package Manager Console janela:
Install-Package Microsoft.AspNetCore.SignalR.Client
Conectar a um hub
Para estabelecer uma conexão, cria uma HubConnectionBuilder e chamar Build . A URL do hub, protocolo, o tipo
de transporte, nível de log, cabeçalhos e outras opções podem ser configuradas durante a criação de uma
conexão. Configurar as opções necessárias, inserindo qualquer um dos HubConnectionBuilder métodos em Build
. Iniciar a conexão com StartAsync .
using System;
using System.Windows;
using Microsoft.AspNetCore.SignalR.Client;
namespace SignalRChatClient
{
public partial class MainWindow : Window
{
HubConnection connection;
public MainWindow()
{
InitializeComponent();
connection = new HubConnectionBuilder()

.WithUrl("http://localhost:53353/ChatHub")
.Build();
connection.Closed += async (error) =>

{
await Task.Delay(new Random().Next(0,5) * 1000);
await connection.StartAsync();
};
}
private async void connectButton_Click(object sender, RoutedEventArgs e)

{
connection.On<string, string>("ReceiveMessage", (user, message) =>
{
this.Dispatcher.Invoke(() =>
{
var newMessage = $"{user}: {message}";
messagesList.Items.Add(newMessage);
});
});
try
{
messagesList.Items.Add("Connection started");
connectButton.IsEnabled = false;
sendButton.IsEnabled = true;
}
{
messagesList.Items.Add(ex.Message);
}
}
private async void sendButton_Click(object sender, RoutedEventArgs e)

{
try
{
await connection.InvokeAsync("SendMessage",
userTextBox.Text, messageTextBox.Text);
}
{
}
}
}
}
Lidar com a conexão perdida

Use o Closed eventos para responder a uma conexão perdida. Por exemplo, você talvez queira automatizar a
reconexão.
O Closed evento requer um delegado que retorna um Task , que permite que o código assíncrono executar sem
usar async void . Para satisfazer a assinatura do delegado em um Closed manipulador de eventos que é
executado de forma síncrona, retorna Task.CompletedTask :
connection.Closed += (error) => {

// Do your close logic.
};
O principal motivo para o suporte assíncrono é portanto, você pode reiniciar a conexão. Iniciar uma conexão é
uma ação assíncrona.
Em um Closed manipulador que reinicia a conexão, considere aguardar algum atraso aleatório evitar
sobrecarregar o servidor, conforme mostrado no exemplo a seguir:
connection.Closed += async (error) =>

{
await Task.Delay(new Random().Next(0,5) * 1000);
};
Chamar métodos de hub do cliente

InvokeAsync chama métodos no hub. Passe o nome do método de hub e quaisquer argumentos definidos no
método de hub para InvokeAsync . O SignalR é assíncrono, portanto, use async e await ao fazer as chamadas.
Chamar métodos de cliente do hub

Definir métodos de hub de chamadas usando connection.On depois de criar, mas antes de iniciar a conexão.
connection.On<string, string>("ReceiveMessage", (user, message) =>

{
this.Dispatcher.Invoke(() =>
{
var newMessage = $"{user}: {message}";
messagesList.Items.Add(newMessage);
});
});
O código anterior no connection.On é executado quando o código do lado do servidor chama-o usando o
SendAsync método.

{
await Clients.All.SendAsync("ReceiveMessage", user,message);
}
Registro em log e tratamento de erros
Tratar erros com uma instrução try-catch. Inspecione o Exception objeto para determinar a ação apropriada a
tomar depois de ocorrer um erro.
try
{
}
{
}
Recursos adicionais
Hubs
Cliente JavaScript
Publicar no Azure
Cliente de Java do SignalR Core ASP.NET
Por Mikael Mengistu

O cliente de Java permite se conectar a um servidor do SignalR do ASP.NET Core do código Java, incluindo
aplicativos Android. Como o cliente JavaScript e o cliente .NET, o cliente de Java permite que você receber e enviar
mensagens a um hub em tempo real. O cliente de Java está disponível no ASP.NET Core 2.2 e posterior.
O aplicativo de console do Java de exemplo referenciado neste artigo usa o cliente de Java do SignalR.
Instalar o pacote de cliente Java do SignalR

O signalr 1.0.0 -preview3 35501 arquivo JAR permite que os clientes se conectem aos hubs de SignalR. Para
localizar o número de versão de arquivo JAR mais recente, consulte o resultados da pesquisa Maven.
Se usando o Gradle, adicione a seguinte linha para o dependencies seção do seu Build. gradle arquivo:
implementation 'com.microsoft.signalr:signalr:1.0.0-preview3-35501'
implementation 'io.reactivex.rxjava2:rxjava:2.2.2'
Se usando o Maven, adicione as seguintes linhas dentro de <dependencies> elemento da sua POM. XML arquivo:
<dependency>
<groupId>com.microsoft.signalr</groupId>
<artifactId>signalr</artifactId>
<version>1.0.0-preview3-35501</version>
</dependency>
<dependency>
<groupId>io.reactivex.rxjava2</groupId>
<artifactId>rxjava</artifactId>
<version>2.2.2</version>
</dependency>
Conectar a um hub
Para estabelecer uma HubConnection , o HubConnectionBuilder deve ser usado. O nível de log e a URL do hub pode
ser configurado durante a criação de uma conexão. Configurar as opções necessárias chamando o
HubConnectionBuilder métodos antes build . Iniciar a conexão com start .
HubConnection hubConnection = HubConnectionBuilder.create(input)

.build();

Uma chamada para send invoca um método de hub. Passe o nome do método de hub e quaisquer argumentos
definidos no método de hub para send .
hubConnection.send("Send", input);

Use hubConnection.on para definir métodos no cliente que o hub pode chamar. Defina os métodos depois de criar,
mas antes de iniciar a conexão.
hubConnection.on("Send", (message) -> {

System.out.println("New Message: " + message);
}, String.class);
Adicionar registro em log

O cliente SignalR Java usa a SLF4J biblioteca para registro em log. É uma API de alto nível de log que permite aos
usuários da biblioteca de escolher sua própria implementação de log específico, colocando em uma dependência
de log específico. O trecho de código a seguir mostra como usar java.util.logging com o cliente de Java do
SignalR.
implementation 'org.slf4j:slf4j-jdk14:1.7.25'
Se você não configurar o registro em log em suas dependências, SLF4J carrega um agente de operação não
padrão com a seguinte mensagem de aviso:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".

SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Isso pode ser ignorado.
Limitações conhecidas
Esta é uma versão de visualização do cliente Java. Não há suporte para alguns recursos:
Há suporte para apenas o protocolo JSON.
Há suporte para apenas o transporte de WebSockets.
Streaming ainda não tem suporte.
Recursos adicionais
Referência de API Java
Publicar um ASP.NET Core SignalR aplicativo ao aplicativo Web do Azure
Por Rachel Appel

A biblioteca de cliente JavaScript de SignalR do ASP.NET Core permite aos desenvolvedores chamar o código
de hub do lado do servidor.
Instalar o pacote de cliente do SignalR

A biblioteca de cliente SignalR JavaScript é entregue como um npm pacote. Se você estiver usando o Visual
Studio, execute npm install do Package Manager Console enquanto na pasta raiz. Para Visual Studio Code,
execute o comando a partir de Terminal integrado.
npm init -y
NPM instala o conteúdo do pacote na node_modules\@aspnet\signalr\dist\browser pasta. Criar uma nova pasta
chamada signalr sob o wwwroot\lib pasta. Cópia de signalr.js do arquivo para o wwwroot\lib\signalr pasta.
Usar o cliente SignalR JavaScript

Referência de cliente SignalR JavaScript no <script> elemento.
<script src="~/lib/signalr/signalr.js"></script>
Conectar a um hub
O código a seguir cria e inicia uma conexão. Nome do hub é diferencia maiusculas de minúsculas.

.withUrl("/chatHub")
.configureLogging(signalR.LogLevel.Information)
.build();
connection.start().catch(err => console.error(err.toString()));
Conexões entre origens

Normalmente, os navegadores carga das conexões do mesmo domínio que a página solicitada. No entanto, há
ocasiões em que é necessária uma conexão para outro domínio.
Para impedir a leitura de dados confidenciais de outro site, um site mal-intencionado conexões entre origens
estão desabilitados por padrão. Para permitir que uma solicitação entre origens, habilitá-lo no Startup classe.
{
{
{
}

{
{
});
services.AddMvc();
services.AddCors(options => options.AddPolicy("CorsPolicy",

builder =>
{
builder.AllowAnyMethod().AllowAnyHeader()
.WithOrigins("http://localhost:55830")
.AllowCredentials();
}));
}

{
{
}
else
{
app.UseHsts();
}
app.UseCors("CorsPolicy");
{
routes.MapHub<ChatHub>("/chathub");
});
app.UseMvc();
}
}
}
Clientes JavaScript chamem métodos públicos em hubs por meio de invocar método da HubConnection. O
invoke método aceita dois argumentos:
O nome do método de hub. No exemplo a seguir, o nome do método no hub é SendMessage .

Quaisquer argumentos definidos no método de hub. No exemplo a seguir, é o nome do argumento
message .
connection.invoke("SendMessage", user, message).catch(err => console.error(err.toString()));

Para receber mensagens do hub, definir um método usando o na método o HubConnection .
O nome do método de cliente JavaScript. No exemplo a seguir, é o nome do método ReceiveMessage .
O hub passa para o método de argumentos. No exemplo a seguir, o valor do argumento é message .
connection.on("ReceiveMessage", (user, message) => {

const encodedMsg = user + " says " + message;
const li = document.createElement("li");
});
O código anterior no connection.on é executado quando o código do lado do servidor chama-o usando o
SendAsync método.

{
}
O SignalR determina qual método de cliente para chamar, correspondendo o nome do método e argumentos
definidos no SendAsync e connection.on .
NOTE
Como uma prática recomendada, chame o inicie método na HubConnection depois on . Isso garante que os
manipuladores são registrados antes de todas as mensagens são recebidas.
Registro em log e tratamento de erros

Cadeia de um catch método até o final do start método para lidar com erros do lado do cliente. Use
console.error para erros de saída para o console do navegador.
Configure o rastreamento de log do lado do cliente, passando um agente de log e o tipo de evento para
registrar em log quando a conexão é feita. As mensagens são registradas com o nível de log especificado e
superior. Níveis de log disponíveis são da seguinte maneira:
signalR.LogLevel.Error – Mensagens de erro. Logs Error somente mensagens.
signalR.LogLevel.Warning – Mensagens de aviso sobre erros em potencial. Os logs Warning , e Error
mensagens.
signalR.LogLevel.Information – Mensagens de status sem erros. Os logs Information , Warning , e Error
mensagens.
signalR.LogLevel.Trace – Mensagens de rastreamento. Registra tudo, incluindo dados transportados entre
cliente e o hub.
Use o configureLogging método HubConnectionBuilder para configurar o nível de log. As mensagens são
registradas para o console do navegador.

.build();
Recursos adicionais
Referência de API JavaScript
Hubs
Cliente .NET
Publicar no Azure
Habilitar solicitações entre origens (CORS ) no ASP.NET Core
Webpack

em TypeScript.
Pré-requisitos
Visual Studio
CLI do .NET Core
Node.js com npm
a Web

Visual Studio
CLI do .NET Core
2. Selecione a entrada $ (PATH ) na lista. Clique na seta para cima para mover a entrada para a segunda
posição da lista. Como uma reserva, a primeira entrada se refere aos pacotes locais do projeto.

cliente.
npm init -y
{
"version": "1.0.0",
"private": true,
"description": "",
"main": "index.js",
"scripts": {
},
"keywords": [],
"author": "",
"license": "ISC"
}

recentes.
"scripts": {
},

module.exports = {
output: {
publicPath: "/"
},
resolve: {
},
module: {
rules: [
{
test: /\.ts$/,
use: "ts-loader"
},
{
test: /\.css$/,
}
]
},
plugins: [
}),
})
]
};

wwwroot.
projeto.
<!DOCTYPE html>
<html>
<head>
</head>
<body>
</div>
</div>
</body>
</html>

}
html, body {
margin: 0;
padding: 0;
}
.input-zone {
display: flex;
margin: 10px;
}
.input-zone-input {
flex: 1;
margin-right: 10px;
}
.message-author {
font-weight: bold;
}
.messages {
margin: 10px;
max-height: 300px;
min-height: 300px;
overflow-y: auto;
padding: 5px;
}

{
"target": "es5"
}
}
ECMAScript 5.


send();
}
});
function send() {
}

Startup.Configure :
{
});
{
{
}
}

para o servidor.


.withUrl("/hub")
.build();

m.innerHTML =
});

send();
}
});
function send() {
}

específica por meio da função on . Você pode escutar qualquer número de nomes de mensagem. Também
é possível passar parâmetros para a mensagem, como o nome do autor e o conteúdo da mensagem
recebida. Quando o cliente recebe a mensagem, um novo elemento div é criado com o nome do autor e o
conteúdo da mensagem em seu atributo innerHTML . Ele é adicionado ao elemento principal div que exibe
as mensagens.


.withUrl("/hub")
.build();

});

send();
}
});
function send() {
}
{
{
{
}
}
}
Testar o aplicativo
Visual Studio
CLI do .NET Core
npm run release
Recursos adicionais
Configuração do ASP.NET SignalR Core
Opções de serialização JSON/MessagePack

SignalR do ASP.NET Core dá suporte a dois protocolos para codificação de mensagens: JSON e MessagePack.
Cada protocolo tem opções de configuração de serialização.
Serialização JSON pode ser configurada no servidor usando o AddJsonProtocol método de extensão, que pode
ser adicionado após AddSignalR em seu Startup.ConfigureServices método. O AddJsonProtocol leva um delegado
que recebe um options objeto. O PayloadSerializerSettings propriedade desse objeto é um JSON.NET
JsonSerializerSettings objeto que pode ser usado para configurar a serialização de argumentos e valores de
retorno. Consulte a documentação do JSON.NET para obter mais detalhes.
Por exemplo, para configurar o serializador para usar nomes de propriedade "PascalCase", em vez dos nomes de
"camelCase" padrão, use o seguinte código:
services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerSettings.ContractResolver =
new DefaultContractResolver();
});
No cliente do .NET, o mesmo AddJsonProtocol método de extensão existe no HubConnectionBuilder. O

Microsoft.Extensions.DependencyInjection namespace deve ser importado para resolver o método de extensão:
// At the top of the file:

// When constructing your connection:

var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerSettings.ContractResolver =
new DefaultContractResolver();
})
.Build();
NOTE
Não é possível configurar a serialização JSON no cliente JavaScript neste momento.
Opções de serialização MessagePack

MessagePack serialização pode ser configurada fornecendo um delegado para o AddMessagePackProtocol
chamar. Ver MessagePack no SignalR para obter mais detalhes.
NOTE
Não é possível configurar a serialização de MessagePack no cliente JavaScript neste momento.
Configurar opções de servidor

A tabela a seguir descreve as opções de configuração hubs do SignalR:
OPÇÃO VALOR PADRÃO DESCRIÇÃO
HandshakeTimeout 15 segundos Se o cliente não envia uma mensagem

de handshake inicial dentro deste
intervalo de tempo, a conexão será
fechada. Isso é uma configuração
avançada que deve ser modificada
apenas se os erros de tempo limite de
handshake estiverem ocorrendo devido
à latência de rede graves. Para obter
mais detalhes sobre o processo de
handshake, consulte a especificação de
protocolo de Hub do SignalR.
KeepAliveInterval 15 segundos Se o servidor não enviou uma

mensagem dentro deste intervalo, uma
mensagem de ping é enviada
automaticamente para manter a
conexão aberta. Ao alterar
KeepAliveInterval , altere o
ServerTimeout /
serverTimeoutInMilliseconds
configuração no cliente. Recomendado
ServerTimeout /
serverTimeoutInMilliseconds valor é
double o KeepAliveInterval valor.
SupportedProtocols Todos os protocolos Protocolos com suporte por esse hub.

Por padrão, todos os protocolos
registrados no servidor são permitidos,
mas protocolos podem ser removidos
dessa lista para desabilitar os protocolos
específicos para hubs individuais.
EnableDetailedErrors false Se true detalhada mensagens de

exceção são retornadas aos clientes
quando uma exceção é gerada em um
método de Hub. O padrão é false ,
conforme essas mensagens de exceção
podem conter informações
confidenciais.
Opções podem ser configuradas para todos os hubs, fornecendo um delegado de opções para o AddSignalR
chamar em Startup.ConfigureServices .

{
services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
}
Opções para um único hub substituem as opções de globais fornecidas no AddSignalR e pode ser configurado
usando AddHubOptions<T >:
services.AddSignalR().AddHubOptions<MyHub>(options =>
{
options.EnableDetailedErrors = true;
});
Use HttpConnectionDispatcherOptions para definir configurações avançadas relacionadas a transportes e

gerenciamento de buffer de memória. Essas opções são configuradas passando um delegado para MapHub<T >.
ApplicationMaxBufferSize 32 KB O número máximo de bytes recebidos

do cliente que os buffers de servidor.
Aumentar esse valor permite que o
servidor receber mensagens maiores,
mas pode afetar negativamente o
consumo de memória.
AuthorizationData Dados coletados automaticamente a Uma lista dos IAuthorizeData objetos

partir de Authorize atributos usados para determinar se um cliente
aplicados à classe Hub. está autorizado a conectar-se ao hub.
TransportMaxBufferSize 32 KB O número máximo de bytes enviados

pelo aplicativo que os buffers de
servidor. Aumentar esse valor permite
que o servidor enviar mensagens
maiores, mas pode afetar
negativamente o consumo de memória.
Transports Todos os transportes estão habilitados. Um bitmask de HttpTransportType

valores que possam restringir os
transportes de um cliente pode usar
para se conectar.
LongPolling Veja a seguir. Opções adicionais específicas para o

transporte de sondagem longa.
WebSockets Veja a seguir. Opções adicionais específicas para o

transporte de WebSockets.
O transporte de sondagem longa tem opções adicionais que podem ser configuradas usando o LongPolling
propriedade:
PollTimeout 90 segundos A quantidade máxima de tempo o

servidor aguarda uma mensagem para
enviar ao cliente antes de encerrar uma
solicitação de pesquisa único. Diminuir
esse valor faz com que o cliente emitir
novas solicitações de sondagem com
mais frequência.
O transporte de WebSocket tem opções adicionais que podem ser configuradas usando o WebSockets
propriedade:
CloseTimeout 5 segundos Depois de fecha o servidor, se o cliente

não conseguir fechar dentro deste
intervalo de tempo, a conexão é
encerrada.
SubProtocolSelector null Um delegado que pode ser usado para

definir o Sec-WebSocket-Protocol
cabeçalho para um valor personalizado.
O delegado recebe os valores
solicitados pelo cliente como entrada e
deve retornar o valor desejado.
Configurar opções do cliente

Opções de cliente podem ser configuradas na HubConnectionBuilder (disponível em clientes .NET e JavaScript), do
tipo, bem como no HubConnection em si.
Configurar o registro em log
O log está configurado no cliente do .NET usando o ConfigureLogging método. Registro em log provedores e
filtros pode ser registrado da mesma forma como estão no servidor. Consulte a entrar no ASP.NET Core
documentação para obter mais informações.
NOTE
Para registrar os provedores de log, você deve instalar os pacotes necessários. Consulte a provedores de log internos seção
do docs para obter uma lista completa.
Por exemplo, para habilitar o log de Console, instale o Microsoft.Extensions.Logging.Console pacote do NuGet.
Chamar o AddConsole método de extensão:

.WithUrl("https://example.com/myhub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
})
.Build();
No cliente JavaScript, um semelhante configureLogging existe um método. Forneça um LogLevel valor que indica
o nível mínimo de mensagens de log para produzir. Os logs são gravados na janela de console do navegador.
let connection = new signalR.HubConnectionBuilder()

.withUrl("/myhub")
.build();
NOTE
Para desabilitar o registro em log totalmente, especifique signalR.LogLevel.None no configureLogging método.
Níveis de log disponíveis para o cliente JavaScript estão listados abaixo. Definindo o nível de log para um desses
valores habilita o log de mensagens no ou superior desse nível.
NÍVEL DESCRIÇÃO
None Nenhuma mensagem será registrada.
Critical Mensagens que indicam uma falha em todo o aplicativo.
Error Mensagens que indicam uma falha na operação atual.
Warning Mensagens que indicam um problema de não-fatais.
Information Mensagens informativas.
Debug Mensagens de diagnóstico útil para depuração.
Trace Mensagens de diagnóstico muito detalhadas projetadas para

diagnosticar problemas específicos.
Configure transportes permitidos

Os transportes usados pelo SignalR podem ser configurados na WithUrl chamar ( withUrl em JavaScript). Um
bitwise OR dos valores de HttpTransportType pode ser usado para restringir o cliente para usar somente os
transportes especificados. Todos os transportes são habilitados por padrão.
Por exemplo, para desabilitar o transporte de eventos do Server-Sent, mas permita conexões WebSocket e
sondagem longa:

.WithUrl("https://example.com/myhub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
No cliente JavaScript, transportes são configurados, definindo o transport campo no objeto de opções fornecido
ao withUrl :

.withUrl("/myhub", { transport: signalR.HttpTransportType.WebSockets |
signalR.HttpTransportType.LongPolling })
.build();
Configurar a autenticação do portador

Para fornecer dados de autenticação junto com as solicitações de SignalR, use o AccessTokenProvider opção (
accessTokenFactory em JavaScript) para especificar uma função que retorna o token de acesso desejado. No
cliente do .NET, esse token de acesso é passado como um HTTP "Autenticação do portador" token (usando o
Authorization cabeçalho com um tipo de Bearer ). No cliente JavaScript, o token de acesso é usado como um
token de portador exceto em alguns casos em que o navegador APIs restringir a capacidade de aplicar cabeçalhos
(especificamente, em solicitações de eventos do Server-sent e WebSockets). Nesses casos, o token de acesso é
fornecido como um valor de cadeia de caracteres de consulta access_token .
No cliente do .NET, o AccessTokenProvider opção pode ser especificada usando o delegado de opções no WithUrl :
.WithUrl("https://example.com/myhub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
No cliente JavaScript, o token de acesso é configurado definindo a accessTokenFactory campo no objeto de opções
no withUrl :

.withUrl("/myhub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
Configurar tempo limite e opções de keep alive

Opções adicionais para configurar o tempo limite e o comportamento de keep alive estão disponíveis no
HubConnection objeto em si:
OPÇÃO DE .NET OPÇÃO DE JAVASCRIPT VALOR PADRÃO DESCRIÇÃO
ServerTimeout serverTimeoutInMilliseconds 30 segundos (30.000 Tempo limite para a

milissegundos) atividade do servidor. Se o
servidor não enviou uma
mensagem nesse intervalo, o
cliente considera o servidor
desconectado e gatilhos do
Closed evento ( onclose
em JavaScript). Esse valor
deve ser grande o suficiente
para uma mensagem de
ping a serem enviados do
servidor e recebida pelo
cliente dentro do intervalo
de tempo limite. O valor
recomendado é um número
pelo menos duas vezes o
servidor
KeepAliveInterval valor,
para dar tempo para pings
de chegada.
HandshakeTimeout Não é configurável 15 segundos Tempo limite para o

handshake inicial do servidor.
Se o servidor não enviar
uma resposta de handshake
nesse intervalo, o cliente
cancela o handshake e
gatilhos do Closed evento
( onclose em JavaScript).
Isso é uma configuração
avançada que deve ser
modificada apenas se os
erros de tempo limite de
handshake estiverem
ocorrendo devido à latência
de rede graves. Para obter
mais detalhes sobre o
processo de Handshake,
consulte a especificação de
protocolo de Hub do
SignalR.
No cliente do .NET, os valores de tempo limite são especificados como TimeSpan valores. No cliente JavaScript, os
valores de tempo limite são especificados como um número que indica a duração em milissegundos.
Configurar opções adicionais
Opções adicionais podem ser configuradas na WithUrl ( withUrl em JavaScript) método em
HubConnectionBuilder :
AccessTokenProvider accessTokenFactory null Uma função que retorna

uma cadeia de caracteres
que é fornecida como um
token de autenticação de
portador em solicitações
HTTP.
SkipNegotiation skipNegotiation false Defina isso como true

para ignorar a etapa de
negociação. Só tem suporte
quando o transporte de
WebSockets é o único
transporte habilitado. Essa
configuração não pode ser
habilitada ao usar o serviço
do Azure SignalR.
ClientCertificates Não é configurável * Vazio Uma coleção de certificados

TLS para enviar para
autenticar solicitações.
Cookies Não é configurável * Vazio Uma coleção de cookies

HTTP a ser enviado com
cada solicitação HTTP.
Credentials Não é configurável * Vazio Credenciais devem ser

enviados com cada
solicitação HTTP.
CloseTimeout Não é configurável * 5 segundos WebSockets. A quantidade

máxima de tempo que o
cliente aguardará depois de
fechamento para o servidor
confirmar a solicitação de
fechamento. Se o servidor
não reconhece o fechamento
dentro desse período, o
cliente se desconecta.
Headers Não é configurável * Vazio Um dicionário de cabeçalhos

HTTP adicionais para enviar
com todas as solicitações
HTTP.
HttpMessageHandlerFactory Não é configurável * null Um delegado que pode ser

usado para configurar ou
substituir o
HttpMessageHandler
usado para enviar
solicitações HTTP. Não é
usado para conexões de
WebSocket. Esse delegado
deve retornar um valor não
nulo e recebe o valor padrão
como um parâmetro.
Modificar as configurações
nesse valor padrão e
retorná-lo ou retornar um
novo HttpMessageHandler
instância. Ao substituir o
manipulador Certifique-se
de copiar as
configurações que você
deseja impedir que o
manipulador fornecido,
caso contrário, as opções
configuradas (como
cabeçalhos e Cookies) não
se aplicam ao novo
manipulador.
Proxy Não é configurável * null Um proxy HTTP a ser usado

ao enviar solicitações HTTP.
UseDefaultCredentials Não é configurável * false Defina esse valor booliano

para enviar as credenciais
padrão para solicitações
HTTP e WebSockets. Isso
permite que o uso da
autenticação do Windows.
WebSocketConfiguration Não é configurável * null Um delegado que pode ser

usado para configurar
opções adicionais de
WebSocket. Recebe uma
instância do
ClientWebSocketOptions
que pode ser usado para
configurar as opções.
Opções marcadas com um asterisco (*) não são configuráveis no cliente JavaScript, devido a limitações no
navegador APIs.
No cliente do .NET, essas opções podem ser modificadas pelo delegado opções fornecido para WithUrl :

.WithUrl("https://example.com/myhub", options => {
options.Headers["Foo"] = "Bar";
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
No cliente JavaScript, essas opções podem ser fornecidas em um objeto JavaScript fornecido para withUrl :

.withUrl("/myhub", {
skipNegotiation: true,
transport: signalR.HttpTransportType.WebSockets
})
.build();
Recursos adicionais
Introdução ao SignalR para ASP.NET Core
Cliente de .NET do SignalR do ASP.NET Core
Usar o protocolo de MessagePack Hub no SignalR do ASP.NET Core
Plataformas com suporte do SignalR do ASP.NET Core
Autenticação e autorização no SignalR do ASP.NET
Core
Por Andrew Stanton-Nurse

Autenticar usuários que se conectam a um hub SignalR

O SignalR pode ser usado com autenticação do ASP.NET Core para associar um usuário a cada conexão. Em um
hub, os dados de autenticação podem ser acessados do HubConnectionContext.User propriedade. A autenticação
permite que o hub para chamar métodos em todas as conexões associadas a um usuário (consulte gerenciar
usuários e grupos no SignalR para obter mais informações). Várias conexões podem estar associadas um único
usuário.
Autenticação de cookie
Em um aplicativo baseado em navegador, a autenticação de cookie permite que suas credenciais de usuário
existentes fluir automaticamente para conexões do SignalR. Ao usar o cliente de navegador, nenhuma
configuração adicional é necessária. Se o usuário está conectado ao seu aplicativo, a conexão do SignalR herda
automaticamente essa autenticação.
Os cookies são uma maneira de específicas do navegador para enviar os tokens de acesso, mas os clientes sem
navegador podem enviá-los. Ao usar o cliente .NET, o Cookies propriedade pode ser configurada no .WithUrl
chamada para fornecer um cookie. No entanto, usando a autenticação de cookie do cliente .NET requer que o
aplicativo para fornecer uma API para trocar dados de autenticação para um cookie.
Autenticação de token de portador
O cliente pode fornecer um token de acesso em vez de usar um cookie. O servidor valida o token e usa-o para
identificar o usuário. Essa validação é feita somente quando a conexão é estabelecida. Durante a vida da conexão, o
servidor não automaticamente revalidar para verificar a revogação do token.
No servidor de autenticação de token de portador é configurada usando o middleware de portador de JWT.
No cliente JavaScript, o token pode ser fornecido usando o accessTokenFactory opção.
this.connection = new signalR.HubConnectionBuilder()

.withUrl("/hubs/chat", { accessTokenFactory: () => this.loginToken })
.build();
No cliente do .NET, há um semelhante AccessTokenProvider propriedade que pode ser usada para configurar o
token:

.WithUrl("https://example.com/myhub", options =>
{
options.AccessTokenProvider = () => Task.FromResult(_myAccessToken);
})
.Build();
NOTE
A função de token de acesso que você fornecer é chamada antes de cada solicitação HTTP feita pelo SignalR. Se você precisa
renovar o token para manter a conexão ativa (porque ele pode expirar durante a conexão), faça isso dentro dessa função e
retornar o token atualizado.
APIs da web padrão, os tokens de portador são enviados em um cabeçalho HTTP. No entanto, o SignalR é não é
possível definir esses cabeçalhos em navegadores quando usando alguns transportes. Ao usar WebSockets e
eventos do Server-Sent, o token é transmitido como um parâmetro de cadeia de caracteres de consulta. Para
suportar isso no servidor, a configuração adicional é necessária:

{
services.AddAuthentication(options =>
{
// Identity made Cookie authentication the default.
// However, we want JWT Bearer Auth to be the default.
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
// Configure JWT Bearer Auth to expect our security key
options.TokenValidationParameters =
new TokenValidationParameters
{
LifetimeValidator = (before, expires, token, param) =>
{
return expires > DateTime.UtcNow;
},
ValidateAudience = false,
ValidateIssuer = false,
ValidateActor = false,
ValidateLifetime = true,
IssuerSigningKey = SecurityKey
};
// We have to hook the OnMessageReceived event in order to

// allow the JWT authentication handler to read the access
// token from the query string when a WebSocket or
// Server-Sent Events request comes in.
options.Events = new JwtBearerEvents
{
OnMessageReceived = context =>
{
var accessToken = context.Request.Query["access_token"];
// If the request is for our hub...

var path = context.HttpContext.Request.Path;
if (!string.IsNullOrEmpty(accessToken) &&
(path.StartsWithSegments("/hubs/chat")))
{
// Read the token out of the query string
context.Token = accessToken;
}
}
};
};
});
// Change to use Name as the user identifier for SignalR

// WARNING: This requires that the source of your JWT token
// ensures that the Name claim is unique!
// If the Name claim isn't unique, users could receive messages
// intended for a different user!
services.AddSingleton<IUserIdProvider, NameUserIdProvider>();
}
Cookies versus os tokens de portador

Como os cookies são específicos para navegadores, enviá-las de outros tipos de clientes adiciona complexidade
em comparação comparada enviar tokens de portador. Por esse motivo, a autenticação de cookie não é
recomendada, a menos que o aplicativo precisa apenas para autenticar usuários de cliente de navegador.
Autenticação de token de portador é a abordagem recomendada ao usar os clientes que não seja o cliente do
navegador.
Se autenticação do Windows é configurado em seu aplicativo, o SignalR pode usar essa identidade para proteger
hubs. No entanto, para enviar mensagens para usuários individuais, você precisará adicionar um provedor de ID
de usuário personalizado. Isso ocorre porque o sistema de autenticação do Windows não fornece a declaração
"Identificador de nome" que usa o SignalR para determinar o nome de usuário.
Adicione uma nova classe que implementa IUserIdProvider e recuperar uma das declarações de usuário a ser
usado como o identificador. Por exemplo, para usar a declaração de "Nome" (que é o nome de usuário do
Windows na forma [Domain]\[Username] ), crie a seguinte classe:
public class NameUserIdProvider : IUserIdProvider

{
public string GetUserId(HubConnectionContext connection)
{
return connection.User?.FindFirst(ClaimTypes.Name)?.Value;
}
}
Em vez de ClaimTypes.Name , você pode usar qualquer valor entre o User (como o identificador do SID do
Windows, etc.).
NOTE
O valor escolhido deve ser exclusivo entre todos os usuários em seu sistema. Caso contrário, uma mensagem para um
usuário poderia acabar indo para um usuário diferente.
Registrar esse componente em seu Startup.ConfigureServices método depois a chamada para .AddSignalR

{
// ... other services ...
services.AddSingleton<IUserIdProvider, NameUserIdProvider>();
}
No cliente do .NET, a autenticação do Windows deve ser habilitada definindo o UseDefaultCredentials
propriedade:

.WithUrl("https://example.com/myhub", options =>
{
options.UseDefaultCredentials = true;
})
.Build();
Autenticação do Windows só tem suporte pelo cliente do navegador ao usar o Microsoft Internet Explorer ou
Microsoft Edge.
Autorizar usuários para acesso hubs e métodos de hub

Por padrão, todos os métodos em um hub podem ser chamados por um usuário não autenticado. Para exigir
autenticação, se aplicam a autorizar de atributo para o hub:
[Authorize]
public class ChatHub: Hub
{
}
Você pode usar os argumentos de construtor e propriedades do [Authorize] atributo para restringir o acesso
somente para usuários específicos de correspondência políticas de autorização. Por exemplo, se você tiver uma
política de autorização personalizada chamada MyAuthorizationPolicy pode garantir que somente os usuários
dessa política de correspondência podem acessar o hub usando o seguinte código:
[Authorize("MyAuthorizationPolicy")]
{
}
Métodos de hub individuais podem ter o [Authorize] atributo aplicado também. Se o usuário atual não
corresponder a política aplicada ao método, um erro será retornado ao chamador:
[Authorize]
{
public async Task Send(string message)
{
// ... send a message to all users ...
}
[Authorize("Administrators")]
public void BanUser(string userName)
{
// ... ban a user from the chat room (something only Administrators can do) ...
}
}
Considerações de segurança no SignalR do ASP.NET
Core
Por Andrew Stanton-Nurse

Este artigo fornece informações sobre como proteger o SignalR.
Compartilhamento de recursos entre origens

Recursos entre origens (CORS ) compartilhamento pode ser usado para permitir conexões do SignalR entre
origens no navegador. Se o código JavaScript é hospedado em um domínio diferente do aplicativo do SignalR,
middleware CORS deve estar habilitado para permitir que o JavaScript para se conectar ao aplicativo SignalR.
Permitir solicitações entre origens de domínios que confiáveis ou controle. Por exemplo:
O site é hospedado em http://www.example.com
Seu aplicativo SignalR é hospedado em http://signalr.example.com
CORS devem ser configurado no aplicativo do SignalR para permitir somente a origem www.example.com .
Para obter mais informações sobre como configurar o CORS, consulte habilitar solicitações de entre origens
(CORS ). O SignalR requer as seguintes políticas CORS:
Permitir que as origens esperadas específicas. Permitir qualquer origem é possível, mas está não segura ou
recomendada.
Métodos HTTP GET e POST devem ser permitidos.
Credenciais devem ser habilitadas, mesmo quando a autenticação não é usada.
Por exemplo, a seguinte política CORS permite que um cliente de navegador do SignalR hospedado no
http://example.com para acessar o aplicativo de SignalR hospedado em http://signalr.example.com :

{
// ... other middleware ...
// Make sure the CORS middleware is ahead of SignalR.

app.UseCors(builder =>
{
builder.WithOrigins("http://example.com")
.AllowAnyHeader()
.WithMethods("GET", "POST")
});
{
});

}
NOTE
O SignalR não é compatível com o recurso interno de CORS no serviço de aplicativo do Azure.
Restrição de origem do WebSocket

As proteções fornecidas pelo CORS não se aplicam ao WebSockets. Navegadores fazem não:
Execute solicitações de simulação CORS.
Respeitar as restrições especificadas no Access-Control cabeçalhos ao fazer solicitações de WebSocket.
No entanto, os navegadores enviam a Origin cabeçalho ao emitir solicitações de WebSocket. Aplicativos devem
ser configurados para validar esses cabeçalhos para garantir que apenas WebSockets provenientes de origens
esperadas são permitidos.
No ASP.NET Core 2.1 e posterior, validação de cabeçalho pode ser obtida usando um middleware personalizado
colocado antes de UseSignalR e o middleware de autenticação em Configure :
// In Startup, add a static field listing the allowed Origin values:
private static readonly HashSet<string> _allowedOrigins = new HashSet<string>()
{
// Add allowed origins here. For example:
"http://www.mysite.com",
"http://mysite.com",
};

{
// Validate Origin header on WebSocket requests to prevent unexpected cross-site

// WebSocket requests.
{
// Check for a WebSocket request.
if (string.Equals(context.Request.Headers["Upgrade"], "websocket"))
{
var origin = context.Request.Headers["Origin"];
// If there is an origin header, and the origin header doesn't match

// an allowed value:
if (!string.IsNullOrEmpty(origin) && !_allowedOrigins.Contains(origin))
{
// The origin is not allowed, reject the request
context.Response.StatusCode = StatusCodes.Status403Forbidden;
}
}
// The request is a valid Origin or not a WebSocket request, so continue.

return next();
});
{
});

}
NOTE
O Origin cabeçalho é controlado pelo cliente e, como o Referer cabeçalho, podem ser falsificadas. Esses cabeçalhos
devem não ser usado como um mecanismo de autenticação.
Log de token de acesso

Ao usar WebSockets ou Server-Sent eventos, o cliente de navegador envia o token de acesso na cadeia de
caracteres de consulta. Receber o token de acesso por meio da cadeia de caracteres de consulta é geralmente tão
seguro quanto usar o padrão Authorization cabeçalho. No entanto, muitos servidores web registrar a URL para
cada solicitação, incluindo a cadeia de caracteres de consulta. Registro em log as URLs pode registrar o token de
acesso. Uma prática recomendada é definir configurações de registro em log do servidor para impedir que tokens
de acesso de registro em log de web.
Exceções
Mensagens de exceção são geralmente consideradas dados confidenciais que não devem ser revelados para um
cliente. Por padrão, o SignalR não envia os detalhes de uma exceção gerada por um método de hub para o cliente.
Em vez disso, o cliente recebe uma mensagem genérica indicando que ocorreu um erro. Entrega de mensagem de
exceção para o cliente pode ser substituída (por exemplo, no desenvolvimento ou teste) com EnableDetailedErrors
. Mensagens de exceção não devem ser expostas ao cliente em aplicativos de produção.
Gerenciamento de buffer
O SignalR usa buffers por conexão para gerenciar mensagens de entrada e saídas. Por padrão, o SignalR limita
esses buffers para 32 KB. A mensagem maior que um cliente ou servidor pode enviar é 32 KB. O máximo de
memória consumido por uma conexão de mensagens é 32 KB. Se as mensagens são sempre menores que 32 KB,
você pode reduzir o limite, que:
Impede que um cliente que está sendo capaz de enviar uma mensagem maior.
O servidor nunca será necessário alocar buffers grandes para aceitar mensagens.
Se suas mensagens forem maiores que 32 KB, você pode aumentar o limite. Aumentar esse limite significa:
O cliente pode fazer com que o servidor para alocar buffers de memória grandes.
Alocação de servidor de buffers grandes pode reduzir o número de conexões simultâneas.
Há limites para mensagens de entrada e saídas, ambos podem ser configuradas sobre o
HttpConnectionDispatcherOptions objeto configurado no MapHub :
ApplicationMaxBufferSize representa o número máximo de bytes do cliente que os buffers de servidor. Se o

cliente tenta enviar uma mensagem maior que esse limite, a conexão poderá ser fechada.
TransportMaxBufferSize representa o número máximo de bytes que o servidor pode enviar. Se o servidor tenta
enviar uma mensagem (incluindo valores de retorno de métodos de hub) maiores que esse limite, uma exceção
será lançada.
Definir o limite como 0 desabilita o limite. Remover o limite permite que um cliente enviar uma mensagem de
qualquer tamanho. Os clientes mal-intencionados enviando mensagens extensas podem provocar alocação de
memória em excesso. Uso de memória em excesso pode reduzir significativamente o número de conexões
simultâneas.
Usar o protocolo de MessagePack Hub no SignalR
do ASP.NET Core
Por Brennan Conroy

Este artigo pressupõe que o leitor esteja familiarizado com os tópicos abordados começar.
O que é MessagePack?
MessagePack é um formato de serialização binária que é rápido e compacto. Ela é útil quando o desempenho e a
largura de banda são uma preocupação porque cria mensagens menores em comparação comparadas JSON.
Porque ele é um formato binário, as mensagens são ilegíveis ao examinar os logs e rastreamentos de rede, a
menos que os bytes são passados por meio de um analisador MessagePack. O SignalR tem suporte interno para
o formato MessagePack e fornece APIs para o cliente e servidor usar.
Configurar MessagePack no servidor

Para habilitar o protocolo do Hub MessagePack no servidor, instale o
Microsoft.AspNetCore.SignalR.Protocols.MessagePack pacote em seu aplicativo. No arquivo Startup.cs, adicione
AddMessagePackProtocol para o AddSignalR chamada para habilitar o suporte de MessagePack no servidor.
NOTE
JSON é habilitado por padrão. Adicionar MessagePack habilita o suporte para JSON e MessagePack clientes.
.AddMessagePackProtocol();
Para personalizar como MessagePack formatará a seus dados, AddMessagePackProtocol aceita um delegado para
configurar as opções. No delegado, o FormatterResolvers propriedade pode ser usada para configurar as opções
de serialização MessagePack. Para obter mais informações sobre como funcionam os resolvedores, visite a
biblioteca, MessagePack em MessagePack-CSharp. Atributos podem ser usados nos objetos que você deseja
serializar para definir como eles devem ser tratados.
.AddMessagePackProtocol(options =>
{
options.FormatterResolvers = new List<MessagePack.IFormatterResolver>()
{
MessagePack.Resolvers.StandardResolver.Instance
};
});
Configurar MessagePack no cliente

NOTE
JSON é habilitado por padrão para os clientes com suporte. Os clientes só podem dar suporte a um único protocolo.
Adicionar suporte MessagePack qualquer substituirá anteriormente protocolos configurados.
Cliente .NET
Para habilitar MessagePack no cliente .NET, instale o Microsoft.AspNetCore.SignalR.Protocols.MessagePack pacote
e chame AddMessagePackProtocol em HubConnectionBuilder .
var hubConnection = new HubConnectionBuilder()

.WithUrl("/chatHub")
.AddMessagePackProtocol()
.Build();
NOTE
Isso AddMessagePackProtocol chamada aceita um delegado para configurar opções de como o servidor.
Cliente JavaScript
MessagePack suporte para o cliente Javascript é fornecido pelo @aspnet/signalr-protocol-msgpack pacote NPM.
npm install @aspnet/signalr-protocol-msgpack
Depois de instalar o pacote npm, o módulo pode ser usado diretamente por meio de um carregador de módulo
de JavaScript ou importado para o navegador fazendo referência a node_modules\@aspnet\signalr-protocol-
msgpack\dist\browser\signalr-protocol-msgpack.js arquivo. Em um navegador, o msgpack5 biblioteca também
deve ser referenciada. Use um <script> marca para criar uma referência. A biblioteca pode ser encontrada em
node_modules\msgpack5\dist\msgpack5.js.
NOTE
Ao usar o <script> elemento, a ordem é importante. Se signalr-protocol-msgpack.js é referenciada antes msgpack5.js,
ocorre um erro quando tentar se conectar com MessagePack. SignalR.js também é necessária antes signalr-protocol-
msgpack.js.
<script src="~/lib/signalr/signalr.js"></script>
<script src="~/lib/msgpack5/msgpack5.js"></script>
<script src="~/lib/signalr/signalr-protocol-msgpack.js"></script>
Adicionando .withHubProtocol(new signalR.protocols.msgpack.MessagePackHubProtocol()) para o

HubConnectionBuilder irá configurar o cliente para usar o protocolo MessagePack ao se conectar a um servidor.

.withHubProtocol(new signalR.protocols.msgpack.MessagePackHubProtocol())
.build();
NOTE
Neste momento, não há nenhuma opção de configuração para o protocolo MessagePack no cliente JavaScript.
Introdução
Cliente .NET
Cliente JavaScript
Usar o streaming em SignalR do ASP.NET Core
Por Brennan Conroy

SignalR do ASP.NET Core dá suporte a streaming valores de retorno dos métodos de servidor. Isso é útil para
cenários em que os fragmentos de dados serão apresentadas ao longo do tempo. Quando um valor de retorno é
transmitido ao cliente, cada fragmento é enviado ao cliente assim que ele se torna disponível, em vez de aguardar
que todos os dados fiquem disponíveis.
Configurar o hub
Um método de hub automaticamente se torna um método de hub streaming quando ele retorna um
ChannelReader<T> ou um Task<ChannelReader<T>> . Abaixo está um exemplo que mostra os conceitos básicos do
fluxo de dados para o cliente. Sempre que um objeto é gravado o ChannelReader esse objeto é enviado
imediatamente para o cliente. No final, o ChannelReader estiver concluído para dizer ao cliente o fluxo está
fechado.
NOTE
Gravar o ChannelReader em um thread em segundo plano e retorne o ChannelReader assim que possível. Outras
chamadas de hub serão bloqueadas até que um ChannelReader é retornado.
public class StreamHub : Hub

{
public ChannelReader<int> Counter(int count, int delay)
{
var channel = Channel.CreateUnbounded<int>();
// We don't want to await WriteItems, otherwise we'd end up waiting

// for all the items to be written before returning the channel back to
// the client.
_ = WriteItems(channel.Writer, count, delay);
return channel.Reader;
}
private async Task WriteItems(ChannelWriter<int> writer, int count, int delay)

{
for (var i = 0; i < count; i++)
{
await writer.WriteAsync(i);
await Task.Delay(delay);
}
writer.TryComplete();
}
}
Cliente .NET
O StreamAsChannelAsync método no HubConnection é usado para invocar um método de transmissão. Passe o
nome do método de hub e argumentos definidos no método de hub para StreamAsChannelAsync . O parâmetro
genérico em StreamAsChannelAsync<T> Especifica o tipo de objetos retornados pelo método de transmissão. Um
ChannelReader<T> é retornada da invocação de fluxo e representa o fluxo no cliente. Para ler dados, um padrão
comum é executar um loop sobre WaitToReadAsync e chamar TryRead quando os dados estiverem disponíveis. O
loop terminará quando o fluxo foi fechado pelo servidor ou o token de cancelamento passado para
StreamAsChannelAsync é cancelada.
var channel = await hubConnection.StreamAsChannelAsync<int>("Counter", 10, 500, CancellationToken.None);
// Wait asynchronously for data to become available

while (await channel.WaitToReadAsync())
{
// Read all currently available data synchronously, before waiting for more data
while (channel.TryRead(out var count))
{
Console.WriteLine($"{count}");
}
}
Console.WriteLine("Streaming completed");
Cliente JavaScript
Os clientes JavaScript chamar métodos de streaming em hubs usando connection.stream .O stream método
aceita dois argumentos:
O nome do método de hub. No exemplo a seguir, o nome do método de hub é Counter .
Argumentos definidos no método de hub. No exemplo a seguir, os argumentos são: uma contagem do número
de itens de fluxo para receber e o atraso entre itens de fluxo.
connection.stream Retorna um IStreamResult que contém um subscribe método. Passar uma
IStreamSubscriber para subscribe e defina as next , error , e complete retornos de chamada para receber as
notificações a stream invocação.
connection.stream("Counter", 10, 500)

.subscribe({
next: (item) => {
li.textContent = item;
},
complete: () => {
li.textContent = "Stream completed";
},
error: (err) => {
li.textContent = err;
},
});
Para terminar o fluxo do cliente, chame o dispose método em de ISubscription que é retornado do subscribe
método.
Hubs
Cliente .NET
Cliente JavaScript
Publicar no Azure
Diferenças entre o SignalR do ASP.NET e o SignalR
do ASP.NET Core
SignalR do ASP.NET Core não é compatível com clientes ou servidores para ASP.NET SignalR. Este artigo fornece
detalhes sobre os recursos que foram removidos ou alterados no SignalR do ASP.NET Core.
Como identificar a versão do SignalR

ASP.NET SIGNALR SIGNALR DO ASP.NET CORE
Pacote do NuGet Server Microsoft.AspNet.SignalR Microsoft (.NET Core)

Microsoft (.NET Framework)
Pacotes NuGet de cliente ASPNET Aspnetcore

Microsoft.AspNet.SignalR.JS
Pacote npm de cliente SignalR @aspnet/signalr
Tipo de aplicativo de servidor ASP.NET (System. Web) ou a auto- ASP.NET Core

hospedagem de OWIN
Plataformas de servidor com suporte .NET framework 4.5 ou posterior .NET Framework 4.6.1 ou posterior
.NET core 2.1 ou posterior
Diferenças de recursos
Reconexão automática
Reconexão automática não têm suporte no SignalR do ASP.NET Core. Se o cliente for desconectado, o usuário
explicitamente deve iniciar uma nova conexão, se eles desejam se reconectar. No ASP.NET SignalR, SignalR
tentará reconectar-se ao servidor se a conexão for interrompida.
Suporte de protocolo
SignalR do ASP.NET Core dá suporte a JSON, bem como um novo protocolo binário, com base em MessagePack.
Além disso, os protocolos personalizados podem ser criados.
Diferenças no servidor
As bibliotecas do lado do servidor SignalR do ASP.NET Core são incluídas na metapacote do Microsoft que faz
parte do pacote a aplicativo Web ASP.NET Core modelo Razor e MVC projetos.
SignalR do ASP.NET Core é um middleware do ASP.NET Core, portanto, ele deve ser configurado por meio da
chamada AddSignalR em Startup.ConfigureServices .
Para configurar o roteamento, mapear as rotas para os hubs de dentro de UseSignalR chamada de método no
Startup.Configure método.
{
routes.MapHub<ChatHub>("/hub");
});
Sessões temporárias
O modelo de expansão do SignalR do ASP.NET permite que os clientes para se reconectar e enviar mensagens
para qualquer servidor no farm. No SignalR do ASP.NET Core, o cliente deve interagir com o mesmo servidor
durante a conexão. Para escala horizontal usando Redis, isso significa que as sessões temporárias são necessárias.
Para o uso de expansão serviço do Azure SignalR , sessões temporárias não são necessárias porque o serviço lida
com as conexões aos clientes.
Hub único por conexão
O SignalR do ASP.NET Core, o modelo de conexão foi simplificado. As conexões são feitas diretamente a um único
hub, em vez de uma única conexão está sendo usado para compartilhar o acesso a vários hubs.
Streaming
ASP.NET SignalR Core agora dá suporte à dados de streaming do hub para o cliente.
Estado
A capacidade de passar o estado arbitrário entre clientes e o hub (geralmente chamado de HubState) foi removida,
bem como suporte para mensagens de progresso. Não há nenhum equivalente de proxies de hub no momento.
Diferenças no cliente
TypeScript
O cliente SignalR do ASP.NET Core é escrito em TypeScript. Você pode escrever em JavaScript ou TypeScript ao
usar o cliente JavaScript.
O cliente JavaScript é hospedado em npm
Nas versões anteriores, o cliente JavaScript foi obtido por meio de um pacote do NuGet no Visual Studio. Para as
versões de núcleo, o @aspnet/signalr pacote npm contém as bibliotecas de JavaScript. Este pacote não está
incluído na aplicativo Web ASP.NET Core modelo. Usar npm para obter e instalar o @aspnet/signalr pacote
npm.
npm init -y
jQuery
A dependência no jQuery foi removida, no entanto, projetos ainda podem usar jQuery.
Sintaxe de método de cliente JavaScript
A sintaxe de JavaScript foi alterado da versão anterior do SignalR. Em vez de usar o $connection de objeto, criar
uma conexão usando o HubConnectionBuilder API.

.withUrl("/hub")
.build();
Use o em método para especificar que o hub pode chamar métodos do cliente.
connection.on("ReceiveMessage", (user, message) => {
const msg = message.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
const encodedMsg = user + " says " + msg;
log(encodedMsg);
});
Depois de criar o método do cliente, inicie a conexão de hub. Cadeia de um catch método para fazer logon ou lidar
com erros.
Proxies de Hub
Os proxies de Hub não automaticamente são gerados. Em vez disso, o nome do método é passado para o invocar
API como uma cadeia de caracteres.
.NET e outros clientes
O Microsoft.AspNetCore.SignalR.Client pacote NuGet contém as bibliotecas de cliente .NET para o SignalR do
ASP.NET Core.
Use o HubConnectionBuilder para criar e compilar uma instância de uma conexão a um hub.
connection = new HubConnectionBuilder()

.WithUrl("url")
.Build();
Diferenças de expansão
SignalR do ASP.NET oferece suporte a SQL Server e o Redis. SignalR do ASP.NET Core dá suporte ao serviço do
Azure SignalR e Redis.
ASP.NET
Expansão do SignalR com o barramento de serviço do Azure
Expansão do SignalR com Redis
Expansão do SignalR com o SQL Server
ASP.NET Core
Serviço Azure SignalR
Recursos adicionais
Hubs
Cliente JavaScript
Cliente .NET
Plataformas compatíveis
Suporte ao WebSockets no ASP.NET Core
Por Tom Dykstra e Andrew Stanton-Nurse

Este artigo explica como começar a usar o WebSockets no ASP.NET Core. WebSocket (RFC 6455) é um
protocolo que permite canais de comunicação persistentes bidirecionais em conexões TCP. Ele é usado em
aplicativos que se beneficiam de comunicação rápida e em tempo real, como chat, painel e aplicativos de jogos.
Exibir ou baixar um código de exemplo (como baixar). Confira a seção Próximas etapas para obter mais
informações.
Pré-requisitos
ASP.NET Core 1.1 ou posterior
Qualquer sistema operacional compatível com o ASP.NET Core:
Windows 7/Windows Server 2008 ou posterior
Linux
macOS
Se o aplicativo é executado no Windows com o IIS:
IIS 8/IIS 8 Express
WebSockets precisam ser habilitados (confira a seção Suporte para IIS/IIS Express).
Se o aplicativo é executado no HTTP.sys:
Para saber quais são os navegadores compatíveis, confira https://caniuse.com/#feat=websockets.
Quando usar WebSockets

Use WebSockets para trabalhar diretamente com uma conexão de soquete. Por exemplo, use WebSockets para
obter o melhor desempenho possível em um jogo em tempo real.
SignalR do ASP.NET Core é uma biblioteca que simplifica a adição da funcionalidade da Web em tempo real aos
aplicativos. Ele usa WebSockets sempre que possível.
Como usar WebSockets

Instale o pacote Microsoft.AspNetCore.WebSockets.
Configure o middleware.
Aceite solicitações do WebSocket.
Envie e receba mensagens.
Configurar o middleware
Adicione o middleware do WebSockets no método Configure da classe Startup :
app.UseWebSockets();
app.UseWebSockets();
As seguintes configurações podem ser definidas:

KeepAliveInterval – a frequência para enviar quadros "ping" ao cliente para garantir que os proxies
mantenham a conexão aberta.
ReceiveBufferSize – o tamanho do buffer usado para receber dados. Os usuários avançados podem precisar
alterar isso para ajuste de desempenho com base no tamanho dos dados.
var webSocketOptions = new WebSocketOptions()

{
KeepAliveInterval = TimeSpan.FromSeconds(120),
ReceiveBufferSize = 4 * 1024
};
app.UseWebSockets(webSocketOptions);
var webSocketOptions = new WebSocketOptions()

{
KeepAliveInterval = TimeSpan.FromSeconds(120),
ReceiveBufferSize = 4 * 1024
};
app.UseWebSockets(webSocketOptions);
Aceitar solicitações do WebSocket

Em algum lugar e em um momento futuro no ciclo de vida da solicitação (posteriormente no método Configure
ou em uma ação do MVC, por exemplo), verifique se é uma solicitação do WebSocket e aceite-a.
O exemplo a seguir é de uma fase posterior do método Configure :

{
if (context.Request.Path == "/ws")
{
if (context.WebSockets.IsWebSocketRequest)
{
WebSocket webSocket = await context.WebSockets.AcceptWebSocketAsync();
await Echo(context, webSocket);
}
else
{
}
}
else
{
await next();
}
});
{
if (context.Request.Path == "/ws")
{
{
await Echo(context, webSocket);
}
else
{
}
}
else
{
await next();
}
});
Uma solicitação do WebSocket pode entrar em qualquer URL, mas esse código de exemplo aceita apenas
solicitações de /ws .
Enviar e receber mensagens
O método AcceptWebSocketAsync atualiza a conexão TCP para uma conexão WebSocket e fornece um objeto
WebSocket. Use o objeto WebSocket para enviar e receber mensagens.
O código mostrado anteriormente que aceita a solicitação do WebSocket passa o objeto WebSocket para um
método Echo . O código recebe uma mensagem e envia de volta imediatamente a mesma mensagem. As
mensagens são enviadas e recebidas em um loop até que o cliente feche a conexão:
private async Task Echo(HttpContext context, WebSocket webSocket)

{
var buffer = new byte[1024 * 4];
WebSocketReceiveResult result = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer),
CancellationToken.None);
while (!result.CloseStatus.HasValue)
{
await webSocket.SendAsync(new ArraySegment<byte>(buffer, 0, result.Count), result.MessageType,
result.EndOfMessage, CancellationToken.None);
result = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);

}
await webSocket.CloseAsync(result.CloseStatus.Value, result.CloseStatusDescription,
}
private async Task Echo(HttpContext context, WebSocket webSocket)
{
var buffer = new byte[1024 * 4];
WebSocketReceiveResult result = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer),
while (!result.CloseStatus.HasValue)
{
await webSocket.SendAsync(new ArraySegment<byte>(buffer, 0, result.Count), result.MessageType,
result.EndOfMessage, CancellationToken.None);
result = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);

}
await webSocket.CloseAsync(result.CloseStatus.Value, result.CloseStatusDescription,
}
Ao aceitar a conexão WebSocket antes de iniciar o loop, o pipeline de middleware é encerrado. Ao fechar o
soquete, o pipeline é desenrolado. Ou seja, a solicitação deixa de avançar no pipeline quando o WebSocket é
aceito. Quando o loop é concluído e o soquete é fechado, a solicitação continua a avançar no pipeline.
Suporte ao IIS/IIS Express

O Windows Server 2012 ou posterior e o Windows 8 ou posterior com o IIS/IIS Express 8 ou posterior são
compatíveis com o protocolo WebSocket.
NOTE
WebSockets estão sempre habilitados ao usar o IIS Express.
Habilitar WebSockets no IIS

Para habilitar o suporte para o protocolo WebSocket no Windows Server 2012 ou posterior:
NOTE
Estas etapas não são necessárias ao usar o IIS Express
1. Use o assistente Adicionar Funções e Recursos por meio do menu Gerenciar ou do link no Gerenciador
do Servidor.
2. Selecione Instalação baseada em função ou em recurso. Selecione Avançar.
3. Selecione o servidor apropriado (o servidor local é selecionado por padrão). Selecione Avançar.
4. Expanda Servidor Web (IIS ) na árvore Funções, expanda Servidor Web e, em seguida, expanda
Desenvolvimento de Aplicativos.
5. Selecione o Protocolo WebSocket. Selecione Avançar.
6. Se não forem necessários recursos adicionais, selecione Avançar.
7. Clique em Instalar.
8. Quando a instalação for concluída, selecione Fechar para sair do assistente.
Para habilitar o suporte para o protocolo WebSocket no Windows 8 ou posterior:
NOTE
Estas etapas não são necessárias ao usar o IIS Express
1. Navegue para Painel de Controle > Programas > Programas e Recursos > Ativar ou desativar recursos
do Windows (lado esquerdo da tela).
2. Abra os nós a seguir: Serviços de Informações da Internet > Serviços da World Wide Web > Recursos
de Desenvolvimento de Aplicativos.
3. Selecione o recurso Protocolo WebSocket. Selecione OK.
Desabilite o WebSocket ao usar o socket.io no Node.js
Se você estiver usando o suporte do WebSocket no socket.io no Node.js, desabilite o módulo do WebSocket do
IIS padrão usando o elemento webSocket em web.config ou em applicationHost.config. Se essa etapa não for
executada, o módulo do WebSocket do IIS tentará manipular a comunicação do WebSocket em vez do Node.js e
o aplicativo.
<system.webServer>
<webSocket enabled="false" />
</system.webServer>
Próximas etapas
O aplicativo de exemplo que acompanha este artigo é um aplicativo de eco. Ele tem uma página da Web que faz
conexões WebSocket e o servidor reenvia para o cliente todas as mensagens recebidas. Execute o aplicativo em
um prompt de comando (ele não está configurado para execução no Visual Studio com o IIS Express) e navegue
para http://localhost:5000. A página da Web exibe o status de conexão no canto superior esquerdo:
Selecione Conectar para enviar uma solicitação WebSocket para a URL exibida. Insira uma mensagem de teste e
selecione Enviar. Quando terminar, selecione Fechar Soquete. A seção Log de Comunicação relata cada ação
de abertura, envio e fechamento conforme ela ocorre.
Testes de unidade de páginas do Razor no ASP.NET
Core
Por Luke Latham

ASP.NET Core dá suporte a testes de unidade de aplicativos de páginas do Razor. Testes dos dados (DAL ) da
camada de acesso e modelos de página ajudam a garantir:
Partes de um aplicativo páginas Razor trabalhem independentemente ou em conjunto como uma unidade
durante a construção do aplicativo.
Classes e métodos limitaram escopos de responsabilidade.
Existe documentação adicional sobre como o aplicativo deve se comportar.
As regressões, que são trazidos por atualizações para o código de erros, são encontradas durante a
implantação e compilação automatizada.
Este tópico pressupõe que você tenha uma compreensão básica dos aplicativos das páginas do Razor e testes de
unidade. Se você estiver familiarizado com conceitos de teste ou de aplicativos de páginas do Razor, consulte os
tópicos a seguir:
Teste de unidade em C# no .NET Core usando dotnet test e xUnit
O projeto de exemplo é composto de dois aplicativos:
APLICATIVO PASTA DO PROJETO DESCRIÇÃO
Aplicativo de mensagens src/RazorPagesTestSample Permite que um usuário adicione,

exclua uma, excluir todas as e analisar
as mensagens.
Aplicativo de teste tests/RazorPagesTestSample.Tests Usado para o aplicativo de mensagem

de teste de unidade: acesso a dados
(DAL) de camada e o modelo de página
de índice.
Os testes podem ser executados usando os recursos de teste interno de um IDE, como Visual Studio. Se usando
Visual Studio Code ou a linha de comando, execute o seguinte comando em um prompt de comando na
tests/RazorPagesTestSample.Tests pasta:
dotnet test
Organização de aplicativo de mensagem

O aplicativo de mensagem é um sistema de mensagem de páginas do Razor simples com as seguintes
características:
A página de índice do aplicativo (Pages e Pages/Index.cshtml.cs) fornece uma interface do usuário e a página
de métodos de modelo para controlar a adição, exclusão e análise de mensagens (palavras médias por
mensagem) .
Uma mensagem é descrita pela Message classe (Data/Message.cs) com duas propriedades: Id (chave) e
Text (mensagem ). O Text propriedade é necessária e é limitada a 200 caracteres.
As mensagens são armazenadas usando banco de dados do Entity Framework na memória†.
O aplicativo contém uma camada de acesso de dados (DAL ) na sua classe de contexto do banco de dados,
AppDbContext ( Data/AppDbContext.cs). Os métodos DAL são marcados como virtual , que permite que os
métodos para uso em testes de simulação.
Se o banco de dados está vazio na inicialização do aplicativo, o repositório de mensagens é inicializado com
três mensagens. Eles propagado mensagens também são usados em testes.
†O tópico EF testar com InMemory, explica como usar um banco de dados na memória para testes com MSTest.
Este tópico usa o xUnit estrutura de teste. Conceitos de teste e teste implementações em estruturas de teste
diferentes são semelhantes, mas não idênticos.
Embora o aplicativo não usa o padrão de repositório e não é um exemplo efetivação do padrão de unidade de
trabalho (UoW ), páginas do Razor dá suporte a esses padrões de desenvolvimento. Para obter mais informações,
consulte Projetando a camada de persistência de infraestrutura e lógica do controlador de teste (o exemplo
implementa o padrão de repositório).
Organização de aplicativo de teste

O aplicativo de teste é um aplicativo de console dentro de tests/RazorPagesTestSample.Tests pasta.
PASTA DO APLICATIVO DE TESTE DESCRIÇÃO
UnitTests DataAccessLayerTest.cs contém os testes de unidade

para o DAL.
IndexPageTests.cs contém os testes de unidade para o
modelo de página de índice.
Utilitários Contém o TestingDbContextOptions método usado para

criar o novo banco de dados opções de contexto para cada
teste de unidade da DAL, de modo que o banco de dados é
redefinido como sua condição de linha de base para cada
teste.
É a estrutura de teste xUnit. É o objeto de objetos fictícios Moq.
Testes de unidade de dados (DAL) da camada de acesso

O aplicativo de mensagem tem uma DAL com quatro métodos contidos na AppDbContext classe
(src/RazorPagesTestSample/Data/AppDbContext.cs). Cada método tem um ou dois testes de unidade no
aplicativo de teste.
MÉTODO DAL FUNÇÃO
GetMessagesAsync Obtém uma List<Message> do banco de dados classificado

pelo Text propriedade.
AddMessageAsync Adiciona um Message no banco de dados.

MÉTODO DAL FUNÇÃO
DeleteAllMessagesAsync Exclui todos os Message entradas do banco de dados.
DeleteMessageAsync Exclui um único Message do banco de dados por Id .
Testes de unidade da DAL requerem DbContextOptions ao criar um novo AppDbContext para cada teste. Uma
abordagem para criar o DbContextOptions para cada teste é usar um DbContextOptionsBuilder:
var optionsBuilder = new DbContextOptionsBuilder<AppDbContext>()

.UseInMemoryDatabase("InMemoryDb");
using (var db = new AppDbContext(optionsBuilder.Options))

{
// Use the db here in the unit test.
}
O problema com essa abordagem é que cada teste recebe o banco de dados no estado em que o teste anterior a
deixou. Isso pode ser um problema ao tentar escrever testes de unidade atômica que não interfiram uns aos
outros. Para forçar o AppDbContext para usar um novo contexto de banco de dados para cada teste, forneça um
DbContextOptions instância com base em um novo provedor de serviço. O aplicativo de teste mostra como fazer
isso usando seus Utilities método de classe TestingDbContextOptions
(tests/RazorPagesTestSample.Tests/Utilities/Utilities.cs):
public static DbContextOptions<AppDbContext> TestDbContextOptions()

{
// Create a new service provider to create a new in-memory database.
var serviceProvider = new ServiceCollection()
.AddEntityFrameworkInMemoryDatabase()
.BuildServiceProvider();
// Create a new options instance using an in-memory database and

// IServiceProvider that the context should resolve all of its
// services from.
var builder = new DbContextOptionsBuilder<AppDbContext>()
.UseInMemoryDatabase("InMemoryDb")
.UseInternalServiceProvider(serviceProvider);
return builder.Options;
}
Usando o DbContextOptions na unidade de DAL testes permite que cada teste executado atomicamente com uma
instância de banco de dados atualizado:
using (var db = new AppDbContext(Utilities.TestingDbContextOptions()))

{
// Use the db here in the unit test.
}
Cada método de teste na DataAccessLayerTest classe (UnitTests/DataAccessLayerTest.cs) segue um padrão

semelhante Arrange, Act-Assert:
1. Organizar: O banco de dados está configurado para o teste de e/ou o resultado esperado é definido.
2. O ACT: O teste é executado.
3. Assert: Asserções são feitas para determinar se o resultado do teste é um sucesso.
Por exemplo, o DeleteMessageAsync método é responsável por remover uma única mensagem identificada pelo
seu Id (src/RazorPagesTestSample/Data/AppDbContext.cs):
public async virtual Task DeleteMessageAsync(int id)

{
var message = await Messages.FindAsync(id);
if (message != null)
{
Messages.Remove(message);
await SaveChangesAsync();
}
}
Há dois testes para esse método. Um teste verifica que o método exclui uma mensagem quando a mensagem
estiver presente no banco de dados. Os outros testes de método que o banco de dados não serão alteradas se a
mensagem Id para exclusão não existe. O DeleteMessageAsync_MessageIsDeleted_WhenMessageIsFound método é
mostrado abaixo:
[Fact]
public async Task DeleteMessageAsync_MessageIsDeleted_WhenMessageIsFound()
{
using (var db = new AppDbContext(Utilities.TestDbContextOptions()))
{
// Arrange
var seedMessages = AppDbContext.GetSeedingMessages();
await db.AddRangeAsync(seedMessages);
var recId = 1;
var expectedMessages =
seedMessages.Where(message => message.Id != recId).ToList();
// Act
await db.DeleteMessageAsync(recId);
// Assert
var actualMessages = await db.Messages.AsNoTracking().ToListAsync();
Assert.Equal(
expectedMessages.OrderBy(x => x.Id),
actualMessages.OrderBy(x => x.Id),
new Utilities.MessageComparer());
}
}
Primeiro, o método executa a etapa Arranjar, onde ocorre a preparação para a etapa atuar. As mensagens de
propagação são obtidas e mantidas em seedMessages . As mensagens de propagação são salvos no banco de
dados. A mensagem com um Id de 1 é definido para exclusão. Quando o DeleteMessageAsync método é
executado, as mensagens esperadas devem ter todas as mensagens, exceto aquele com um Id de 1 . O
expectedMessages variável representa esse resultado esperado.
// Arrange
var seedMessages = AppDbContext.GetSeedingMessages();
await db.AddRangeAsync(seedMessages);
var recId = 1;
var expectedMessages =
seedMessages.Where(message => message.Id != recId).ToList();
O método funciona: O DeleteMessageAsync método é executado passando a recId de 1 :

// Act
Por fim, o método obtém o Messages do contexto e o compara a expectedMessages declarando que os dois são
iguais:
// Assert
Assert.Equal(
expectedMessages.OrderBy(m => m.Id).Select(m => m.Text),
actualMessages.OrderBy(m => m.Id).Select(m => m.Text));
Para comparar os dois List<Message> são os mesmos:

As mensagens são ordenadas por Id .
Pares de mensagens são comparados no Text propriedade.
Um método de teste semelhante, DeleteMessageAsync_NoMessageIsDeleted_WhenMessageIsNotFound verifica o

resultado da tentativa de excluir uma mensagem que não existe. Nesse caso, as mensagens esperadas no banco
de dados devem ser iguais para as mensagens reais após o DeleteMessageAsync método é executado. Não deve
haver nenhuma alteração para o conteúdo do banco de dados:
[Fact]
public async Task DeleteMessageAsync_NoMessageIsDeleted_WhenMessageIsNotFound()
{
using (var db = new AppDbContext(Utilities.TestDbContextOptions()))
{
// Arrange
var expectedMessages = AppDbContext.GetSeedingMessages();
await db.AddRangeAsync(expectedMessages);
var recId = 4;
// Act
// Assert
Assert.Equal(
}
}
Testes de unidade dos métodos do modelo de página

Outro conjunto de testes de unidade é responsável por testes de métodos do modelo de página. No aplicativo de
mensagem, os modelos de página de índice são encontrados na IndexModel classe
src/RazorPagesTestSample/Pages/Index.cshtml.cs.
MÉTODO DE MODELO DE PÁGINA FUNÇÃO
OnGetAsync Obtém as mensagens de DAL para a interface do usuário

usando o GetMessagesAsync método.
MÉTODO DE MODELO DE PÁGINA FUNÇÃO
OnPostAddMessageAsync Se o ModelState é válido, as chamadas AddMessageAsync

para adicionar uma mensagem para o banco de dados.
OnPostDeleteAllMessagesAsync Chamadas DeleteAllMessagesAsync para excluir todas as

mensagens no banco de dados.
OnPostDeleteMessageAsync Executa DeleteMessageAsync para excluir uma mensagem

com o Id especificado.
OnPostAnalyzeMessagesAsync Se uma ou mais mensagens estão no banco de dados, calcula

o número médio de palavras por mensagem.
Os métodos de modelo de página são testados usando testes de sete na IndexPageTests classe
(tests/RazorPagesTestSample.Tests/UnitTests/IndexPageTests.cs). Os testes de usam o padrão de Act Assert
organizar familiar. Esses testes se concentram em:
Determinando se os métodos seguem o comportamento correto quando o ModelState é inválido.
Confirmar os métodos produzem correto IActionResult .
Verificando-se de que as atribuições de valor de propriedade são feitas corretamente.
Geralmente, esse grupo de testes de simular os métodos da DAL para produzir os dados esperados para a etapa
atuar em que um método de modelo de página é executado. Por exemplo, o GetMessagesAsync método da
AppDbContext é simulado para produzir uma saída. Quando este método é executado um método de modelo de
página, a simulação retorna o resultado. Os dados não vem do banco de dados. Isso cria condições de teste
previsível e confiável para uso a DAL nos testes de modelo de página.
O OnGetAsync_PopulatesThePageModel_WithAListOfMessages teste mostra como o GetMessagesAsync método é
simulado para o modelo de página:
var mockAppDbContext = new Mock<AppDbContext>(optionsBuilder.Options);

mockAppDbContext.Setup(
db => db.GetMessagesAsync()).Returns(Task.FromResult(expectedMessages));
var pageModel = new IndexModel(mockAppDbContext.Object);
Quando o OnGetAsync método é executado na etapa Act, ela chama o modelo de página GetMessagesAsync
método.
Etapa atuar de teste de unidade (tests/RazorPagesTestSample.Tests/UnitTests/IndexPageTests.cs):
// Act
await pageModel.OnGetAsync();
IndexPage modelo de página OnGetAsync método (src/RazorPagesTestSample/Pages/Index.cshtml.cs):

{
Messages = await _db.GetMessagesAsync();
}
O GetMessagesAsync método no DAL não retornar o resultado para esta chamada de método. A versão fictícia do
método retorna o resultado.
No Assert etapa, as mensagens reais ( actualMessages ) são atribuídos a partir de Messages propriedade do
modelo de página. Uma verificação de tipo também é executada quando as mensagens são atribuídas. As
mensagens esperadas e reais são comparadas por seus Text propriedades. O teste declara que os dois
List<Message> instâncias contêm as mesmas mensagens.
// Assert
var actualMessages = Assert.IsAssignableFrom<List<Message>>(pageModel.Messages);
Assert.Equal(
Outros testes neste grupo Criar página de objetos de modelo que incluam o DefaultHttpContext , o
ModelStateDictionary , um ActionContext para estabelecer a PageContext , um ViewDataDictionary e um
PageContext . Elas são úteis na realização de testes. Por exemplo, o aplicativo de mensagens estabelece uma
ModelState erro com AddModelError para verificar se válido PageResult é retornado quando
OnPostAddMessageAsync é executado:
[Fact]
public async Task OnPostAddMessageAsync_ReturnsAPageResult_WhenModelStateIsInvalid()
{
// Arrange
var optionsBuilder = new DbContextOptionsBuilder<AppDbContext>()
.UseInMemoryDatabase("InMemoryDb");
var mockAppDbContext = new Mock<AppDbContext>(optionsBuilder.Options);
mockAppDbContext.Setup(db => db.GetMessagesAsync()).Returns(Task.FromResult(expectedMessages));
var httpContext = new DefaultHttpContext();
var modelState = new ModelStateDictionary();
var actionContext = new ActionContext(httpContext, new RouteData(), new PageActionDescriptor(),
modelState);
var modelMetadataProvider = new EmptyModelMetadataProvider();
var viewData = new ViewDataDictionary(modelMetadataProvider, modelState);
var tempData = new TempDataDictionary(httpContext, Mock.Of<ITempDataProvider>());
var pageContext = new PageContext(actionContext)
{
ViewData = viewData
};
var pageModel = new IndexModel(mockAppDbContext.Object)
{
PageContext = pageContext,
TempData = tempData,
Url = new UrlHelper(actionContext)
};
pageModel.ModelState.AddModelError("Message.Text", "The Text field is required.");
// Act
var result = await pageModel.OnPostAddMessageAsync();
// Assert
Assert.IsType<PageResult>(result);
}
Recursos adicionais
Teste de unidade em C# no .NET Core usando dotnet test e xUnit
Seu código de teste de unidade (Visual Studio)
xUnit.net
Guia de Introdução xUnit.net (.NET Core/ASP.NET Core)
Moq
Guia de início rápido Moq
Lógica do controlador de teste no ASP.NET Core
Por Steve Smith

Controladores desempenham um papel central em qualquer aplicativo ASP.NET Core MVC. Assim, você precisa
estar confiante de que os controladores se comportarão conforme o esperado. Testes automatizados podem
detectar erros antes do aplicativo ser implantado em um ambiente de produção.
Testes de unidade da lógica do controlador

Os testes de unidade envolvem o teste de uma parte de um aplicativo isoladamente em relação à sua
infraestrutura e às suas dependências. Quando a unidade está testando a lógica do controlador, somente o
conteúdo de uma única ação é testada, não o comportamento de suas dependências ou da estrutura em si.
Configure testes de unidade de ações do controlador para se concentrarem no comportamento do controlador.
Um teste de unidade do controlador evita cenários como filtros, roteamento ou model binding. Os testes que
abrangem as interações entre os componentes que respondem coletivamente a uma solicitação são
manipulados pelos testes de integração. Para obter mais informações sobre os testes de integração, consulte
Testes de integração no ASP.NET Core.
Se você estiver escrevendo filtros e rotas personalizados, realize testes de unidade neles de forma isolada, não
como parte dos testes em uma ação do controlador específica.
Para demonstrar testes de unidade do controlador, examine o controlador a seguir no aplicativo de exemplo. O
controlador Home exibe uma lista de sessões de debate e permite que novas sessões sejam criadas com uma
solicitação POST:
{
public HomeController(IBrainstormSessionRepository sessionRepository)

{
}

{
var sessionList = await _sessionRepository.ListAsync();
var model = sessionList.Select(session => new StormSessionViewModel()

{
Id = session.Id,
IdeaCount = session.Ideas.Count
});
return View(model);
}
public class NewSessionModel

{
[Required]
public string SessionName { get; set; }
}
[HttpPost]
public async Task<IActionResult> Index(NewSessionModel model)
{
{
}
else
{
await _sessionRepository.AddAsync(new BrainstormSession()
{
Name = model.SessionName
});
}
return RedirectToAction(actionName: nameof(Index));

}
}
O controlador anterior:
Segue o Princípio de Dependências Explícitas.
Espera DI (injeção de dependência) para fornecer uma instância de IBrainstormSessionRepository .
Pode ser testado com um serviço IBrainstormSessionRepository fictício usando uma estrutura de objeto
fictício, como Moq. Um objeto fictício é um objeto fabricado com um conjunto predeterminado de
comportamentos de propriedade e de método usado para teste. Para saber mais, consulte Introdução aos
testes de integração.
O método HTTP GET Index não tem nenhum loop ou branch e chama apenas um método. O teste de unidade
para esta ação:
Imita o serviço IBrainstormSessionRepository usando o método GetTestSessions . GetTestSessions cria duas
sessões de debate fictícias com datas e nomes de sessão.
Executa o método Index .
Faz declarações sobre o resultado retornado pelo método:
Um ViewResult é retornado.
O ViewDataDictionary.Model é um StormSessionViewModel .
Há duas sessões de debate armazenadas no ViewDataDictionary.Model .
[Fact]
public async Task Index_ReturnsAViewResult_WithAListOfBrainstormSessions()
{
// Arrange
// Act
var result = await controller.Index();
// Assert
var model = Assert.IsAssignableFrom<IEnumerable<StormSessionViewModel>>(
Assert.Equal(2, model.Count());
}
private List<BrainstormSession> GetTestSessions()

{
var sessions = new List<BrainstormSession>();
{
Id = 1,
Name = "Test One"
});
{
Id = 2,
Name = "Test Two"
});
return sessions;
}
Os testes método HTTP POST Index do controlador Home verificam se:

Quando ModelState.IsValid é false , o método de ação retorna uma 400 Solicitação inválida ViewResult
com os dados apropriados.
Quando ModelState.IsValid é true :
O método Add no repositório é chamado.
Um RedirectToActionResult é retornado com os argumentos corretos.
O estado de modelo inválido é testado por meio da adição de erros usando AddModelError, conforme
mostrado no primeiro teste abaixo:
[Fact]
public async Task IndexPost_ReturnsBadRequestResult_WhenModelStateIsInvalid()
{
// Arrange
controller.ModelState.AddModelError("SessionName", "Required");
var newSession = new HomeController.NewSessionModel();
// Act
// Assert
var badRequestResult = Assert.IsType<BadRequestObjectResult>(result);
Assert.IsType<SerializableError>(badRequestResult.Value);
}
[Fact]
public async Task IndexPost_ReturnsARedirectAndAddsSession_WhenModelStateIsValid()
{
// Arrange
mockRepo.Setup(repo => repo.AddAsync(It.IsAny<BrainstormSession>()))
.Verifiable();
var newSession = new HomeController.NewSessionModel()
{
SessionName = "Test Name"
};
// Act
// Assert
var redirectToActionResult = Assert.IsType<RedirectToActionResult>(result);
Assert.Null(redirectToActionResult.ControllerName);
mockRepo.Verify();
}
Quando ModelState não for válido, o mesmo ViewResult será retornado para uma solicitação GET. O teste não
tenta passar um modelo inválido. Passar um modelo inválido não é uma abordagem válida, visto que o model
binding não está em execução (embora um teste de integração use model binding). Nesse caso, o model binding
não está sendo testado. Esses testes de unidade estão testando apenas o código no método de ação.
O segundo teste verifica se, quando o ModelState é válido:
Um novo BrainstormSession é adicionado (por meio do repositório).
O método retorna um RedirectToActionResult com as propriedades esperadas.
Chamadas fictícias que não são chamadas são normalmente ignoradas, mas a chamada a Verifiable no final
da chamada de instalação permite a validação fictícia no teste. Isso é realizado com a chamada a
mockRepo.Verify , que não será aprovada no teste se o método esperado não tiver sido chamado.
NOTE
A biblioteca do Moq usada neste exemplo possibilita a combinação de simulações verificáveis ou "estritas" com simulações
não verificáveis (também chamadas de simulações "flexíveis" ou stubs). Saiba mais sobre como personalizar o
comportamento de Simulação com o Moq.
SessionController no exemplo de aplicativo exibe informações relacionadas a uma sessão de debate específica.
O controlador inclui lógica para lidar com valores id inválidos (há dois cenários return no exemplo a seguir
para abordar esses cenários). A última instrução return retorna um novo StormSessionViewModel para a
exibição (Controllers/SessionController.cs):
public class SessionController : Controller

{
public SessionController(IBrainstormSessionRepository sessionRepository)

{
}
public async Task<IActionResult> Index(int? id)

{
if (!id.HasValue)
{
return RedirectToAction(actionName: nameof(Index),
controllerName: "Home");
}
var session = await _sessionRepository.GetByIdAsync(id.Value);

{
return Content("Session not found.");
}
var viewModel = new StormSessionViewModel()

{
Id = session.Id
};
}
}
Os testes de unidade incluem um teste para cada cenário return na ação Index do controlador Session:
[Fact]
public async Task IndexReturnsARedirectToIndexHomeWhenIdIsNull()
{
// Arrange
var controller = new SessionController(sessionRepository: null);
// Act
var result = await controller.Index(id: null);
// Assert
var redirectToActionResult =
Assert.IsType<RedirectToActionResult>(result);
Assert.Equal("Home", redirectToActionResult.ControllerName);
}
[Fact]
public async Task IndexReturnsContentWithSessionNotFoundWhenSessionNotFound()
{
// Arrange
// Act
// Assert
var contentResult = Assert.IsType<ContentResult>(result);
Assert.Equal("Session not found.", contentResult.Content);
}
[Fact]
public async Task IndexReturnsViewResultWithStormSessionViewModel()
{
// Arrange
.ReturnsAsync(GetTestSessions().FirstOrDefault(
s => s.Id == testSessionId));
// Act
// Assert
var model = Assert.IsType<StormSessionViewModel>(
Assert.Equal("Test One", model.Name);
Assert.Equal(2, model.DateCreated.Day);
Assert.Equal(testSessionId, model.Id);
}
Mudando para o controlador Ideas, o aplicativo expõe a funcionalidade como uma API Web na rota api/ideas :
Uma lista de ideias ( IdeaDTO ) associada com uma sessão de debate é retornada pelo método ForSession .
O método Create adiciona novas ideias a uma sessão.
[HttpGet("forsession/{sessionId}")]
public async Task<IActionResult> ForSession(int sessionId)
{
{
}

{
Id = idea.Id,
Name = idea.Name,
}).ToList();
return Ok(result);
}
[HttpPost("create")]
public async Task<IActionResult> Create([FromBody]NewIdeaModel model)
{
{
}

{
}

{
Name = model.Name
};
return Ok(session);
}
Evite retornar entidades de domínio de negócios diretamente por meio de chamadas à API. Entidades de
domínio:
Geralmente incluem mais dados do que o cliente necessita.
Acople desnecessariamente o modelo de domínio interno do aplicativo à API exposta publicamente.
É possível executar o mapeamento entre entidades de domínio e os tipos retornados ao cliente:
Manualmente com um LINQ Select , como o aplicativo de exemplo usa. Para saber mais, consulte LINQ
(Consulta Integrada à Linguagem).
Automaticamente com uma biblioteca, como AutoMapper.
Em seguida, o aplicativo de exemplo demonstra os testes de unidade para os métodos de API Create e
ForSession do controlador Ideas.
O aplicativo de exemplo contém dois testes ForSession . O primeiro teste determina se ForSession retorna um
NotFoundObjectResult (HTTP não encontrado) para uma sessão inválida:
[Fact]
public async Task ForSession_ReturnsHttpNotFound_ForInvalidSession()
{
// Arrange
// Act
// Assert
var notFoundObjectResult = Assert.IsType<NotFoundObjectResult>(result);
Assert.Equal(testSessionId, notFoundObjectResult.Value);
}
O segundo teste ForSession determina se ForSession retorna uma lista de ideias de sessão ( <List<IdeaDTO>> )
para uma sessão válida. As verificações também examinam a primeira ideia para confirmar se sua propriedade
Name está correta:
[Fact]
public async Task ForSession_ReturnsIdeasForSession()
{
// Arrange
// Act
// Assert
var returnValue = Assert.IsType<List<IdeaDTO>>(okResult.Value);
}
Para testar o comportamento do método Create quando o ModelState é inválido, o aplicativo de exemplo
adiciona um erro de modelo ao controlador como parte do teste. Não tente testar a validação de modelos ou o
model binding em testes de unidade—teste apenas o comportamento do método de ação quando houver um
ModelState inválido:
[Fact]
public async Task Create_ReturnsBadRequest_GivenInvalidModel()
{
// Arrange & Act
// Act
var result = await controller.Create(model: null);
// Assert
Assert.IsType<BadRequestObjectResult>(result);
}
O segundo teste de Create depende do repositório retornar null , portanto, o repositório fictício é configurado
para retornar null . Não é necessário criar um banco de dados de teste (na memória ou de outro tipo) e
construir uma consulta que retornará esse resultado. O teste pode ser realizado em uma única instrução, como
mostrado no código de exemplo:
[Fact]
public async Task Create_ReturnsHttpNotFound_ForInvalidSession()
{
// Arrange
// Act
var result = await controller.Create(new NewIdeaModel());
// Assert
Assert.IsType<NotFoundObjectResult>(result);
}
O terceiro teste Create , Create_ReturnsNewlyCreatedIdeaForSession , verifica se o método UpdateAsync do

repositório é chamado. A simulação é chamada com Verifiable e o método Verify do repositório fictício é
chamado para confirmar se o método verificável é executado. Não é responsabilidade do teste de unidade
garantir que o método UpdateAsync salve os dados—isso pode ser realizado com um teste de integração.
[Fact]
public async Task Create_ReturnsNewlyCreatedIdeaForSession()
{
// Arrange

{
Name = testName,
};
.Verifiable();
// Act
var result = await controller.Create(newIdea);
// Assert
var returnSession = Assert.IsType<BrainstormSession>(okResult.Value);
mockRepo.Verify();
Assert.Equal(2, returnSession.Ideas.Count());
Assert.Equal(testName, returnSession.Ideas.LastOrDefault().Name);
Assert.Equal(testDescription, returnSession.Ideas.LastOrDefault().Description);
}
Testar ActionResult<T>
No ASP.NET Core 2.1 ou posterior, o ActionResult<T> (ActionResult<TValue>) permite que você retorne um
tipo derivado de ActionResult ou retorne um tipo específico.
O aplicativo de exemplo inclui um método que retorna um List<IdeaDTO> para uma sessão id determinada.
Se a sessão id não existir, o controlador retornará NotFound:
[HttpGet("forsessionactionresult/{sessionId}")]
public async Task<ActionResult<List<IdeaDTO>>> ForSessionActionResult(int sessionId)
{
{
}

{
Id = idea.Id,
Name = idea.Name,
}).ToList();
return result;
}
Dois testes do controlador ForSessionActionResult estão incluídos no ApiIdeasControllerTests .

O primeiro teste confirma se o controlador retorna um ActionResult , mas não uma lista de ideias inexistente
para uma sessão id inexistente:
O tipo ActionResult<List<IdeaDTO>> é ActionResult .
O Result é um NotFoundObjectResult.
[Fact]
public async Task ForSessionActionResult_ReturnsNotFoundObjectResultForNonexistentSession()
{
// Arrange
// Act
var result = await controller.ForSessionActionResult(nonExistentSessionId);
// Assert
}
Para uma sessão id válida, o segundo teste confirma se o método retorna:

Um ActionResult com um tipo List<IdeaDTO> .
O ActionResult<T>.Value é um tipo List<IdeaDTO> .
O primeiro item na lista é uma ideia válida que corresponde à ideia armazenada na sessão fictícia (obtida
chamando GetTestSession ).
[Fact]
public async Task ForSessionActionResult_ReturnsIdeasForSession()
{
// Arrange
// Act
var result = await controller.ForSessionActionResult(testSessionId);
// Assert
var returnValue = Assert.IsType<List<IdeaDTO>>(actionResult.Value);
}
O aplicativo de exemplo também inclui um método para criar um novo Idea para uma determinada sessão. O
controlador retorna:
BadRequest para um modelo inválido.
NotFound se a sessão não existir.
CreatedAtAction quando a sessão for atualizada com a nova ideia.
[HttpPost("createactionresult")]
public async Task<ActionResult<BrainstormSession>> CreateActionResult([FromBody]NewIdeaModel model)
{
{
}
{
}

{
Name = model.Name
};
return CreatedAtAction(nameof(CreateActionResult), new { id = session.Id }, session);

}
Três testes CreateActionResult estão incluídos no ApiIdeasControllerTests .

O primeiro texto confirma que um BadRequest é retornado para um modelo inválido.
[Fact]
public async Task CreateActionResult_ReturnsBadRequest_GivenInvalidModel()
{
// Arrange & Act
// Act
var result = await controller.CreateActionResult(model: null);
// Assert
Assert.IsType<BadRequestObjectResult>(actionResult.Result);
}
O segundo teste verifica se um NotFound será retornado se a sessão não existir.
[Fact]
public async Task CreateActionResult_ReturnsNotFoundObjectResultForNonexistentSession()
{
// Arrange

{
Name = testName,
SessionId = nonExistentSessionId
};
// Act
// Assert
}
Para uma sessão id válida, o teste final confirmará se:

O método retorna um ActionResult com um tipo BrainstormSession .
O ActionResult<T>.Result é um CreatedAtActionResult. CreatedAtActionResult é semelhante à resposta 201
Criado com um cabeçalho Location .
O ActionResult<T>.Value é um tipo BrainstormSession .
A chamada fictícia para atualizar a sessão, UpdateAsync(testSession) , foi invocada. A chamada de método
Verifiable é verificada por meio da execução de mockRepo.Verify() nas declarações.
Dois objetos Idea são retornados para a sessão.
O último item (o Idea adicionado pela chamada fictícia a UpdateAsync ) corresponde ao newIdea adicionado
à sessão no teste.
[Fact]
public async Task CreateActionResult_ReturnsNewlyCreatedIdeaForSession()
{
// Arrange

{
Name = testName,
};
.Verifiable();
// Act
// Assert
var createdAtActionResult = Assert.IsType<CreatedAtActionResult>(actionResult.Result);
var returnValue = Assert.IsType<BrainstormSession>(createdAtActionResult.Value);
mockRepo.Verify();
Assert.Equal(2, returnValue.Ideas.Count());
Assert.Equal(testName, returnValue.Ideas.LastOrDefault().Name);
Assert.Equal(testDescription, returnValue.Ideas.LastOrDefault().Description);
}
Recursos adicionais
<xref:test/index>
Crie e execute testes de unidade com o Visual Studio.
Por Luke Latham e Steve Smith

Testes de integração Certifique-se de que os componentes do aplicativo funcionam corretamente em um nível
que inclui a infraestrutura de suporte do aplicativo, como o banco de dados, o sistema de arquivos e a rede.
ASP.NET Core dá suporte a testes de integração usando uma estrutura de teste de unidade com um host de
teste da web e um servidor de teste na memória.
Este tópico pressupõe uma compreensão básica dos testes de unidade. Se estiver familiarizado com os
conceitos de teste, consulte o testes de unidade no .NET Core e .NET Standard tópico e seu conteúdo
vinculado.
O aplicativo de exemplo é um aplicativo páginas Razor e pressupõe uma compreensão básica de páginas do
Razor. Se estiver familiarizado com as páginas Razor, consulte os tópicos a seguir:
NOTE
Para SPAs de teste, é recomendável uma ferramenta, como Selenium, que pode automatizar um navegador.
Introdução aos testes de integração

Componentes de um aplicativo em um nível mais amplo do que avaliar a testes de integração testes de
unidade. Testes de unidade são usados para testar os componentes de software isolado, tais como métodos de
classe individual. Testes de integração confirme que dois ou mais componentes de aplicativo funcionam em
conjunto para produzir um resultado esperado, possivelmente incluindo todos os componentes necessários
para processar totalmente uma solicitação.
Esses testes mais amplos são usados para testar a infraestrutura do aplicativo e o framework inteiro, muitas
vezes, incluindo os seguintes componentes:
Banco de Dados
Sistema de arquivos
Dispositivos de rede
Pipeline de solicitação-resposta
Componentes de uso gerado, conhecidos como testes de unidade fakes ou objetos fictícios, no lugar de
componentes de infraestrutura.
Em contraste com testes de unidade, testes de integração:
Use os componentes reais usados pelo aplicativo em produção.
Exigem mais código e processamento de dados.
Pode levar mais tempo.
Portanto, limite o uso de testes de integração para os cenários mais importantes de infraestrutura. Se um
comportamento pode ser testado usando um teste de unidade ou um teste de integração, escolha o teste de
unidade.
TIP
Não escreva testes de integração para cada permutação possíveis de acesso de dados e arquivos com sistemas de
arquivos e bancos de dados. Independentemente de quantos coloca em um aplicativo de interagir com bancos de dados
e sistemas de arquivos, um conjunto com foco de leitura, gravação, atualização e exclusão integração testes são
geralmente capazes de banco de dados de teste adequadamente e componentes do sistema de arquivos. Testes de
unidade de uso para testes de rotina da lógica do método que interagem com esses componentes. Em testes de
unidade, o uso da infra-estrutura de falsificações/simulações resultado na execução de teste mais rápido.
NOTE
Em discussões de testes de integração, o projeto testado com frequência é chamado de sistema em teste, ou "SUT" de
forma abreviada.
Testes de integração do ASP.NET Core

Testes de integração no ASP.NET Core requerem o seguinte:
Um projeto de teste é usado para conter e executar os testes. O projeto de teste tem uma referência ao
projeto ASP.NET Core testada, chamado de sistema em teste (SUT). "SUT" é usado ao longo deste tópico
para referir-se para o aplicativo testado.
O projeto de teste cria um host da web de teste do SUT e usa um cliente do servidor de teste para lidar
com solicitações e respostas para o SUT.
Um executor de teste é usado para executar os testes e o relatório de resultados de teste.
Testes de integração seguem uma sequência de eventos que incluem o usual organizar, Act, e Assert etapas de
teste:
1. Host de web do SUT está configurado.
2. Um cliente do servidor de teste é criado para enviar solicitações para o aplicativo.
3. O organizar etapa de teste é executada: O aplicativo de teste prepara uma solicitação.
4. O Act etapa de teste é executada: O cliente envia a solicitação e recebe a resposta.
5. O Assert etapa de teste é executada: O real resposta é validada como um passar ou falhar com base em um
esperado resposta.
6. O processo continua até que todos os testes são executados.
7. Os resultados do teste são relatados.
Normalmente, o host de teste da web está configurado diferentemente do host do aplicativo web normal para
o teste é executado. Por exemplo, configurações de aplicativo diferente ou outro banco de dados podem ser
usadas para os testes.
Componentes de infraestrutura, como o host do teste da web e o servidor de teste na memória ( TestServer),
são fornecidas ou gerenciados pelo Microsoft.AspNetCore.Mvc.Testing pacote. O uso desse pacote simplifica a
criação de teste e execução.
O Microsoft.AspNetCore.Mvc.Testing pacote lida com as seguintes tarefas:
Copia o arquivo de dependências (*.deps) do SUT para o projeto de teste bin pasta.
Define a raiz do conteúdo raiz do projeto do SUT para que os arquivos estáticos e páginas/exibições são
encontradas quando os testes são executados.
Fornece o WebApplicationFactory classe para simplificar a inicialização com o SUT TestServer .
O testes de unidade documentação descreve como configurar um projeto e teste de executor de teste, junto
com instruções detalhadas sobre como executar testes e recomendações sobre como a testes de nome e
classes de teste.
NOTE
Ao criar um projeto de teste para um aplicativo, separe os testes de unidade dos testes de integração em projetos
diferentes. Isso ajuda a garantir que o teste componentes da infraestrutura não acidentalmente incluídos nos testes de
unidade. Também permite a separação dos testes de unidade e integração de controle sobre qual conjunto de testes são
executados.
Não há praticamente nenhuma diferença entre a configuração para testes de aplicativos de páginas do Razor e
aplicativos MVC. A única diferença está em como os testes são nomeados. Em um aplicativo de páginas do
Razor, os testes de pontos de extremidade de página geralmente são nomeadas depois a classe de modelo de
página (por exemplo, IndexPageTests para testar a integração do componente para a página de índice). Em um
aplicativo MVC, testes são geralmente organizadas por classes de controlador e os controladores de testam
por eles em homenagem (por exemplo, HomeControllerTests para testar a integração do componente para o
controlador Home).
Pré-requisitos de aplicativo de teste

O projeto de teste deve:
Referenciar os seguintes pacotes:
Microsoft.AspNetCore.Mvc.Testing
Especifique o SDK para Web no arquivo de projeto ( <Project Sdk="Microsoft.NET.Sdk.Web"> ). O SDK para
Web é necessário ao fazer referência a metapacote Microsoft.
Esses pré-requisitos podem ser vistos na aplicativo de exemplo. Inspecione o
tests/RazorPagesProject.Tests/RazorPagesProject.Tests.csproj arquivo. O aplicativo de exemplo usa o xUnit
estrutura de teste e o AngleSharp biblioteca do analisador, portanto, o aplicativo de exemplo também
referencia:
xUnit
xUnit
AngleSharp
Testes básicos com o padrão WebApplicationFactory

WebApplicationFactory<TEntryPoint> é usado para criar um TestServer para os testes de integração.
TEntryPoint é a classe de ponto de entrada do SUT, geralmente o Startup classe.
Teste as classes implementam uma acessório de classe interface ( IClassFixture ) para indicar a classe contém
testes e fornece instâncias de objeto compartilhado entre os testes na classe.
Teste básico de pontos de extremidade do aplicativo
O seguinte teste de classe, BasicTests , usa o WebApplicationFactory para inicializar o SUT e fornecer uma
HttpClient para um método de teste, Get_EndpointsReturnSuccessAndCorrectContentType . O método verifica se o
código de status de resposta for bem-sucedida (códigos de status no intervalo 200-299) e o Content-Type
cabeçalho é text/html; charset=utf-8 para várias páginas de aplicativo.
CreateClient cria uma instância de HttpClient que segue redirecionamentos e manipula cookies
automaticamente.
public class BasicTests

: IClassFixture<WebApplicationFactory<RazorPagesProject.Startup>>
{
private readonly WebApplicationFactory<RazorPagesProject.Startup> _factory;
public BasicTests(WebApplicationFactory<RazorPagesProject.Startup> factory)

{
_factory = factory;
}
[Theory]
[InlineData("/")]
[InlineData("/Index")]
[InlineData("/About")]
[InlineData("/Privacy")]
[InlineData("/Contact")]
public async Task Get_EndpointsReturnSuccessAndCorrectContentType(string url)
{
// Arrange
var client = _factory.CreateClient();
// Act
var response = await client.GetAsync(url);
// Assert
response.EnsureSuccessStatusCode(); // Status Code 200-299
Assert.Equal("text/html; charset=utf-8",
response.Content.Headers.ContentType.ToString());
}
Testar um ponto de extremidade seguro

Outro teste no BasicTests classe verifica que um ponto de extremidade seguro redireciona um usuário não
autenticado à página de logon do aplicativo.
No SUT, o /SecurePage página usa um AuthorizePage convenção para aplicar um AuthorizeFilter para a
página. Para obter mais informações, consulte convenções de autorização de páginas do Razor.
services.AddMvc()
{
options.Conventions.AuthorizePage("/SecurePage");
});
No Get_SecurePageRequiresAnAuthenticatedUser testar, uma WebApplicationFactoryClientOptions está definido

para não permitir redirecionamentos definindo AllowAutoRedirect para false :
[Fact]
public async Task Get_SecurePageRequiresAnAuthenticatedUser()
{
// Arrange
var client = _factory.CreateClient(
new WebApplicationFactoryClientOptions
{
AllowAutoRedirect = false
});
// Act
var response = await client.GetAsync("/SecurePage");
// Assert
Assert.Equal(HttpStatusCode.Redirect, response.StatusCode);
Assert.StartsWith("http://localhost/Identity/Account/Login",
response.Headers.Location.OriginalString);
}
Não permitindo que o cliente para seguir o redirecionamento, podem ser feitas as seguintes verificações:
O código de status retornado pelo SUT pode ser verificado em relação a esperada HttpStatusCode.Redirect
resultado, não o código de status final após o redirecionamento para a página de logon, o que seria
Httpstatuscode.
O Location valor de cabeçalho nos cabeçalhos de resposta é verificado para confirmar que ela começa
com http://localhost/Identity/Account/Login , não a logon página resposta final, onde o Location
cabeçalho não está presente.
Para obter mais informações sobre WebApplicationFactoryClientOptions , consulte o opções de cliente seção.
Personalizar WebApplicationFactory
Configuração do host da Web pode ser criada independentemente das classes de teste herdando de
WebApplicationFactory para criar um ou mais fábricas personalizadas:
1. Herdar WebApplicationFactory e substituir ConfigureWebHost. O IWebHostBuilder permite a

configuração da coleção com o serviço ConfigureServices:
public class CustomWebApplicationFactory<TStartup>
: WebApplicationFactory<RazorPagesProject.Startup>
{
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
builder.ConfigureServices(services =>
{
// Create a new service provider.
var serviceProvider = new ServiceCollection()
.AddEntityFrameworkInMemoryDatabase()
.BuildServiceProvider();
// Add a database context (ApplicationDbContext) using an in-memory

// database for testing.
{
options.UseInMemoryDatabase("InMemoryDbForTesting");
options.UseInternalServiceProvider(serviceProvider);
});
// Build the service provider.

var sp = services.BuildServiceProvider();
// Create a scope to obtain a reference to the database

// context (ApplicationDbContext).
using (var scope = sp.CreateScope())
{
var scopedServices = scope.ServiceProvider;
var db = scopedServices.GetRequiredService<ApplicationDbContext>();
var logger = scopedServices
.GetRequiredService<ILogger<CustomWebApplicationFactory<TStartup>>>();
// Ensure the database is created.

db.Database.EnsureCreated();
try
{
// Seed the database with test data.
Utilities.InitializeDbForTests(db);
}
{
logger.LogError(ex, $"An error occurred seeding the " +
"database with test messages. Error: {ex.Message}");
}
}
});
}
}
A propagação do banco de dados de aplicativo de exemplo é executada pelo InitializeDbForTests

método. O método é descrito na exemplo para testes de integração: testar a organização de aplicativo
seção.
2. Usar o custom CustomWebApplicationFactory em classes de teste. O exemplo a seguir usa o alocador no
IndexPageTests classe:
public class IndexPageTests : IClassFixture<CustomWebApplicationFactory<RazorPagesProject.Startup>>
{
private readonly HttpClient _client;
private readonly CustomWebApplicationFactory<RazorPagesProject.Startup> _factory;
public IndexPageTests(
CustomWebApplicationFactory<RazorPagesProject.Startup> factory)
{
_factory = factory;
_client = factory.CreateClient(new WebApplicationFactoryClientOptions
{
});
}
Cliente do aplicativo de exemplo está configurado para impedir o HttpClient de seguir

redirecionamentos. Conforme explicado a testar um ponto de extremidade seguro seção, isso permite
que os testes para verificar o resultado da primeira de resposta do aplicativo. A primeira resposta é um
redirecionamento em muitos desses testes com um Location cabeçalho.
3. Um teste típico usa a HttpClient e métodos auxiliares para processar a solicitação e resposta:
[Fact]
public async Task Post_DeleteAllMessagesHandler_ReturnsRedirectToRoot()
{
// Arrange
var defaultPage = await _client.GetAsync("/");
var content = await HtmlHelpers.GetDocumentAsync(defaultPage);
//Act
var response = await _client.SendAsync(
(IHtmlFormElement)content.QuerySelector("form[id='messages']"),
(IHtmlButtonElement)content.QuerySelector("button[id='deleteAllBtn']"));
// Assert
Assert.Equal(HttpStatusCode.OK, defaultPage.StatusCode);
Assert.Equal("/", response.Headers.Location.OriginalString);
}
Todas as solicitações POST para o SUT devem satisfazer a verificação de antifalsificação é feita
automaticamente pelo aplicativo do sistema de proteção de dados antifalsificação. Para organizar para
solicitação POST de um teste, o aplicativo de teste deve:
1. Faça uma solicitação para a página.
2. Analise o cookie antifalsificação e o token de validação de solicitação da resposta.
3. Fazer a solicitação POST com a validação antifalsificação do cookie e solicitação de token em vigor.
O SendAsync métodos de extensão auxiliar (Helpers/HttpClientExtensions.cs) e o GetDocumentAsync método
auxiliar (Helpers/HtmlHelpers.cs) no doaplicativodeexemplo usar o AngleSharp analisador para lidar com a
verificação de antiforgery com os seguintes métodos:
GetDocumentAsync – Recebe o HttpResponseMessage e retorna um IHtmlDocument . GetDocumentAsync usa
uma fábrica que prepara uma resposta virtual com base no original HttpResponseMessage . Para obter mais
informações, consulte o AngleSharp documentação.
SendAsync métodos de extensão para o HttpClient compor uma HttpRequestMessage e chame
SendAsync(HttpRequestMessage) para enviar solicitações para o SUT. Sobrecargas SendAsync aceite o
formulário HTML ( IHtmlFormElement ) e o seguinte:
Enviar o botão do formulário ( IHtmlElement )
Coleção de valores de formulário ( IEnumerable<KeyValuePair<string, string>> )
Botão enviar ( IHtmlElement ) e valores de formulário ( IEnumerable<KeyValuePair<string, string>> )
NOTE
AngleSharp é um terceiro biblioteca usada para fins de demonstração neste tópico e o aplicativo de exemplo de análise.
AngleSharp não é suportado ou necessários para os testes de integração de aplicativos ASP.NET Core. Outros
analisadores podem usados, como o Pack de agilidade de Html (HAP). Outra abordagem é escrever código para lidar
com o token de verificação de solicitação e o cookie antifalsificação o sistema antifalsificação diretamente.
Personalizar o cliente com WithWebHostBuilder

Quando a configuração adicional é necessária dentro de um método de teste WithWebHostBuilder cria uma
nova WebApplicationFactory com um IWebHostBuilder que é ainda mais personalizado pela configuração.
O Post_DeleteMessageHandler_ReturnsRedirectToRoot método de teste a aplicativo de exemplo demonstra o uso
de WithWebHostBuilder . Esse teste executa uma exclusão de registro no banco de dados ao disparar um envio
de formulário no SUT.
Porque outro teste na IndexPageTests classe executa uma operação que exclui todos os registros no banco de
dados e podem ser executadas antes do Post_DeleteMessageHandler_ReturnsRedirectToRoot método, o banco de
dados é propagado nesse método de teste para garantir que um registro está presente para o SUT excluir.
Selecionando o deleteBtn1 botão do messages formulário no SUT é simulado na solicitação para o SUT:
[Fact]
public async Task Post_DeleteMessageHandler_ReturnsRedirectToRoot()
{
// Arrange
var client = _factory.WithWebHostBuilder(builder =>
{
{
var serviceProvider = services.BuildServiceProvider();
using (var scope = serviceProvider.CreateScope())

{
var scopedServices = scope.ServiceProvider;
var db = scopedServices
.GetRequiredService<ApplicationDbContext>();
var logger = scopedServices
.GetRequiredService<ILogger<IndexPageTests>>();
try
{
Utilities.InitializeDbForTests(db);
}
{
logger.LogError(ex, "An error occurred seeding " +
"the database with test messages. Error: " +
ex.Message);
}
}
});
})
.CreateClient(new WebApplicationFactoryClientOptions
{
});
var defaultPage = await client.GetAsync("/");
//Act
var response = await client.SendAsync(
(IHtmlFormElement)content.QuerySelector("form[id='messages']"),
(IHtmlButtonElement)content.QuerySelector("button[id='deleteBtn1']"));
// Assert
Assert.Equal(HttpStatusCode.OK, defaultPage.StatusCode);
Assert.Equal("/", response.Headers.Location.OriginalString);
}
Opções do cliente
A tabela a seguir mostra o padrão WebApplicationFactoryClientOptions disponíveis ao criar HttpClient
instâncias.
OPÇÃO DESCRIÇÃO PADRÃO
AllowAutoRedirect Obtém ou define se HttpClient true

instâncias precisar seguir
automaticamente as respostas de
redirecionamento.
OPÇÃO DESCRIÇÃO PADRÃO
BaseAddress Obtém ou define o endereço básico http://localhost

do HttpClient instâncias.
HandleCookies Obtém ou define se HttpClient true

instâncias devem lidar com cookies.
MaxAutomaticRedirections Obtém ou define o número máximo 7

de respostas de redirecionamento que
HttpClient instâncias devem seguir.
Criar o WebApplicationFactoryClientOptions de classe e passá-lo para o CreateClient método (padrão de

valores são mostrados no exemplo de código):
// Default client option values are shown

var clientOptions = new WebApplicationFactoryClientOptions();
clientOptions.AllowAutoRedirect = true;
clientOptions.BaseAddress = new Uri("http://localhost");
clientOptions.HandleCookies = true;
clientOptions.MaxAutomaticRedirections = 7;
_client = _factory.CreateClient(clientOptions);
Inserir serviços fictícios

Os serviços podem ser substituídos em um teste com uma chamada para ConfigureTestServices no construtor
do host. Para inserir os serviços de simulação, o SUT deve ter uma Startup classe com um
Startup.ConfigureServices método.
O exemplo SUT inclui um serviço com escopo definido que retorna uma citação. A cotação é inserida em um
campo oculto na página de índice quando a página de índice é solicitada.
Services/IQuoteService.cs:
public interface IQuoteService

{
Task<string> GenerateQuote();
}
Services/QuoteService.cs:
// Quote ©1975 BBC: The Doctor (Tom Baker); Dr. Who: Planet of Evil
// https://www.bbc.co.uk/programmes/p00pyrx6
public class QuoteService : IQuoteService
{
public Task<string> GenerateQuote()
{
return Task.FromResult<string>(
"Come on, Sarah. We've an appointment in London, " +
"and we're already 30,000 years late.");
}
}
Startup.cs:
services.AddScoped<IQuoteService, QuoteService>();
Pages/Index.cshtml.cs:

{
private readonly ApplicationDbContext _db;
private readonly IQuoteService _quoteService;
public IndexModel(ApplicationDbContext db, IQuoteService quoteService)

{
_db = db;
_quoteService = quoteService;
}
[BindProperty]
public Message Message { get; set; }
public IList<Message> Messages { get; private set; }
[TempData]
public string MessageAnalysisResult { get; set; }
public string Quote { get; private set; }

{
Messages = await _db.GetMessagesAsync();
Quote = await _quoteService.GenerateQuote();

}
Pages/Index.cs:
<input id="quote" type="hidden" value="@Model.Quote">
A marcação a seguir é gerada quando o aplicativo SUT for executado:
<input id="quote" type="hidden" value="Come on, Sarah. We've an appointment in

London, and we're already 30,000 years late.">
Para testar a injeção de serviço e as aspas em um teste de integração, um serviço de simulação é injetado no
SUT pelo teste. O serviço fictício substitui o aplicativo QuoteService com um serviço fornecido pelo aplicativo
de teste, chamado TestQuoteService :
IntegrationTests.IndexPageTests.cs:
// Quote ©1975 BBC: The Doctor (Tom Baker); Pyramids of Mars

// https://www.bbc.co.uk/programmes/p00pys55
public class TestQuoteService : IQuoteService
{
public Task<string> GenerateQuote()
{
return Task.FromResult<string>(
"Something's interfering with time, Mr. Scarman, " +
"and time is my business.");
}
}
ConfigureTestServices é chamado, e o serviço com escopo está registrado:
[Fact]
public async Task Get_QuoteService_ProvidesQuoteInPage()
{
// Arrange
var client = _factory.WithWebHostBuilder(builder =>
{
builder.ConfigureTestServices(services =>
{
services.AddScoped<IQuoteService, TestQuoteService>();
});
})
.CreateClient();
//Act
var defaultPage = await client.GetAsync("/");
var quoteElement = content.QuerySelector("#quote");
// Assert
Assert.Equal("Something's interfering with time, Mr. Scarman, " +
"and time is my business.", quoteElement.Attributes["value"].Value);
}
A marcação produzida durante a execução do teste reflete o texto de cotação fornecido pelo TestQuoteService ,
portanto, os passos de asserção:
<input id="quote" type="hidden" value="Something's interfering with time,

Mr. Scarman, and time is my business.">
Como a infraestrutura de teste infere o caminho de raiz do conteúdo

do aplicativo
O WebApplicationFactory construtor infere o caminho de raiz do conteúdo do aplicativo procurando por um
WebApplicationFactoryContentRootAttribute no assembly que contém os testes de integração com uma chave
igual ao TEntryPoint assembly System.Reflection.Assembly.FullName . No caso de um atributo com a chave
correta não for encontrado, WebApplicationFactory reverterá para procurar por um arquivo de solução ( *. sln)
e anexa o TEntryPoint nome do assembly para o diretório da solução. O diretório raiz do aplicativo (o
caminho raiz do conteúdo) é usado para descobrir os modos de exibição e arquivos de conteúdo.
Na maioria dos casos, ele não é necessário definir explicitamente a raiz do conteúdo de aplicativo, conforme a
lógica de pesquisa geralmente encontra a raiz do conteúdo correta no tempo de execução. Em cenários
especiais em que a raiz do conteúdo não for encontrada usando o algoritmo de pesquisa interna, o aplicativo
de conteúdo raiz pode ser especificada explicitamente ou por meio de lógica personalizada. Para definir a raiz
do conteúdo de aplicativo nesses cenários, chame o UseSolutionRelativeContentRoot método de extensão do
testhost pacote. Forneça um caminho relativo da solução e o padrão de nome ou glob do arquivo de solução
opcional (padrão = *.sln ).
Chame o UseSolutionRelativeContentRoot usando o método extensão um das seguintes abordagens:
Ao configurar classes de teste com WebApplicationFactory , forneça uma configuração personalizada
com o IWebHostBuilder:
public IndexPageTests(
WebApplicationFactory<RazorPagesProject.Startup> factory)
{
var _factory = factory.WithWebHostBuilder(builder =>
{
builder.UseSolutionRelativeContentRoot("<SOLUTION-RELATIVE-PATH>");
...
});
}
Ao configurar classes de teste com um personalizado WebApplicationFactory , herdam

WebApplicationFactory e substituir ConfigureWebHost:
public class CustomWebApplicationFactory<TStartup>

: WebApplicationFactory<RazorPagesProject.Startup>
{
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
{
builder.UseSolutionRelativeContentRoot("<SOLUTION-RELATIVE-PATH>");
...
});
}
}
Desabilitar a cópia de sombra

A cópia de sombra faz com que os testes a serem executados em uma pasta diferente que a pasta de saída.
Para testes funcione corretamente, a cópia de sombra deve ser desabilitada. O aplicativo de exemplo usa o
xUnit e desabilita a cópia de sombra para xUnit, incluindo um xunit.runner.json arquivo com a configuração
correta. Para obter mais informações, consulte Configurando o xUnit.net com JSON.
Adicione a xunit.runner.json arquivo raiz do projeto de teste com o seguinte conteúdo:
{
"shadowCopy": false
}
Exemplo para testes de integração

O aplicativo de exemplo é composto de dois aplicativos:
APLICATIVO PASTA DO PROJETO DESCRIÇÃO
Aplicativo de mensagens (SUT) src/RazorPagesProject Permite que um usuário adicione,

exclua uma, excluir todas as e analisar
as mensagens.
Aplicativo de teste tests/RazorPagesProject.Tests Usado para teste de integração o SUT.
Os testes podem ser executados usando os recursos de teste interno de um IDE, como Visual Studio. Se
usando Visual Studio Code ou a linha de comando, execute o seguinte comando em um prompt de comando
na tests/RazorPagesProject.Tests pasta:
dotnet test
Organização de aplicativo (SUT ) da mensagem

O SUT é um sistema de mensagem de páginas do Razor com as seguintes características:
A página de índice do aplicativo (Pages e Pages/Index.cshtml.cs) fornece uma interface do usuário e a
página de métodos de modelo para controlar a adição, exclusão e análise de mensagens (palavras médias
por mensagem) .
Uma mensagem é descrita pela Message classe (Data/Message.cs) com duas propriedades: Id (chave) e
Text (mensagem ). O Text propriedade é necessária e é limitada a 200 caracteres.
As mensagens são armazenadas usando banco de dados do Entity Framework na memória†.
O aplicativo contém uma camada de acesso de dados (DAL ) na sua classe de contexto do banco de dados,
AppDbContext ( Data/AppDbContext.cs).
Se o banco de dados está vazio na inicialização do aplicativo, o repositório de mensagens é inicializado com
três mensagens.
O aplicativo inclui um /SecurePage que só pode ser acessado por um usuário autenticado.
†O tópico EF testar com InMemory, explica como usar um banco de dados na memória para testes com
MSTest. Este tópico usa o xUnit estrutura de teste. Conceitos de teste e teste implementações em estruturas de
teste diferentes são semelhantes, mas não idênticos.
Embora o aplicativo não usa o padrão de repositório e não é um exemplo efetivação do padrão de unidade de
trabalho (UoW ), páginas do Razor dá suporte a esses padrões de desenvolvimento. Para obter mais
informações, consulte Projetando a camada de persistência de infraestrutura e lógica do controlador de teste
(o exemplo implementa o padrão de repositório).
Organização de aplicativo de teste
O aplicativo de teste é um aplicativo de console dentro de tests/RazorPagesProject.Tests pasta.
PASTA DO APLICATIVO DE TESTE DESCRIÇÃO
BasicTests BasicTests.cs contém métodos de teste para o roteamento,

acesso a uma página segura por um usuário não
autenticado e como obter um perfil de usuário do GitHub e
verificação de logon do usuário do perfil.
IntegrationTests IndexPageTests.cs contém os testes de integração para a

página de índice usar custom WebApplicationFactory
classe.
Os auxiliares/Utilities Utilities.CS contém o InitializeDbForTests

método usado para propagar o banco de dados com
dados de teste.
HtmlHelpers.cs fornece um método para retornar
um AngleSharp IHtmlDocument para uso pelos
métodos de teste.
HttpClientExtensions.cs fornecem sobrecargas para
SendAsync para enviar solicitações para o SUT.
É a estrutura de teste xUnit. Testes de integração são realizados usando o testhost, que inclui o TestServer.
Porque o Microsoft.AspNetCore.Mvc.Testing pacote é usado para configurar o servidor de host e o teste de
teste, o TestHost e TestServer pacotes não exigem referências de pacote direto no arquivo de projeto de
teste do aplicativo ou configuração de desenvolvedor do aplicativo de teste.
A propagação do banco de dados para teste
Testes de integração geralmente exigem um pequeno conjunto de dados no banco de dados antes da execução
de teste. Por exemplo, uma exclusão chamadas de teste para uma exclusão de registros de banco de dados,
portanto, o banco de dados deve ter pelo menos um registro para a solicitação de exclusão seja bem-sucedida.
O aplicativo de exemplo propaga o banco de dados com três mensagens na Utilities.cs que testes podem usar
quando elas são executadas:
public static void InitializeDbForTests(ApplicationDbContext db)

{
db.Messages.AddRange(GetSeedingMessages());
db.SaveChanges();
}
public static List<Message> GetSeedingMessages()

{
return new List<Message>()
{
new Message(){ Text = "TEST RECORD: You're standing on my scarf." },
new Message(){ Text = "TEST RECORD: Would you like a jelly baby?" },
new Message(){ Text = "TEST RECORD: To the rational mind, " +
"nothing is inexplicable; only unexplained." }
};
}
Recursos adicionais
Testes de unidade
Middleware
Solucionar problemas de projetos do ASP.NET Core
Por Rick Anderson

Os links a seguir fornecem diretrizes de solução de problemas:
NDC Conference (2018 Londres): Diagnosticar problemas em aplicativos do ASP.NET Core
Blog do ASP.NET: Solucionando problemas de desempenho do ASP.NET Core
Avisos do SDK do .NET core

Os 32 bits e versões de 64 bits do SDK do .NET Core estão instaladas
No novo projeto caixa de diálogo para o ASP.NET Core, você poderá ver o seguinte aviso:
As versões de bit 32 e 64 do SDK do .NET Core são instaladas. Somente modelos das versões de 64 bits
instalados em ' c:\Program Files\dotnet\sdk\' será exibida.
Esse aviso é exibido quando (x86) 32 bits e 64 bits (x64) versões dos SDK do .NET Core estão instalados. Ambas as
versões podem ser instaladas os motivos comuns incluem:
Você originalmente baixou o instalador do SDK do .NET Core usando um computador de 32 bits, mas, em
seguida, copiado entre e instalado em um computador de 64 bits.
O .NET Core SDK de 32 bits foi instalado por outro aplicativo.
A versão incorreta foi baixada e instalada.
Desinstale o .NET Core SDK 32 bits para evitar esse aviso. Desinstalar do painel de controle > programas e
recursos > desinstalar ou alterar um programa. Se você entender por que o aviso ocorre e suas implicações,
você pode ignorar o aviso.
SDK do .NET Core é instalado em vários locais
SDK do .NET Core é instalado em vários locais. Somente modelos dos SDKs instalados em ' c:\Program
Files\dotnet\sdk\' será exibida.
Você verá esta mensagem quando você tem pelo menos uma instalação do SDK do .NET Core em um diretório
fora do c:\arquivos de programas\dotnet\sdk\. Geralmente isso acontece quando o SDK do .NET Core foi
implantado em um computador usando copiar/colar em vez do instalador MSI.
Desinstale o .NET Core SDK 32 bits para evitar esse aviso. Desinstalar do painel de controle > programas e
recursos > desinstalar ou alterar um programa. Se você entender por que o aviso ocorre e suas implicações,
você pode ignorar o aviso.
Não há SDKs do .NET Core foram detectados
Nenhum SDK do .NET Core foi detectado, verifique se que eles estão incluídos na variável de ambiente 'PATH'.
Esse aviso é exibido quando a variável de ambiente PATH não apontar para qualquer SDKs do .NET Core no
computador. Para resolver esse problema:
Instale ou verifique se o que SDK do .NET Core é instalado.
Verifique o PATH variável de ambiente aponta para o local em que o SDK está instalado. O instalador
normalmente define o PATH .
Páginas Razor do ASP.NET Core com EF Core – série
de tutoriais
Esta série de tutoriais ensina a criar aplicativos Web de Razor Pages do ASP.NET Core que usam o EF (Entity
Framework) Core para o acesso a dados.
1. Introdução
4. Migrações
Páginas Razor com o Entity Framework Core no
ASP.NET Core – Tutorial 1 de 8
A versão deste tutorial para o ASP.NET Core 2.0 pode ser encontrada neste arquivo PDF.
A versão deste tutorial para o ASP.NET Core 2.1 contém diversas melhorias em relação à versão 2.0.
Por Tom Dykstra e Rick Anderson
O aplicativo Web de exemplo Contoso University demonstra como criar um aplicativo Razor Pages do
ASP.NET Core usando o EF (Entity Framework) Core.
O aplicativo de exemplo é um site de uma Contoso University fictícia. Ele inclui funcionalidades como
admissão de alunos, criação de cursos e atribuições de instrutor. Esta página é a primeira de uma série
de tutoriais que explica como criar o aplicativo de exemplo Contoso University.
Baixe ou exiba o aplicativo concluído. Instruções de download.
Pré-requisitos
Visual Studio
CLI do .NET Core
Familiaridade com as Páginas do Razor. Os novos programadores devem concluir a Introdução às
Páginas do Razor antes de começar esta série.
Caso tenha um problema que não consiga resolver, em geral, você poderá encontrar a solução
comparando o código com o projeto concluído. Uma boa maneira de obter ajuda é postando uma
pergunta no StackOverflow.com sobre o ASP.NET Core ou EF Core.
O aplicativo Web Contoso University

O aplicativo criado nesses tutoriais é um site básico de universidade.
Os usuários podem exibir e atualizar informações de alunos, cursos e instrutores. Veja a seguir algumas
das telas criadas no tutorial.
O estilo de interface do usuário deste site é próximo ao que é gerado pelos modelos internos. O foco do
tutorial é o EF Core com as Páginas do Razor, não a interface do usuário.
Criar o aplicativo Web Razor Pages da ContosoUniversity

Visual Studio
CLI do .NET Core
Crie um novo Aplicativo Web ASP.NET Core. Nomeie o projeto ContosoUniversity. É importante
nomear o projeto ContosoUniversity para que os namespaces sejam correspondentes quando o
código for copiado/colado.
Para ver imagens das etapas anteriores, confira Criar um aplicativo Web do Razor. Execute o aplicativo.
Configurar o estilo do site

Algumas alterações configuram o menu do site, o layout e a home page. Atualize
Pages/Shared/_Layout.cshtml com as seguintes alterações:
Altere cada ocorrência de "ContosoUniversity" para "Contoso University". Há três ocorrências.
Adicione entradas de menu para Alunos, Cursos, Instrutores e Departamentos e exclua a
entrada de menu Contato.
As alterações são realçadas. (Toda a marcação não é exibida.)
<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] : Contoso University</title>
</environment>
href="https://ajax.aspnetcdn.com/ajax/bootstrap/3.3.7/css/bootstrap.min.css"
asp-fallback-test-class="sr-only" asp-fallback-test-property="position" asp-fallback-
test-value="absolute" />
</environment>
</head>
<body>
target=".navbar-collapse">
</button>
<a asp-page="/Index" class="navbar-brand">Contoso University</a>
</div>
<li><a asp-page="/Students/Index">Students</a></li>
<li><a asp-page="/Courses/Index">Courses</a></li>
<li><a asp-page="/Instructors/Index">Instructors</a></li>
<li><a asp-page="/Departments/Index">Departments</a></li>
</ul>
</div>
</div>
</nav>

@RenderBody()
<hr />
<footer>
<p>© 2018 : Contoso University</p>
</footer>
</div>
@*Remaining markup not shown for brevity.*@
Em Pages/Index.cshtml, substitua o conteúdo do arquivo pelo seguinte código para substituir o texto
sobre o ASP.NET e MVC pelo texto sobre este aplicativo:
@page
@model IndexModel
@{
ViewData["Title"] = "Home page";
}
<div class="jumbotron">
<h1>Contoso University</h1>
</div>
<div class="row">
<h2>Welcome to Contoso University</h2>
<p>
Contoso University is a sample application that
demonstrates how to use Entity Framework Core in an
ASP.NET Core Razor Pages web app.
</p>
</div>
<h2>Build it from scratch</h2>
<p>You can build the application by following the steps in a series of tutorials.</p>
<p>
<a class="btn btn-default"
href="https://docs.microsoft.com/aspnet/core/data/ef-rp/intro">
See the tutorial »
</a>
</p>
</div>
<h2>Download it</h2>
<p>You can download the completed project from GitHub.</p>
<p>
<a class="btn btn-default"
href="https://github.com/aspnet/Docs/tree/master/aspnetcore/data/ef-
rp/intro/samples/cu-final">
See project source code »
</a>
</p>
</div>
</div>
Criar o modelo de dados

Crie classes de entidade para o aplicativo Contoso University. Comece com as três seguintes entidades:
Há uma relação um-para-muitos entre as entidades Student e Enrollment . Há uma relação um-para-
muitos entre as entidades Course e Enrollment . Um aluno pode se registrar em qualquer quantidade
de cursos. Um curso pode ter qualquer quantidade de alunos registrados.
Nas seções a seguir, é criada uma classe para cada uma dessas entidades.
A entidade Student
Crie uma pasta Models. Na pasta Models, crie um arquivo de classe chamado Student.cs com o seguinte
código:
using System;
namespace ContosoUniversity.Models
{
public class Student
{
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; set; }
public ICollection<Enrollment> Enrollments { get; set; }

}
}
A propriedade ID se torna a coluna de chave primária da tabela de BD (banco de dados) que

corresponde a essa classe. Por padrão, o EF Core interpreta uma propriedade nomeada ID ou
classnameID como a chave primária. Em classnameID , classname é o nome da classe. A chave primária
alternativa reconhecida automaticamente é StudentID no exemplo anterior.
A propriedade Enrollments é uma propriedade de navegação. As propriedades de navegação
vinculam-se a outras entidades que estão relacionadas a essa entidade. Nesse caso, a propriedade
Enrollments de uma Student entity armazena todas as entidades Enrollment relacionadas a essa
Student . Por exemplo, se uma linha Aluno no BD tiver duas linhas Registro relacionadas, a propriedade
de navegação Enrollments conterá duas entidades Enrollment . Uma linha Enrollment relacionada é
uma linha que contém o valor de chave primária do aluno na coluna StudentID . Por exemplo, suponha
que o aluno com ID=1 tenha duas linhas na tabela Enrollment . A tabela Enrollment tem duas linhas
com StudentID = 1. StudentID é uma chave estrangeira na tabela Enrollment que especifica o aluno
na tabela Student .
Se uma propriedade de navegação puder armazenar várias entidades, a propriedade de navegação
deverá ser um tipo de lista, como ICollection<T> . ICollection<T> pode ser especificado ou um tipo
como List<T> ou HashSet<T> . Quando ICollection<T> é usado, o EF Core cria uma coleção
HashSet<T> por padrão. As propriedades de navegação que armazenam várias entidades são
provenientes de relações muitos para muitos e um-para-muitos.
A entidade Enrollment
Na pasta Models, crie Enrollment.cs com o seguinte código:
{
public enum Grade
{
A, B, C, D, F
}
public class Enrollment

{
public int EnrollmentID { get; set; }
public int CourseID { get; set; }
public int StudentID { get; set; }
public Grade? Grade { get; set; }
public Course Course { get; set; }

public Student Student { get; set; }
}
}
A propriedade EnrollmentID é a chave primária. Essa entidade usa o padrão classnameID em vez de
ID como a entidade Student . Normalmente, os desenvolvedores escolhem um padrão e o usam em
todo o modelo de dados. Em um tutorial posterior, o uso de uma ID sem nome de classe é mostrado
para facilitar a implementação da herança no modelo de dados.
A propriedade Grade é um enum . O ponto de interrogação após a declaração de tipo Grade indica que
a propriedade Grade permite valor nulo. Uma nota nula é diferente de uma nota zero – nulo significa
que uma nota não é conhecida ou que ainda não foi atribuída.
A propriedade StudentID é uma chave estrangeira e a propriedade de navegação correspondente é
Student . Uma entidade Enrollment está associada a uma entidade Student e, portanto, a propriedade
contém uma única entidade Student . A entidade Student é distinta da propriedade de navegação
Student.Enrollments , que contém várias entidades Enrollment .
A propriedade CourseID é uma chave estrangeira e a propriedade de navegação correspondente é

Course . Uma entidade Enrollment está associada a uma entidade Course .
O EF Core interpreta uma propriedade como uma chave estrangeira se ela é nomeada
<navigation property name><primary key property name> . Por exemplo, StudentID para a propriedade de
navegação Student , pois a chave primária da entidade Student é ID . Propriedades de chave
estrangeira também podem ser nomeadas <primary key property name> . Por exemplo, CourseID , pois a
chave primária da entidade Course é CourseID .
A entidade Course
Na pasta Models, crie Course.cs com o seguinte código:
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
public int Credits { get; set; }

}
}
A propriedade Enrollments é uma propriedade de navegação. Uma entidade Course pode estar
relacionada a qualquer quantidade de entidades Enrollment .
O atributo DatabaseGenerated permite que o aplicativo especifique a chave primária em vez de fazer
com que ela seja gerada pelo BD.
Gere um modelo de aluno por scaffold

Nesta seção, é feito o scaffold do modelo de aluno. Ou seja, a ferramenta de scaffolding gera páginas
para operações de CRUD (Criar, Ler, Atualizar e Excluir) para o modelo de aluno.
Compile o projeto.
Crie a pasta Pages/Students.
Visual Studio
CLI do .NET Core
No Gerenciador de Soluções, clique com o botão direito do mouse na pasta Páginas/Alunos pasta
> Adicionar > Novo item com scaffold.
Na caixa de diálogo Adicionar Scaffold, selecione Razor Pages usando o Entity Framework
(CRUD ) > Adicionar.
Conclua a caixa de diálogo Adicionar Razor Pages usando o Entity Framework (CRUD ):
Na lista suspensa classe Modelo, selecione Aluno (ContosoUniversity.Models).
Na linha Classe de contexto de dados, selecione o sinal de (mais) + e altere o nome gerado para
ContosoUniversity.Models.SchoolContext.
Na lista suspensa Classe de contexto de dados, selecione
ContosoUniversity.Models.SchoolContext
Selecione Adicionar.
Confira Fazer scaffold do modelo de filme se tiver problemas na etapa anterior.
O processo de scaffold criou e alterou os seguintes arquivos:
Arquivos criados
Pages/Students Criar, Excluir, Detalhes, Editar, Índice.
Data/SchoolContext.cs
Atualizações de arquivo
Startup.cs: alterações a esse arquivo serão detalhadas na próxima seção.
appsettings.json: a cadeia de conexão usada para se conectar a um banco de dados local é
adicionada.
Examinar o contexto registrado com a injeção de dependência

O ASP.NET Core é construído com a injeção de dependência. Serviços (como o contexto de BD do EF
Core) são registrados com injeção de dependência durante a inicialização do aplicativo. Os
componentes que exigem esses serviços (como as Páginas do Razor) recebem esses serviços por meio
de parâmetros do construtor. O código de construtor que obtém uma instância de contexto do BD é
mostrado mais adiante no tutorial.
A ferramenta de scaffolding criou automaticamente um contexto de BD e o registrou no contêiner da
injeção de dependência.
Examine o método ConfigureServices em Startup.cs. A linha destacada foi adicionada pelo scaffolder:
{
{
// This lambda determines whether user consent for
//non -essential cookies is needed for a given request.
});
services.AddDbContext<SchoolContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("SchoolContext")));
}
DbContextOptions. Para o desenvolvimento local, o sistema de configuração do ASP.NET Core lê a
cadeia de conexão do arquivo appsettings.json.
Atualizar o principal
Em Program.cs, modifique o método Main para fazer o seguinte:
Obtenha uma instância de contexto de BD do contêiner de injeção de dependência.
Chame o EnsureCreated.
Descarte o contexto quando o método EnsureCreated for concluído.
O código a seguir mostra o arquivo Program.cs atualizado.

using ContosoUniversity.Models; // SchoolContext
using Microsoft.Extensions.DependencyInjection; // CreateScope
using System;
namespace ContosoUniversity
{
{
{

{
try
{
var context = services.GetRequiredService<SchoolContext>();
context.Database.EnsureCreated();
}
{
logger.LogError(ex, "An error occurred creating the DB.");
}
}
host.Run();
}

}
}
EnsureCreated garante que o banco de dados do contexto exista. Se ele existir, nenhuma ação será
realizada. Se ele não existir, o banco de dados e todos os seus esquemas serão criados. EnsureCreated
não usa migrações para criar o banco de dados. Um banco de dados criado com EnsureCreated não
pode ser atualizado posteriormente usando migrações.
EnsureCreated é chamado na inicialização do aplicativo, que permite que o seguinte fluxo de trabalho:
Exclua o BD.
Altere o esquema de BD (por exemplo, adicione um campo EmailAddress ).
EnsureCreated cria um BD com a coluna EmailAddress .
EnsureCreated é conveniente no início do desenvolvimento quando o esquema está evoluindo

rapidamente. Mais tarde, no tutorial do banco de dados, é excluído e as migrações são usadas.
Testar o aplicativo
Execute o aplicativo e aceite a política de cookies. Este aplicativo não armazena informações pessoais.
Você pode ler sobre a política de cookies em Suporte para a RGPD (Regulamento Geral sobre a
Proteção de Dados) da UE.
Selecione o link Alunos e Criar Novo.
Examine o contexto de BD SchoolContext

A classe principal que coordena a funcionalidade do EF Core de um modelo de dados é a classe de
contexto de BD. O contexto de dados deriva de Microsoft.EntityFrameworkCore.DbContext. O contexto
de dados especifica quais entidades são incluídas no modelo de dados. Neste projeto, a classe é
chamada SchoolContext .
Atualize SchoolContext.cs com o seguinte código:
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options)
: base(options)
{
}
public DbSet<Student> Student { get; set; }

public DbSet<Enrollment> Enrollment { get; set; }
public DbSet<Course> Course { get; set; }
}
}
O código destacado cria uma propriedade DbSet<TEntity> para cada conjunto de entidades. Na
terminologia do EF Core:
Um conjunto de entidades normalmente corresponde a uma tabela de BD.
Uma entidade corresponde a uma linha da tabela.
DbSet<Enrollment> e DbSet<Course> podem ser omitidos. O EF Core inclui-os de forma implícita porque
a entidade Student referencia a entidade Enrollment e a entidade Enrollment referencia a entidade
Course . Para este tutorial, mantenha DbSet<Enrollment> e DbSet<Course> no SchoolContext .

A cadeia de conexão especifica um LocalDB do SQL Server. LocalDB é uma versão leve do Mecanismo
de Banco de Dados do SQL Server Express destinado ao desenvolvimento de aplicativos, e não ao uso
em produção. O LocalDB é iniciado sob demanda e executado no modo de usuário e, portanto, não há
nenhuma configuração complexa. Por padrão, o LocalDB cria arquivos .mdf de BD no diretório
C:/Users/<user> .
Adicionar um código para inicializar o BD com os dados de teste

O EF Core cria um BD vazio. Nesta seção, um método Initialize é escrito para populá-lo com os
dados de teste.
Na pasta Dados, crie um novo arquivo de classe chamado DbInitializer.cs e adicione o seguinte código:
using ContosoUniversity.Models;
using System;
using System.Linq;
{
public static class DbInitializer
{
public static void Initialize(SchoolContext context)
{
// context.Database.EnsureCreated();
// Look for any students.

if (context.Student.Any())
{
}
var students = new Student[]

{
new
Student{FirstMidName="Carson",LastName="Alexander",EnrollmentDate=DateTime.Parse("2005-09-01")},
new
Student{FirstMidName="Meredith",LastName="Alonso",EnrollmentDate=DateTime.Parse("2002-09-01")},
new Student{FirstMidName="Arturo",LastName="Anand",EnrollmentDate=DateTime.Parse("2003-
09-01")},
new
Student{FirstMidName="Gytis",LastName="Barzdukas",EnrollmentDate=DateTime.Parse("2002-09-01")},
new Student{FirstMidName="Yan",LastName="Li",EnrollmentDate=DateTime.Parse("2002-09-
01")},
new Student{FirstMidName="Peggy",LastName="Justice",EnrollmentDate=DateTime.Parse("2001-
09-01")},
new Student{FirstMidName="Laura",LastName="Norman",EnrollmentDate=DateTime.Parse("2003-
09-01")},
new Student{FirstMidName="Nino",LastName="Olivetto",EnrollmentDate=DateTime.Parse("2005-
09-01")}
};
foreach (Student s in students)
{
context.Student.Add(s);
}
var courses = new Course[]

{
new Course{CourseID=1050,Title="Chemistry",Credits=3},
new Course{CourseID=4022,Title="Microeconomics",Credits=3},
new Course{CourseID=4041,Title="Macroeconomics",Credits=3},
new Course{CourseID=1045,Title="Calculus",Credits=4},
new Course{CourseID=3141,Title="Trigonometry",Credits=4},
new Course{CourseID=2021,Title="Composition",Credits=3},
new Course{CourseID=2042,Title="Literature",Credits=4}
};
foreach (Course c in courses)
{
context.Course.Add(c);
}
var enrollments = new Enrollment[]

{
new Enrollment{StudentID=1,CourseID=1050,Grade=Grade.A},
new Enrollment{StudentID=1,CourseID=4022,Grade=Grade.C},
new Enrollment{StudentID=1,CourseID=4041,Grade=Grade.B},
new Enrollment{StudentID=2,CourseID=3141,Grade=Grade.F},
new Enrollment{StudentID=3,CourseID=1050},
};
foreach (Enrollment e in enrollments)
{
{
context.Enrollment.Add(e);
}
}
}
}
O código verifica se há alunos no BD. Se não houver nenhum aluno no BD, o BD será inicializado com
os dados de teste. Ele carrega os dados de teste em matrizes em vez de em coleções List<T> para
otimizar o desempenho.
O método EnsureCreated cria o BD automaticamente para o contexto de BD. Se o BD existir,
EnsureCreated retornará sem modificar o BD.
Em Program.cs, modifique o método Main para chamar Initialize :

{
{

{
try
{
// using ContosoUniversity.Data;
DbInitializer.Initialize(context);
}
{
logger.LogError(ex, "An error occurred creating the DB.");
}
}
host.Run();
}

}
Exclua todos os registros de alunos e reinicie o aplicativo. Se o BD não for inicializado, defina um ponto
de interrupção em Initialize para diagnosticar o problema.
Exibir o BD
Abra o SSOX (Pesquisador de Objetos do SQL Server) no menu Exibir do Visual Studio. No SSOX,
clique em (localdb)\MSSQLLocalDB > Bancos de Dados > ContosoUniversity1.
Expanda o nó Tabelas.
Clique com o botão direito do mouse na tabela Aluno e clique em Exibir Dados para ver as colunas
criadas e as linhas inseridas na tabela.
Código assíncrono
A programação assíncrona é o modo padrão do ASP.NET Core e EF Core.
Um servidor Web tem um número limitado de threads disponíveis e, em situações de alta carga, todos
os threads disponíveis podem estar em uso. Quando isso acontece, o servidor não pode processar
novas solicitações até que os threads são liberados. Com um código síncrono, muitos threads podem
ser vinculados enquanto realmente não são fazendo nenhum trabalho porque estão aguardando a
conclusão da E/S. Com um código assíncrono, quando um processo está aguardando a conclusão da
E/S, seu thread é liberado para o servidor para ser usado para processar outras solicitações. Como
resultado, o código assíncrono permite que os recursos do servidor sejam usados com mais eficiência, e
o servidor fica capacitado a manipular mais tráfego sem atrasos.
O código assíncrono introduz uma pequena quantidade de sobrecarga em tempo de execução. Para
situações de baixo tráfego, o impacto no desempenho é insignificante, enquanto para situações de alto
tráfego, a melhoria de desempenho potencial é significativa.
No código a seguir, a palavra-chave async, o valor retornado Task<T> , a palavra-chave await eo
método ToListAsync fazem o código ser executado de forma assíncrona.

{
Student = await _context.Student.ToListAsync();
}
A palavra-chave async instrui o compilador a:

Gerar retornos de chamada para partes do corpo do método.
Criar automaticamente o objeto Task que é retornado. Para obter mais informações, consulte
Tipo de retorno de Tarefa.
O tipo de retorno implícito Task representa um trabalho em andamento.
A palavra-chave await faz com que o compilador divida o método em duas partes. A primeira
parte termina com a operação que é iniciada de forma assíncrona. A segunda parte é colocada
em um método de retorno de chamada que é chamado quando a operação é concluída.
ToListAsync é a versão assíncrona do método de extensão ToList .
Algumas coisas a serem consideradas ao escrever um código assíncrono que usa o EF Core:
Somente instruções que fazem com que consultas ou comandos sejam enviados ao BD são
executadas de forma assíncrona. Isso inclui ToListAsync , SingleOrDefaultAsync ,
FirstOrDefaultAsync e SaveChangesAsync . Isso não inclui instruções que apenas alteram um
IQueryable , como var students = context.Students.Where(s => s.LastName == "Davolio") .
Um contexto do EF Core não é thread-safe: não tente realizar várias operações em paralelo.
Para aproveitar os benefícios de desempenho do código assíncrono, verifique se os pacotes de
biblioteca (como para paginação) usam o código assíncrono se eles chamam métodos do EF Core
que enviam consultas ao BD.
Para obter mais informações sobre a programação assíncrona, consulte Visão geral de Async e
Programação assíncrona com async e await.
No próximo tutorial, as operações CRUD (criar, ler, atualizar e excluir) básicas são examinadas.
A VA N ÇA R
Páginas Razor com o EF Core no ASP.NET Core –
CRUD – 2 de 8
Por Tom Dykstra, Jon P Smith e Rick Anderson
O aplicativo Web Contoso University demonstra como criar aplicativos Web das Páginas do Razor usando o EF
Core e o Visual Studio. Para obter informações sobre a série de tutoriais, consulte o primeiro tutorial.
Neste tutorial, o código CRUD (criar, ler, atualizar e excluir) gerado por scaffolding é examinado e personalizado.
Para minimizar a complexidade e manter o foco destes tutoriais no EF Core, o código do EF Core é usado nos
modelos de página. Alguns desenvolvedores usam um padrão de repositório ou de camada de serviço para criar
uma camada de abstração entre a interface do usuário (Páginas do Razor) e a camada de acesso a dados.
Neste tutorial, as Razor Pages Criar, Editar, Excluir e Detalhes na pasta Student são examinadas.
O código gerado por scaffolding usa o seguinte padrão para as páginas Criar, Editar e Excluir:
Obtenha e exiba os dados solicitados com o método HTTP GET OnGetAsync .
Salve as alterações nos dados com o método HTTP POST OnPostAsync .
As páginas Índice e Detalhes obtêm e exibem os dados solicitados com o método HTTP GET OnGetAsync
SingleOrDefaultAsync vs. FirstOrDefaultAsync

O código gerado usa FirstOrDefaultAsync, que geralmente é uma preferência em relação a
SingleOrDefaultAsync.
FirstOrDefaultAsync é mais eficiente que SingleOrDefaultAsync na busca de uma entidade:
A menos que o código precise verificar se não há mais de uma entidade retornada da consulta.
SingleOrDefaultAsync busca mais dados e faz o trabalho desnecessário.
SingleOrDefaultAsync gera uma exceção se há mais de uma entidade que se ajusta à parte do filtro.
FirstOrDefaultAsync não gera uma exceção se há mais de uma entidade que se ajusta à parte do filtro.
FindAsync
Em grande parte do código gerado por scaffolding, FindAsync pode ser usado no lugar de FirstOrDefaultAsync .
FindAsync :
Encontra uma entidade com o PK (chave primária). Se uma entidade com o PK está sendo controlada pelo
contexto, ela é retornada sem uma solicitação para o BD.
É simples e conciso.
É otimizado para pesquisar uma única entidade.
Pode ter benefícios de desempenho em algumas situações, mas isso é raro em aplicativos Web.
Usa FirstAsync em vez de SingleAsync de forma implícita.
Mas se você deseja Include outras entidades, FindAsync não é mais apropriado. Isso significa que talvez seja
necessário abandonar FindAsync e passar para uma consulta à medida que o aplicativo avança.
Personalizar a página Detalhes

Navegue para a página Pages/Students . Os links Editar, Detalhes e Excluir são gerados pelo Auxiliar de
Marcação de Âncora no arquivo Pages/Students/Index.cshtml.
<td>
</td>
Execute o aplicativo e selecione o link Detalhes. A URL tem o formato

http://localhost:5000/Students/Details?id=2 . A ID do Aluno é passada com uma cadeia de caracteres de consulta
( ?id=2 ).
Atualize as Páginas Editar, Detalhes e Excluir do Razor para que elas usem o modelo de rota "{id:int}" . Altere a
diretiva de página de cada uma dessas páginas de @page para @page "{id:int}" .
Uma solicitação para a página com o modelo de rota "{id:int}" que não inclui um valor inteiro de rota retorna um
erro HTTP 404 (não encontrado). Por exemplo, http://localhost:5000/Students/Details retorna um erro 404. Para
tornar a ID opcional, acrescente ? à restrição de rota:
@page "{id:int?}"
Execute o aplicativo, clique em um link Detalhes e verifique se a URL está passando a ID como dados de rota (
http://localhost:5000/Students/Details/2 ).
Não altere @page globalmente para @page "{id:int}" , pois isso desfaz os links para as páginas Início e Criar.
Adicionar dados relacionados
O código gerado por scaffolding para a página Índice de Alunos não inclui a propriedade Enrollments . Nesta
seção, o conteúdo da coleção Enrollments é exibido na página Detalhes.
O método OnGetAsync de Pages/Students/Details.cshtml.cs usa o método FirstOrDefaultAsync para recuperar
uma única entidade Student . Adicione o seguinte código realçado:

{
if (id == null)
{
return NotFound();
}
Student = await _context.Student

.Include(s => s.Enrollments)
.ThenInclude(e => e.Course)
.AsNoTracking()
if (Student == null)
{
return NotFound();
}
return Page();
}
Os métodos Include e ThenInclude fazem com que o contexto carregue a propriedade de navegação
Student.Enrollments e, dentro de cada registro, a propriedade de navegação Enrollment.Course . Esses métodos
são examinados em detalhes no tutorial de dados relacionado à leitura.
O método AsNoTracking melhora o desempenho em cenários em que as entidades retornadas não são
atualizadas no contexto atual. AsNoTracking é abordado mais adiante neste tutorial.
Exibir registros relacionados na página Detalhes
Abra Pages/Students/Details.cshtml. Adicione o seguinte código realçado para exibir uma lista de registros:
@page "{id:int}"
@model ContosoUniversity.Pages.Students.DetailsModel
@{
}
<h2>Details</h2>
<div>
<h4>Student</h4>
<hr />
<dt>
@Html.DisplayNameFor(model => model.Student.LastName)
</dt>
<dd>
@Html.DisplayFor(model => model.Student.LastName)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Student.FirstMidName)
</dt>
<dd>
@Html.DisplayFor(model => model.Student.FirstMidName)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Student.EnrollmentDate)
</dt>
<dd>
@Html.DisplayFor(model => model.Student.EnrollmentDate)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Student.Enrollments)
</dt>
<dd>
<tr>
<th>Course Title</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.Student.Enrollments)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.Course.Title)
</td>
<td>
@Html.DisplayFor(modelItem => item.Grade)
</td>
</tr>
}
</table>
</dd>
</dl>
</div>
<div>
<a asp-page="./Edit" asp-route-id="@Model.Student.ID">Edit</a> |
</div>
Se o recuo do código estiver incorreto depois que o código for colado, pressione CTRL -K-D para corrigi-lo.
O código anterior percorre as entidades na propriedade de navegação Enrollments . Para cada registro, ele exibe o
nome do curso e a nota. O título do curso é recuperado da entidade Course, que é armazenada na propriedade de
navegação Course da entidade Enrollments.
Execute o aplicativo, selecione a guia Alunos e clique no link Detalhes de um aluno. A lista de cursos e notas do
aluno selecionado é exibida.
Atualizar a página Criar

Atualize o método OnPostAsync em Pages/Students/Create.cshtml.cs com o seguinte código:

{
{
return Page();
}
var emptyStudent = new Student();
if (await TryUpdateModelAsync<Student>(
emptyStudent,
"student", // Prefix for form value.
s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate))
{
_context.Student.Add(emptyStudent);
}
return null;
}
TryUpdateModelAsync
Examine o código TryUpdateModelAsync:
var emptyStudent = new Student();
emptyStudent,
"student", // Prefix for form value.
{
No código anterior, TryUpdateModelAsync<Student> tenta atualizar o objeto emptyStudent usando os valores de

formulário postados da propriedade PageContext no PageModel. TryUpdateModelAsync atualiza apenas as
propriedades listadas ( s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate ).
Na amostra anterior:
O segundo argumento ( "student", // Prefix ) é o prefixo usado para pesquisar valores. Não diferencia
maiúsculas de minúsculas.
Os valores de formulário postados são convertidos nos tipos no modelo Student usando o model binding.
Excesso de postagem
O uso de TryUpdateModel para atualizar campos com valores postados é uma melhor prática de segurança porque
ele impede o excesso de postagem. Por exemplo, suponha que a entidade Student inclua uma propriedade
Secret que esta página da Web não deve atualizar nem adicionar:
{
public string Secret { get; set; }
}
Mesmo que o aplicativo não tenha um campo Secret na Página criar/atualizar do Razor, um invasor pode definir
o valor Secret por excesso de postagem. Um invasor pode usar uma ferramenta como o Fiddler ou escrever um
JavaScript para postar um valor de formulário Secret . O código original não limita os campos que o associador
de modelos usa quando ele cria uma instância Student.
Seja qual for o valor que o invasor especificou para o campo de formulário Secret , ele será atualizado no BD. A
imagem a seguir mostra a ferramenta Fiddler adicionando o campo Secret (com o valor "OverPost") aos valores
de formulário postados.
O valor "OverPost" foi adicionado com êxito à propriedade Secret da linha inserida. O designer do aplicativo
nunca desejou que a propriedade Secret fosse definida com a página Criar.
Modelo de exibição
Um modelo de exibição normalmente contém um subconjunto das propriedades incluídas no modelo usado pelo
aplicativo. O modelo de aplicativo costuma ser chamado de modelo de domínio. O modelo de domínio
normalmente contém todas as propriedades necessárias para a entidade correspondente no BD. O modelo de
exibição contém apenas as propriedades necessárias para a camada de interface do usuário (por exemplo, a
página Criar). Além do modelo de exibição, alguns aplicativos usam um modelo de associação ou modelo de
entrada para passar dados entre a classe de modelo de página das Páginas do Razor e o navegador. Considere o
seguinte modelo de exibição Student :
using System;
{
public class StudentVM
{
}
}
Os modelos de exibição fornecem uma maneira alternativa para impedir o excesso de postagem. O modelo de
exibição contém apenas as propriedades a serem exibidas ou atualizadas.
O seguinte código usa o modelo de exibição StudentVM para criar um novo aluno:
[BindProperty]
public StudentVM StudentVM { get; set; }

{
{
return Page();
}
var entry = _context.Add(new Student());

entry.CurrentValues.SetValues(StudentVM);
}
O método SetValues define os valores desse objeto lendo os valores de outro objeto PropertyValues. SetValues
usa a correspondência de nomes de propriedade. O tipo de modelo de exibição não precisa estar relacionado ao
tipo de modelo, apenas precisa ter as propriedades correspondentes.
O uso de StudentVM exige a atualização de CreateVM.cshtml para usar StudentVM em vez de Student .
Nas Páginas do Razor, a classe derivada PageModel é o modelo de exibição.
Atualizar a página Editar

Atualize o modelo de página para a página de edição. As alterações principais são realçadas:
{
private readonly SchoolContext _context;
public EditModel(SchoolContext context)

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
Student = await _context.Student.FindAsync(id);
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
var studentToUpdate = await _context.Student.FindAsync(id);
studentToUpdate,
"student",
{
}
return Page();
}
}
As alterações de código são semelhantes à página Criar, com algumas exceções:

OnPostAsync tem um parâmetro id opcional.
O aluno atual é buscado do BD, em vez de criar um aluno vazio.
FirstOrDefaultAsync foi substituído por FindAsync. FindAsync é uma boa opção ao selecionar uma entidade
da chave primária. Consulte FindAsync para obter mais informações.
Testar as páginas Editar e Criar
Crie e edite algumas entidades de aluno.
Estados da entidade
O contexto de BD controla se as entidades em memória estão em sincronia com suas linhas correspondentes no
BD. As informações de sincronização de contexto do BD determinam o que acontece quando SaveChangesAsync
é chamado. Por exemplo, quando uma nova entidade é passada para o método AddAsync, o estado da entidade é
definido como Added. Quando SaveChangesAsync é chamado, o contexto de BD emite um comando SQL INSERT.
Uma entidade pode estar em um dos seguintes estados:
Added : a entidade ainda não existe no BD. O método SaveChanges emite uma instrução INSERT.
Unchanged : nenhuma alteração precisa ser salva com essa entidade. Uma entidade tem esse status quando
é lida do BD.
Modified : alguns ou todos os valores de propriedade da entidade foram modificados. O método
SaveChanges emite uma instrução UPDATE.
Deleted : a entidade foi marcada para exclusão. O método SaveChanges emite uma instrução DELETE.
Detached : a entidade não está sendo controlada pelo contexto de BD.
Em um aplicativo da área de trabalho, em geral, as alterações de estado são definidas automaticamente. Uma
entidade é lida, as alterações são feitas e o estado da entidade é alterado automaticamente para Modified . A
chamada a SaveChanges gera uma instrução SQL UPDATE que atualiza apenas as propriedades alteradas.
Em um aplicativo Web, o DbContext que lê uma entidade e exibe os dados é descartado depois que uma página é
renderizada. Quando o método OnPostAsync de uma página é chamado, é feita uma nova solicitação da Web e
com uma nova instância do DbContext . A nova leitura da entidade nesse novo contexto simula o processamento
da área de trabalho.
Atualizar a página Excluir

Nesta seção, o código é adicionado para implementar uma mensagem de erro personalizada quando há falha na
chamada a SaveChanges . Adicione uma cadeia de caracteres para que ela contenha as possíveis mensagens de
erro:

{
public DeleteModel(SchoolContext context)

{
_context = context;
}
[BindProperty]
public string ErrorMessage { get; set; }
Substitua o método OnGetAsync pelo seguinte código:

public async Task<IActionResult> OnGetAsync(int? id, bool? saveChangesError = false)
{
if (id == null)
{
return NotFound();
}
Student = await _context.Student

.AsNoTracking()
{
return NotFound();
}
if (saveChangesError.GetValueOrDefault())
{
ErrorMessage = "Delete failed. Try again";
}
return Page();
}
O código anterior contém o parâmetro opcional saveChangesError . saveChangesError indica se o método foi
chamado após uma falha ao excluir o objeto de aluno. A operação de exclusão pode falhar devido a problemas de
rede temporários. Erros de rede transitórios serão mais prováveis de ocorrerem na nuvem. saveChangesError é
falso quando a página Excluir OnGetAsync é chamada na interface do usuário. Quando OnGetAsync é chamado por
OnPostAsync (devido à falha da operação de exclusão), o parâmetro saveChangesError é verdadeiro.
O método OnPostAsync nas páginas Excluir

Substitua OnPostAsync pelo seguinte código:

{
if (id == null)
{
return NotFound();
}
var student = await _context.Student

.AsNoTracking()
if (student == null)
{
return NotFound();
}
try
{
_context.Student.Remove(student);
}
catch (DbUpdateException /* ex */)
{
//Log the error (uncomment ex variable name and write a log.)
return RedirectToAction("./Delete",
new { id, saveChangesError = true });
}
}
O código anterior recupera a entidade selecionada e, em seguida, chama o método Remove para definir o status
da entidade como Deleted . Quando SaveChanges é chamado, um comando SQL DELETE é gerado. Se Remove
falhar:
A exceção de BD é capturada.
O método OnGetAsync das páginas Excluir é chamado com saveChangesError=true .
Atualizar a Página Excluir do Razor
Adicione a mensagem de erro realçada a seguir à Página Excluir do Razor.
@page "{id:int}"
@model ContosoUniversity.Pages.Students.DeleteModel
@{
ViewData["Title"] = "Delete";
}
<h2>Delete</h2>
<p class="text-danger">@Model.ErrorMessage</p>

<div>
Exclusão de teste.
Erros comuns
Alunos/Índice ou outros links não funcionam:
Verifique se a Página do Razor contém a diretiva @page correta. Por exemplo, a Razor Page Alunos/Índice não
deve conter um modelo de rota:
@page "{id:int}"
Cada Página do Razor deve incluir a diretiva @page .
Classificação, filtro, paginação – 3 de 8
Por Tom Dykstra, Rick Anderson e Jon P Smith
Neste tutorial, as funcionalidades de classificação, filtragem, agrupamento e paginação são adicionadas.
A ilustração a seguir mostra uma página concluída. Os títulos de coluna são links clicáveis para classificar a
coluna. Clicar em um título de coluna alterna repetidamente entre a ordem de classificação ascendente e
descendente.
Caso tenha problemas que não consiga resolver, baixe o aplicativo concluído.
Adicionar uma classificação à página Índice

Adicione cadeias de caracteres ao PageModel de Students/Index.cshtml.cs para que ele contenha os parâmetros de
classificação:
{
public IndexModel(SchoolContext context)

{
_context = context;
}
public string NameSort { get; set; }

public string DateSort { get; set; }
public string CurrentFilter { get; set; }
public string CurrentSort { get; set; }
Atualize OnGetAsync de Students/Index.cshtml.cs com o seguinte código:
public async Task OnGetAsync(string sortOrder)

{
NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
DateSort = sortOrder == "Date" ? "date_desc" : "Date";
IQueryable<Student> studentIQ = from s in _context.Student

select s;
switch (sortOrder)
{
case "name_desc":
studentIQ = studentIQ.OrderByDescending(s => s.LastName);
break;
case "Date":
studentIQ = studentIQ.OrderBy(s => s.EnrollmentDate);
break;
case "date_desc":
studentIQ = studentIQ.OrderByDescending(s => s.EnrollmentDate);
break;
default:
studentIQ = studentIQ.OrderBy(s => s.LastName);
break;
}
Student = await studentIQ.AsNoTracking().ToListAsync();

}
O código anterior recebe um parâmetro sortOrder da cadeia de caracteres de consulta na URL. A URL (incluindo
a cadeia de caracteres de consulta) é gerada pelo Auxiliar de Marcação de Âncora
O parâmetro sortOrder é "Name" ou "Data". O parâmetro sortOrder é opcionalmente seguido de "_desc" para
especificar a ordem descendente. A ordem de classificação crescente é padrão.
Quando a página Índice é solicitada do link Alunos, não há nenhuma cadeia de caracteres de consulta. Os alunos
são exibidos em ordem ascendente por sobrenome. A ordem ascendente por sobrenome é o padrão (caso fall-
through) na instrução switch . Quando o usuário clica em um link de título de coluna, o valor sortOrder
apropriado é fornecido no valor de cadeia de caracteres de consulta.
NameSort e DateSort são usados pela Página do Razor para configurar os hiperlinks de título de coluna com os
valores de cadeia de caracteres de consulta apropriados:
{

select s;
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}

}
O seguinte código contém o operador ?: condicional do C#:

A primeira linha especifica que, quando sortOrder é nulo ou vazio, NameSort é definido como "name_desc". Se
sortOrder não é nulo nem vazio, NameSort é definido como uma cadeia de caracteres vazia.
O ?: operator também é conhecido como o operador ternário.

Essas duas instruções permitem que a página defina os hiperlinks de título de coluna da seguinte maneira:
ORDEM DE CLASSIFICAÇÃO ATUAL HIPERLINK DO SOBRENOME HIPERLINK DE DATA
Sobrenome ascendente descending ascending
Sobrenome descendente ascending ascending
Data ascendente ascending descending
Data descendente ascending ascending
O método usa o LINQ to Entities para especificar a coluna pela qual classificar. O código inicializa um
IQueryable<Student> antes da instrução switch e modifica-o na instrução switch:
{

select s;
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}

}
Quando um IQueryable é criado ou modificado, nenhuma consulta é enviada ao banco de dados. A consulta não
é executada até que o objeto IQueryable seja convertido em uma coleção. IQueryable são convertidos em uma
coleção com uma chamada a um método como ToListAsync . Portanto, o código IQueryable resulta em uma
única consulta que não é executada até que a seguinte instrução:
OnGetAsync pode ficar detalhado com um grande número de colunas classificáveis.

Adicionar hiperlinks de título de coluna à página Student Index
Substitua o código em Students/Index.cshtml, pelo seguinte código realçado:
@page
@model ContosoUniversity.Pages.Students.IndexModel
@{
}
<h2>Index</h2>
<p>
</p>
<thead>
<tr>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort">
@Html.DisplayNameFor(model => model.Student[0].LastName)
</a>
</th>
<th>
@Html.DisplayNameFor(model => model.Student[0].FirstMidName)
</th>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.DateSort">
@Html.DisplayNameFor(model => model.Student[0].EnrollmentDate)
</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Student)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
O código anterior:
Adiciona hiperlinks aos títulos de coluna LastName e EnrollmentDate .
Usa as informações em NameSort e DateSort para configurar hiperlinks com os valores de ordem de
classificação atuais.
Para verificar se a classificação funciona:
Execute o aplicativo e selecione a guia Alunos.
Clique em Sobrenome.
Clique em Data de Registro.
Para obter um melhor entendimento do código:
Em Students/Index.cshtml.cs, defina um ponto de interrupção em switch (sortOrder) .
Adicione uma inspeção para NameSort e DateSort .
Em Students/Index.cshtml, defina um ponto de interrupção em
@Html.DisplayNameFor(model => model.Student[0].LastName) .
Execute o depurador em etapas.
Adicionar uma Caixa de Pesquisa à página Índice de Alunos

Para adicionar a filtragem à página Índice de Alunos:
Uma caixa de texto e um botão Enviar são adicionados à Página do Razor. A caixa de texto fornece uma cadeia
de caracteres de pesquisa no nome ou sobrenome.
O modelo de página é atualizado para usar o valor da caixa de texto.
Adicionar a funcionalidade de filtragem a método Index
public async Task OnGetAsync(string sortOrder, string searchString)

{
CurrentFilter = searchString;

select s;
{
studentIQ = studentIQ.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}

}
O código anterior:
Adiciona o parâmetro searchString ao método OnGetAsync . O valor de cadeia de caracteres de pesquisa é
recebido de uma caixa de texto que é adicionada na próxima seção.
Adicionou uma cláusula Where à instrução LINQ. A cláusula Where seleciona somente os alunos cujo nome
ou sobrenome contém a cadeia de caracteres de pesquisa. A instrução LINQ é executada somente se há um
valor a ser pesquisado.
Observação: o código anterior chama o método Where em um objeto IQueryable , e o filtro é processado no
servidor. Em alguns cenários, o aplicativo pode chamar o método Where como um método de extensão em uma
coleção em memória. Por exemplo, suponha que _context.Students seja alterado do DbSet do EF Core para um
método de repositório que retorna uma coleção IEnumerable . O resultado normalmente é o mesmo, mas em
alguns casos pode ser diferente.
Por exemplo, a implementação do .NET Framework do Contains executa uma comparação diferencia maiúsculas
de minúsculas por padrão. No SQL Server, a diferenciação de maiúsculas e minúsculas de Contains é
determinada pela configuração de ordenação da instância do SQL Server. O SQL Server usa como padrão a não
diferenciação de maiúsculas e minúsculas. ToUpper pode ser chamado para fazer com que o teste diferencie
maiúsculas de minúsculas de forma explícita:
Where(s => s.LastName.ToUpper().Contains(searchString.ToUpper())
O código anterior garantirá que os resultados diferenciem maiúsculas de minúsculas se o código for alterado
para usar IEnumerable . Quando Contains é chamado em uma coleção IEnumerable , a implementação do .NET
Core é usada. Quando Contains é chamado em um objeto IQueryable , a implementação do banco de dados é
usada. O retorno de um IEnumerable de um repositório pode ter uma penalidade significativa de desempenho:
1. Todas as linhas são retornadas do servidor de BD.
2. O filtro é aplicado a todas as linhas retornadas no aplicativo.
Há uma penalidade de desempenho por chamar ToUpper . O código ToUpper adiciona uma função à cláusula
WHERE da instrução TSQL SELECT. A função adicionada impede que o otimizador use um índice. Considerando
que o SQL é instalado como diferenciando maiúsculas de minúsculas, é melhor evitar a chamada ToUpper
quando ela não for necessária.
Adicionar uma Caixa de Pesquisa à página Student Index
Em Pages/Students/Index.cshtml, adicione o código realçado a seguir para criar um botão Pesquisar e o cromado
variado.
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form asp-page="./Index" method="get">

<div class="form-actions no-color">
<p>
Find by name:
<input type="text" name="SearchString" value="@Model.CurrentFilter" />
<input type="submit" value="Search" class="btn btn-default" /> |
<a asp-page="./Index">Back to full List</a>
</p>
</div>
</form>
O código anterior usa o auxiliar de marcação <form> para adicionar o botão e a caixa de texto de pesquisa. Por
padrão, o auxiliar de marcação <form> envia dados de formulário com um POST. Com o POST, os parâmetros
são passados no corpo da mensagem HTTP e não na URL. Quando o HTTP GET é usado, os dados de formulário
são passados na URL como cadeias de consulta. Passar os dados com cadeias de consulta permite aos usuários
marcar a URL. As diretrizes do W3C recomendam o uso de GET quando a ação não resulta em uma atualização.
Teste o aplicativo:
Selecione a guia Alunos e insira uma cadeia de caracteres de pesquisa.
Selecione Pesquisar.
Observe que a URL contém a cadeia de caracteres de pesquisa.
http://localhost:5000/Students?SearchString=an
Se a página estiver marcada, o indicador conterá a URL para a página e a cadeia de caracteres de consulta
SearchString . O method="get" na marcação form é o que fez com que a cadeia de caracteres de consulta fosse
gerada.
Atualmente, quando um link de classificação de título de coluna é selecionado, o valor de filtro da caixa Pesquisa
é perdido. O valor de filtro perdido é corrigido na próxima seção.
Adicionar a funcionalidade de paginação à página Índice de Alunos

Nesta seção, uma classe PaginatedList é criada para dar suporte à paginação. A classe PaginatedList usa as
instruções Skip e Take para filtrar dados no servidor em vez de recuperar todas as linhas da tabela. A ilustração
a seguir mostra os botões de paginação.
Na pasta do projeto, crie PaginatedList.cs com o seguinte código:

using System;
using System.Linq;
{
public class PaginatedList<T> : List<T>
{
public int PageIndex { get; private set; }
public int TotalPages { get; private set; }
public PaginatedList(List<T> items, int count, int pageIndex, int pageSize)

{
PageIndex = pageIndex;
TotalPages = (int)Math.Ceiling(count / (double)pageSize);
this.AddRange(items);
}
public bool HasPreviousPage

{
get
{
return (PageIndex > 1);
}
}
public bool HasNextPage

{
get
{
return (PageIndex < TotalPages);
}
}
public static async Task<PaginatedList<T>> CreateAsync(

IQueryable<T> source, int pageIndex, int pageSize)
{
var count = await source.CountAsync();
var items = await source.Skip(
(pageIndex - 1) * pageSize)
.Take(pageSize).ToListAsync();
return new PaginatedList<T>(items, count, pageIndex, pageSize);
}
}
}
O método CreateAsync no código anterior usa o tamanho da página e o número da página e aplica as instruções
Skip e Take ao IQueryable . Quando ToListAsync é chamado no IQueryable , ele retorna uma Lista que contém
somente a página solicitada. As propriedades HasPreviousPage e HasNextPage são usadas para habilitar ou
desabilitar os botões de paginação Anterior e Próximo.
O método CreateAsyncé usado para criar o PaginatedList<T> . Um construtor não pode criar o objeto
PaginatedList<T> ; construtores não podem executar um código assíncrono.
Adicionar a funcionalidade de paginação ao método Index

Em Students/Index.cshtml.cs, atualize o tipo de Student em IList<Student> para PaginatedList<Student> :
public PaginatedList<Student> Student { get; set; }

public async Task OnGetAsync(string sortOrder,

string currentFilter, string searchString, int? pageIndex)
{
CurrentSort = sortOrder;
if (searchString != null)
{
pageIndex = 1;
}
else
{
searchString = currentFilter;
}
CurrentFilter = searchString;

select s;
{
studentIQ = studentIQ.Where(s => s.LastName.Contains(searchString)
}
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}
int pageSize = 3;
Student = await PaginatedList<Student>.CreateAsync(
studentIQ.AsNoTracking(), pageIndex ?? 1, pageSize);
}
O código anterior adiciona o índice de página, o sortOrder atual e o currentFilter à assinatura do método.
public async Task OnGetAsync(string sortOrder,

string currentFilter, string searchString, int? pageIndex)
Todos os parâmetros são nulos quando:

A página é chamada no link Alunos.
O usuário ainda não clicou em um link de paginação ou classificação.
Quando um link de paginação recebe um clique, a variável de índice de páginas contém o número da página a ser
exibido.
CurrentSort fornece à Página do Razor a ordem de classificação atual. A ordem de classificação atual precisa ser
incluída nos links de paginação para que a ordem de classificação seja mantida durante a paginação.
CurrentFilter fornece à Página do Razor a cadeia de caracteres de filtro atual. O valor CurrentFilter :
Deve ser incluído nos links de paginação para que as configurações de filtro sejam mantidas durante a
paginação.
Deve ser restaurado para a caixa de texto quando a página é exibida novamente.
Se a cadeia de caracteres de pesquisa é alterada durante a paginação, a página é redefinida como 1. A página
precisa ser redefinida como 1, porque o novo filtro pode resultar na exibição de dados diferentes. Quando um
valor de pesquisa é inserido e Enviar é selecionado:
A cadeia de caracteres de pesquisa foi alterada.
O parâmetro searchString não é nulo.
{
pageIndex = 1;
}
else
{
}
O método PaginatedList.CreateAsync converte a consulta de alunos em uma única página de alunos de um tipo
de coleção compatível com paginação. Essa única página de alunos é passada para a Página do Razor.
Student = await PaginatedList<Student>.CreateAsync(

studentIQ.AsNoTracking(), pageIndex ?? 1, pageSize);
Os dois pontos de interrogação em PaginatedList.CreateAsync representam o operador de união de nulo. O

operador de união de nulo define um valor padrão para um tipo que permite valor nulo. A expressão
(pageIndex ?? 1) significará retornar o valor de pageIndex se ele tiver um valor. Se pageIndex não tiver um
valor, 1 será retornado.
Adicionar links de paginação à Página do Razor do aluno

Atualize a marcação em Students/Index.cshtml. As alterações são realçadas:
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form asp-page="./Index" method="get">

<p>
Find by name: <input type="text" name="SearchString" value="@Model.CurrentFilter" />
<a asp-page="./Index">Back to full List</a>
</p>
</div>
</form>
<thead>
<tr>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort"
asp-route-currentFilter="@Model.CurrentFilter">
</a>
</th>
<th>
@Html.DisplayNameFor(model => model.Student[0].FirstMidName)
</th>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.DateSort"
@Html.DisplayNameFor(model => model.Student[0].EnrollmentDate)
</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
@{
var prevDisabled = !Model.Student.HasPreviousPage ? "disabled" : "";
var nextDisabled = !Model.Student.HasNextPage ? "disabled" : "";
}
<a asp-page="./Index"
asp-route-sortOrder="@Model.CurrentSort"
asp-route-pageIndex="@(Model.Student.PageIndex - 1)"
asp-route-currentFilter="@Model.CurrentFilter"
class="btn btn-default @prevDisabled">
Previous
</a>
asp-route-pageIndex="@(Model.Student.PageIndex + 1)"
class="btn btn-default @nextDisabled">
Next
</a>
Os links de cabeçalho de coluna usam a cadeia de caracteres de consulta para passar a cadeia de caracteres de
pesquisa atual para o método OnGetAsync , de modo que o usuário possa classificar nos resultados do filtro:
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort"
</a>
Os botões de paginação são exibidos por auxiliares de marcação:
asp-route-pageIndex="@(Model.Student.PageIndex - 1)"
Previous
</a>
asp-route-pageIndex="@(Model.Student.PageIndex + 1)"
Next
</a>
Execute o aplicativo e navegue para a página de alunos.

Para verificar se a paginação funciona, clique nos links de paginação em ordens de classificação diferentes.
Para verificar se a paginação funciona corretamente com a classificação e filtragem, insira uma cadeia de
caracteres de pesquisa e tente fazer a paginação.
Para obter um melhor entendimento do código:

Em Students/Index.cshtml.cs, defina um ponto de interrupção em switch (sortOrder) .
Adicione uma inspeção para NameSort , DateSort , CurrentSort e Model.Student.PageIndex .
Em Students/Index.cshtml, defina um ponto de interrupção em
@Html.DisplayNameFor(model => model.Student[0].LastName) .
Execute o depurador em etapas.
Atualizar a página Sobre para mostras estatísticas de alunos

Nesta etapa, Pages/About.cshtml é atualizada para exibir quantos alunos se registraram para cada data de
registro. A atualização usa o agrupamento e inclui as seguintes etapas:
Criar um modelo de exibição para os dados usados pela página Sobre.
Atualizar a página Sobre para usar o modelo de exibição.
Criar o modelo de exibição
Crie uma pasta SchoolViewModels na pasta Models.
Na pasta SchoolViewModels, adicione um EnrollmentDateGroup.cs com o seguinte código:
using System;
namespace ContosoUniversity.Models.SchoolViewModels
{
public class EnrollmentDateGroup
{
public DateTime? EnrollmentDate { get; set; }
public int StudentCount { get; set; }

}
}
Atualizar o modelo da página Sobre

Atualize o arquivo Pages/About.cshtml.cs com o seguinte código:
using ContosoUniversity.Models.SchoolViewModels;
using System.Linq;
using ContosoUniversity.Data;
namespace ContosoUniversity.Pages
{
{
public AboutModel(SchoolContext context)

{
_context = context;
}
public IList<EnrollmentDateGroup> Student { get; set; }

{
IQueryable<EnrollmentDateGroup> data =
from student in _context.Student
group student by student.EnrollmentDate into dateGroup
select new EnrollmentDateGroup()
{
EnrollmentDate = dateGroup.Key,
StudentCount = dateGroup.Count()
};
Student = await data.AsNoTracking().ToListAsync();

}
}
}
A instrução LINQ agrupa as entidades de alunos por data de registro, calcula o número de entidades em cada
grupo e armazena os resultados em uma coleção de objetos de modelo de exibição EnrollmentDateGroup .
Modificar a Página Sobre do Razor
Substitua o código no arquivo Pages/About.cshtml pelo seguinte código:
@page
@model ContosoUniversity.Pages.AboutModel
@{
ViewData["Title"] = "Student Body Statistics";
}
<h2>Student Body Statistics</h2>
<table>
<tr>
<th>
Enrollment Date
</th>
<th>
Students
</th>
</tr>

{
<tr>
<td>
</td>
<td>
@item.StudentCount
</td>
</tr>
}
</table>
Execute o aplicativo e navegue para a página Sobre. A contagem de alunos para cada data de registro é exibida
em uma tabela.
Caso tenha problemas que não consiga resolver, baixe o aplicativo concluído para este estágio.
Recursos adicionais
Depuração de origem do ASP.NET Core 2.x
No próximo tutorial, o aplicativo usa migrações para atualizar o modelo de dados.
Migrações – 4 de 8
Neste tutorial, o recurso de migrações do EF Core para o gerenciamento de alterações do modelo de dados é
usado.
Quando um novo aplicativo é desenvolvido, o modelo de dados é alterado com frequência. Sempre que o modelo
é alterado, ele fica fora de sincronia com o banco de dados. Este tutorial começa configurando o Entity
Framework para criar o banco de dados, caso ele não exista. Sempre que o modelo de dados é alterado:
O BD é removido.
O EF cria um novo que corresponde ao modelo.
O aplicativo propaga o BD com os dados de teste.
Essa abordagem para manter o BD em sincronia com o modelo de dados funciona bem até que você implante o
aplicativo em produção. Quando o aplicativo é executado em produção, normalmente, ele armazena dados que
precisam ser mantidos. O aplicativo não pode começar com um BD de teste sempre que uma alteração é feita
(como a adição de uma nova coluna). O recurso Migrações do EF Core resolve esse problema, permitindo que o
EF Core atualize o esquema de BD em vez de criar um novo BD.
Em vez de remover e recriar o BD quando o modelo de dados é alterado, as migrações atualizam o esquema e
retêm os dados existentes.
Remover o banco de dados

Use o SSOX (Pesquisador de Objetos do SQL Server) ou o comando database drop :
Visual Studio
CLI do .NET Core
No PMC (Console do Gerenciador de Pacotes), execute o seguinte comando:
Drop-Database
Execute Get-Help about_EntityFrameworkCore no PMC para obter informações de ajuda.
Criar uma migração inicial e atualizar o BD

Crie o projeto e a primeira migração.
Visual Studio
CLI do .NET Core
Add-Migration InitialCreate
Update-Database
Examinar os métodos Up e Down

O comando migrations add do EF Core gerou um código para criar o BD. Esse código de migrações está
localizado no arquivo Migrations<timestamp>_InitialCreate.cs. O método Up da classe InitialCreate cria as
tabelas de BD que correspondem aos conjuntos de entidades do modelo de dados. O método Down exclui-os,
conforme mostrado no seguinte exemplo:
public partial class InitialCreate : Migration

{
protected override void Up(MigrationBuilder migrationBuilder)
{
migrationBuilder.CreateTable(
name: "Course",
columns: table => new
{
CourseID = table.Column<int>(nullable: false),
Title = table.Column<string>(nullable: true),
Credits = table.Column<int>(nullable: false)
},
constraints: table =>
{
table.PrimaryKey("PK_Course", x => x.CourseID);
});
protected override void Down(MigrationBuilder migrationBuilder)
{
migrationBuilder.DropTable(
name: "Enrollment");
name: "Course");
name: "Student");
}
}
As migrações chamam o método Up para implementar as alterações do modelo de dados para uma migração.
Quando você insere um comando para reverter a atualização, as migrações chamam o método Down .
O código anterior refere-se à migração inicial. Esse código foi criado quando o comando
migrations add InitialCreate foi executado. O parâmetro de nome da migração ("InitialCreate" no exemplo) é
usado para o nome do arquivo. O nome da migração pode ser qualquer nome de arquivo válido. É melhor
escolher uma palavra ou frase que resume o que está sendo feito na migração. Por exemplo, uma migração que
adicionou uma tabela de departamento pode ser chamada "AddDepartmentTable".
Se a migração inicial foi criada e o BD existe:
O código de criação do BD é gerado.
O código de criação do BD não precisa ser executado porque o BD já corresponde ao modelo de dados. Se o
código de criação do BD for executado, ele não fará nenhuma alteração porque o BD já corresponde ao
modelo de dados.
Quando o aplicativo é implantado em um novo ambiente, o código de criação do BD precisa ser executado para
criar o BD.
Anteriormente, o BD foi removido, e não existe mais. Então, as migrações criam o novo BD.
O instantâneo do modelo de dados
As migrações criam um instantâneo do esquema de banco de dados atual em
Migrations/SchoolContextModelSnapshot.cs. Quando você adiciona uma migração, o EF determina o que foi
alterado, comparando o modelo de dados com o arquivo de instantâneo.
Para excluir uma migração, use o seguinte comando:
Visual Studio
CLI do .NET Core
Remove-Migration
O comando de exclusão de migrações exclui a migração e garante que o instantâneo seja redefinido
corretamente.
Remover EnsureCreated e testar o aplicativo
Para o desenvolvimento inicial, EnsureCreated foi usado. Neste tutorial, as migrações são usadas. EnsureCreated
tem as seguintes limitações:
Ignora as migrações e cria o BD e o esquema.
Não cria uma tabela de migrações.
Não pode ser usado com migrações.
Foi projetado para teste ou criação rápida de protótipos em que o BD é removido e recriado com frequência.
Remova a seguinte linha de DbInitializer :
Execute o aplicativo e verifique se o BD é propagado.

Inspecionar o banco de dados
Use o Pesquisador de Objetos do SQL Server para inspecionar o BD. Observe a adição de uma tabela
__EFMigrationsHistory . A tabela __EFMigrationsHistory controla quais migrações foram aplicadas ao BD. Exiba
os dados na __EFMigrationsHistory tabela; ela mostra uma linha para a primeira migração. O último log no
exemplo de saída da CLI anterior mostra a instrução INSERT que cria essa linha.
Execute o aplicativo e verifique se tudo funciona.
Aplicando migrações na produção

Recomendamos que os aplicativos de produção não chamem Database.Migrate na inicialização do aplicativo.
Migrate não deve ser chamado em um aplicativo no farm de servidores. Por exemplo, se o aplicativo foi
implantado na nuvem com escalabilidade horizontal (várias instâncias do aplicativo estão sendo executadas).
A migração de banco de dados deve ser feita como parte da implantação e de maneira controlada. Abordagens
de migração de banco de dados de produção incluem:
Uso de migrações para criar scripts SQL e uso dos scripts SQL na implantação.
Execução de dotnet ef database update em um ambiente controlado.
O EF Core usa a tabela __MigrationsHistory para ver se uma migração precisa ser executada. Se o BD estiver
atualizado, nenhuma migração será executada.
Baixar o aplicativo concluído.
O aplicativo gera a seguinte exceção:
SqlException: Cannot open database "ContosoUniversity" requested by the login.

The login failed.
Login failed for user 'user name'.
Solução: execute dotnet ef database update
Recursos adicionais
CLI do .NET Core.
Console do Gerenciador de Pacotes (Visual Studio)
Modelo de dados – 5 de 8
Os tutoriais anteriores trabalharam com um modelo de dados básico composto por três entidades. Neste tutorial:
Mais entidades e relações são adicionadas.
O modelo de dados é personalizado com a especificação das regras de formatação, validação e mapeamento
de banco de dados.
As classes de entidade para o modelo de dados concluído são mostradas na seguinte ilustração:
Personalizar o modelo de dados com atributos

Nesta seção, o modelo de dados é personalizado com atributos.
O atributo DataType
As páginas de alunos atualmente exibem a hora da data de registro. Normalmente, os campos de data mostram
apenas a data e não a hora.
Atualize Models/Student.cs com o seguinte código realçado:
using System;
{
{

}
}
O atributo DataType especifica um tipo de dados mais específico do que o tipo intrínseco de banco de dados.
Neste caso, apenas a data deve ser exibida, não a data e a hora. A Enumeração DataType fornece muitos tipos de
dados, como Date, Time, PhoneNumber, Currency, EmailAddress, etc. O atributo DataType também pode
permitir que o aplicativo forneça automaticamente recursos específicos a um tipo. Por exemplo:
O link mailto: é criado automaticamente para DataType.EmailAddress .
O seletor de data é fornecido para DataType.Date na maioria dos navegadores.
O atributo DataType emite atributos data- HTML 5 (pronunciados “data dash”) que são consumidos pelos
navegadores HTML 5. Os atributos DataType não fornecem validação.
A configuração ApplyFormatInEditMode especifica que a formatação também deve ser aplicada à interface do
usuário de edição. Alguns campos não devem usar ApplyFormatInEditMode . Por exemplo, o símbolo de moeda
geralmente não deve ser exibido em uma caixa de texto de edição.
O atributo DisplayFormat pode ser usado por si só. Geralmente, é uma boa ideia usar o atributo DataType com o
atributo DisplayFormat . O atributo DataType transmite a semântica dos dados em vez de como renderizá-los em
uma tela. O atributo DataType oferece os seguintes benefícios que não estão disponíveis em DisplayFormat :
O navegador pode habilitar recursos do HTML5. Por exemplo, mostra um controle de calendário, o símbolo de
moeda apropriado à localidade, links de email, validação de entrada do lado do cliente, etc.
Por padrão, o navegador renderiza os dados usando o formato correto de acordo com a localidade.
Para obter mais informações, consulte a documentação do Auxiliar de Marcação <input>.
Execute o aplicativo. Navegue para a página Índice de Alunos. As horas não são mais exibidas. Cada exibição que
usa o modelo Student exibe a data sem a hora.
O atributo StringLength
Regras de validação de dados e mensagens de erro de validação podem ser especificadas com atributos. O
atributo StringLength especifica o tamanho mínimo e máximo de caracteres permitidos em um campo de dados.
O atributo StringLength também fornece a validação do lado do cliente e do servidor. O valor mínimo não tem
impacto sobre o esquema de banco de dados.
Atualize o modelo Student com o seguinte código:
using System;
{
{
[StringLength(50)]
[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]

}
}
O código anterior limita os nomes a, no máximo, 50 caracteres. O atributo StringLength não impede que um
usuário insira um espaço em branco em um nome. O atributo RegularExpression é usado para aplicar restrições à
entrada. Por exemplo, o seguinte código exige que o primeiro caractere esteja em maiúscula e os caracteres
restantes estejam em ordem alfabética:
Execute o aplicativo:
Navegue para a página Alunos.
Selecione Criar Novo e insira um nome com mais de 50 caracteres.
Selecione Criar e a validação do lado do cliente mostrará uma mensagem de erro.
No SSOX (Pesquisador de Objetos do SQL Server), abra o designer de tabela Aluno clicando duas vezes na
tabela Aluno.
A imagem anterior mostra o esquema para a tabela Student . Os campos de nome têm o tipo nvarchar(MAX)
porque as migrações não foram executadas no BD. Quando as migrações forem executadas mais adiante neste
tutorial, os campos de nome se tornarão nvarchar(50) .
O atributo Column
Os atributos podem controlar como as classes e propriedades são mapeadas para o banco de dados. Nesta seção,
o atributo Column é usado para mapear o nome da propriedade FirstMidName como "FirstName" no BD.
Quando o BD é criado, os nomes de propriedade no modelo são usados para nomes de coluna (exceto quando o
atributo Column é usado).
O modelo Student usa FirstMidName para o campo de nome porque o campo também pode conter um
sobrenome.
Atualize o arquivo Student.cs com o seguinte código:
using System;
{
{
[StringLength(50)]
[Column("FirstName")]

}
}
Com a alteração anterior, Student.FirstMidName no aplicativo é mapeado para a coluna FirstName da tabela
Student .
A adição do atributo Column altera o modelo que dá suporte ao SchoolContext . O modelo que dá suporte ao
SchoolContext não corresponde mais ao banco de dados. Se o aplicativo for executado antes da aplicação das
migrações, a seguinte exceção será gerada:
SqlException: Invalid column name 'FirstName'.
Para atualizar o BD:

Compile o projeto.
Abra uma janela Comando na pasta do projeto. Insira os seguintes comandos para criar uma nova migração e
atualizar o BD:
Visual Studio
CLI do .NET Core
Add-Migration ColumnFirstName
Update-Database
O comando migrations add ColumnFirstName gera a seguinte mensagem de aviso:
An operation was scaffolded that may result in the loss of data.

Please review the migration for accuracy.
O aviso é gerado porque os campos de nome agora estão limitados a 50 caracteres. Se um nome no BD tiver
mais de 50 caracteres, o 51º caractere até o último caractere serão perdidos.
Teste o aplicativo.
Abra a tabela Alunos no SSOX:
Antes de a migração ser aplicada, as colunas de nome eram do tipo nvarchar(MAX). As colunas de nome agora
são nvarchar(50) . O nome da coluna foi alterado de FirstMidName para FirstName .
NOTE
Na seção a seguir, a criação do aplicativo em alguns estágios gera erros do compilador. As instruções especificam quando
compilar o aplicativo.
Atualização da entidade Student
Atualize Models/Student.cs com o seguinte código:

using System;
{
{
[Required]
[StringLength(50)]
[Display(Name = "Last Name")]
[Required]
[Display(Name = "First Name")]
[Display(Name = "Enrollment Date")]
[Display(Name = "Full Name")]
public string FullName
{
get
{
return LastName + ", " + FirstMidName;
}
}

}
}
O atributo Required
O atributo Required torna as propriedades de nome campos obrigatórios. O atributo Required não é necessário
para tipos que não permitem valor nulo, como tipos de valor ( DateTime , int , double , etc.). Tipos que não
podem ser nulos são tratados automaticamente como campos obrigatórios.
O atributo Required pode ser substituído por um parâmetro de tamanho mínimo no atributo StringLength :

[StringLength(50, MinimumLength=1)]
O atributo Display
O atributo Display especifica que a legenda para as caixas de texto deve ser "Nome", "Sobrenome", "Nome
Completo" e "Data de Registro". As legendas padrão não tinham nenhum espaço entre as palavras, por exemplo,
"Lastname".
A propriedade calculada FullName
FullName é uma propriedade calculada que retorna um valor criado pela concatenação de duas outras
propriedades. FullName não pode ser definido; ele apenas tem um acessador get. Nenhuma coluna FullName é
criada no banco de dados.
Criar a entidade Instructor

Crie Models/Instructor.cs com o seguinte código:
using System;
{
public class Instructor
{
[Required]
[StringLength(50)]
[Required]
[StringLength(50)]
[Display(Name = "Hire Date")]
public DateTime HireDate { get; set; }

{
get { return LastName + ", " + FirstMidName; }
}
public ICollection<CourseAssignment> CourseAssignments { get; set; }

public OfficeAssignment OfficeAssignment { get; set; }
}
}
Vários atributos podem estar em uma linha. Os atributos HireDate podem ser escritos da seguinte maneira:
[DataType(DataType.Date),Display(Name = "Hire Date"),DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}",

ApplyFormatInEditMode = true)]
As propriedades de navegação CourseAssignments e OfficeAssignment

As propriedades CourseAssignments e OfficeAssignment são propriedades de navegação.
Um instrutor pode ministrar qualquer quantidade de cursos e, portanto, CourseAssignments é definido como uma
coleção.
Se uma propriedade de navegação armazenar várias entidades:

Ele deve ser um tipo de lista no qual as entradas possam ser adicionadas, excluídas e atualizadas.
Os tipos de propriedade de navegação incluem:
ICollection<T>
List<T>
HashSet<T>
Se ICollection<T> for especificado, o EF Core criará uma coleção HashSet<T> por padrão.
A entidade CourseAssignment é explicada na seção sobre relações muitos para muitos.
Regras de negócio do Contoso University indicam que um instrutor pode ter, no máximo, um escritório. A
propriedade OfficeAssignment contém uma única entidade OfficeAssignment . OfficeAssignment será nulo se
nenhum escritório for atribuído.
Criar a entidade OfficeAssignment
Crie Models/OfficeAssignment.cs com o seguinte código:
{
public class OfficeAssignment
{
[Key]
public int InstructorID { get; set; }
[StringLength(50)]
[Display(Name = "Office Location")]
public string Location { get; set; }
public Instructor Instructor { get; set; }

}
}
O atributo Key
O atributo [Key] é usado para identificar uma propriedade como a PK (chave primária) quando o nome da
propriedade é algo diferente de classnameID ou ID.
Há uma relação um para zero ou um entre as entidades Instructor e OfficeAssignment . Uma atribuição de
escritório existe apenas em relação ao instrutor ao qual ela é atribuída. A PK OfficeAssignment também é a FK
(chave estrangeira) da entidade Instructor . O EF Core não pode reconhecer InstructorID automaticamente
como o PK de OfficeAssignment porque:
InstructorID não segue a convenção de nomenclatura de ID nem de classnameID.
Portanto, o atributo Key é usado para identificar InstructorID como a PK:
[Key]
Por padrão, o EF Core trata a chave como não gerada pelo banco de dados porque a coluna destina-se a uma
relação de identificação.
A propriedade de navegação Instructor
A propriedade de navegação OfficeAssignment da entidade Instructor permite valor nulo porque:
Tipos de referência (como classes que permitem valor nulo).
Um instrutor pode não ter uma atribuição de escritório.
A entidade OfficeAssignment tem uma propriedade de navegação Instructor que não permite valor nulo
porque:
InstructorIDnão permite valor nulo.
Uma atribuição de escritório não pode existir sem um instrutor.
Quando uma entidade Instructor tem uma entidade OfficeAssignment relacionada, cada entidade tem uma
referência à outra em sua propriedade de navegação.
O atributo [Required] pode ser aplicado à propriedade de navegação Instructor :
[Required]
O código anterior especifica que deve haver um instrutor relacionado. O código anterior é desnecessário porque
a chave estrangeira InstructorID (que também é a PK) não permite valor nulo.
Modificar a entidade Course
Atualize Models/Course.cs com o seguinte código:

{
public class Course
{
[Display(Name = "Number")]

[Range(0, 5)]
public int DepartmentID { get; set; }
public Department Department { get; set; }

}
}
A entidade Course tem uma propriedade de FK (chave estrangeira) DepartmentID . DepartmentID aponta para a
entidade Department relacionada. A entidade Course tem uma propriedade de navegação Department .
O EF Core não exige uma propriedade de FK para um modelo de dados quando o modelo tem uma propriedade
de navegação para uma entidade relacionada.
O EF Core cria automaticamente FKs no banco de dados sempre que forem necessárias. O EF Core cria
propriedades de sombra para FKs criadas automaticamente. Ter a FK no modelo de dados pode tornar as
atualizações mais simples e mais eficientes. Por exemplo, considere um modelo em que a propriedade de FK
DepartmentID não é incluída. Quando uma entidade de curso é buscada para editar:
A entidade Department será nula se não for carregada de forma explícita.

Para atualizar a entidade de curso, a entidade Department primeiro deve ser buscada.
Quando a propriedade de FK DepartmentID está incluída no modelo de dados, não é necessário buscar a entidade
Department antes de uma atualização.
O atributo DatabaseGenerated
O atributo [DatabaseGenerated(DatabaseGeneratedOption.None)] especifica que a PK é fornecida pelo aplicativo em
vez de ser gerada pelo banco de dados.
Por padrão, o EF Core supõe que os valores de PK sejam gerados pelo BD. Os valores de PK gerados pelo BD
geralmente são a melhor abordagem. Para entidades Course , o usuário especifica o PK. Por exemplo, um número
de curso, como uma série 1000 para o departamento de matemática e uma série 2000 para o departamento em
inglês.
O atributo DatabaseGenerated também pode ser usado para gerar valores padrão. Por exemplo, o BD pode gerar
automaticamente um campo de data para registrar a data em que uma linha foi criada ou atualizada. Para obter
mais informações, consulte Propriedades geradas.
Propriedades de navegação e de chave estrangeira
As propriedades de navegação e de FK (chave estrangeira) na entidade Course refletem as seguintes relações:
Um curso é atribuído a um departamento; portanto, há uma FK DepartmentID e uma propriedade de navegação
Department .

Um curso pode ter qualquer quantidade de estudantes inscritos; portanto, a propriedade de navegação
Enrollments é uma coleção:
Um curso pode ser ministrado por vários instrutores; portanto, a propriedade de navegação CourseAssignments é
uma coleção:
CourseAssignment é explicado posteriormente.
Criar a entidade Department
Crie Models/Department.cs com o seguinte código:

using System;
{
public class Department
{

[Column(TypeName = "money")]
public decimal Budget { get; set; }
[Display(Name = "Start Date")]
public DateTime StartDate { get; set; }
public int? InstructorID { get; set; }
public Instructor Administrator { get; set; }

public ICollection<Course> Courses { get; set; }
}
}
O atributo Column
Anteriormente, o atributo Column foi usado para alterar o mapeamento de nome de coluna. No código da
entidade Department , o atributo Column é usado para alterar o mapeamento de tipo de dados SQL. A coluna
Budget é definida usando o tipo de dinheiro do SQL Server no BD:
[Column(TypeName="money")]
Em geral, o mapeamento de coluna não é necessário. Em geral, o EF Core escolhe o tipo de dados do SQL Server
apropriado com base no tipo CLR da propriedade. O tipo decimal CLR é mapeado para um tipo decimal SQL
Server. Budget refere-se à moeda e o tipo de dados de dinheiro é mais apropriado para moeda.
As propriedades de navegação e de FK refletem as seguintes relações:
Um departamento pode ou não ter um administrador.
Um administrador é sempre um instrutor. Portanto, a propriedade InstructorID está incluída como a FK da
entidade Instructor .
A propriedade de navegação é chamada Administrator , mas contém uma entidade Instructor :

O ponto de interrogação (?) no código anterior especifica que a propriedade permite valor nulo.
Um departamento pode ter vários cursos e, portanto, há uma propriedade de navegação Courses:
Observação: por convenção, o EF Core habilita a exclusão em cascata em FKs que não permitem valor nulo e em
relações muitos para muitos. A exclusão em cascata pode resultar em regras de exclusão em cascata circular. As
regras de exclusão em cascata circular causam uma exceção quando uma migração é adicionada.
Por exemplo, se a propriedade Department.InstructorID não foi definida como uma propriedade que permite
valor nulo:
O EF Core configura uma regra de exclusão em cascata para excluir o instrutor quando o departamento é
excluído.
A exclusão do instrutor quando o departamento é excluído não é o comportamento pretendido.
Se as regras de negócio exigirem que a propriedade InstructorID não permita valor nulo, use a seguinte
instrução da API fluente:
modelBuilder.Entity<Department>()
.HasOne(d => d.Administrator)
.WithMany()
.OnDelete(DeleteBehavior.Restrict)
O código anterior desabilita a exclusão em cascata na relação departamento-instrutor.
Atualizar a entidade Enrollment

Um registro se refere a um curso feito por um aluno.
Atualize Models/Enrollment.cs com o seguinte código:

{
public enum Grade
{
A, B, C, D, F
}

{
[DisplayFormat(NullDisplayText = "No grade")]

}
}

As propriedades de navegação e de FK refletem as seguintes relações:
Um registro destina-se a um curso e, portanto, há uma propriedade de FK CourseID e uma propriedade de
navegação Course :

Um registro destina-se a um aluno e, portanto, há uma propriedade de FK StudentID e uma propriedade de

navegação Student :

Relações muitos para muitos

Há uma relação muitos para muitos entre as entidades Student e Course . A entidade Enrollment funciona como
uma tabela de junção muitos para muitos com conteúdo no banco de dados. "Com conteúdo" significa que a
tabela Enrollment contém dados adicionais além das FKs das tabelas unidas (nesse caso, a FK e Grade ).
A ilustração a seguir mostra a aparência dessas relações em um diagrama de entidades. (Esse diagrama foi
gerado com o EF Power Tools para EF 6.x. A criação do diagrama não faz parte do tutorial.)
Cada linha de relação tem um 1 em uma extremidade e um asterisco (*) na outra, indicando uma relação um para
muitos.
Se a tabela Enrollment não incluir informações de nota, ela apenas precisará conter as duas FKs ( CourseID e
StudentID ). Uma tabela de junção muitos para muitos sem conteúdo é às vezes chamada de PJT (uma tabela de
junção pura).
As entidades Instructor e Course têm uma relação muitos para muitos usando uma tabela de junção pura.
Observação: o EF 6.x é compatível com tabelas de junção implícita para relações muitos para muitos, ao contrário
do EF Core. Para obter mais informações, consulte Relações muitos para muitos no EF Core 2.0.
A entidade CourseAssignment
Crie Models/CourseAssignment.cs com o seguinte código:

using System;
{
public class CourseAssignment
{
}
}
Instrutor para Cursos
A relação muitos para muitos de Instrutor para Cursos:

Exige que uma tabela de junção seja representada por um conjunto de entidades.
É uma tabela de junção pura (tabela sem conteúdo).
É comum nomear uma entidade de junção EntityName1EntityName2 . Por exemplo, a tabela de junção Instrutor
para Cursos com esse padrão é CourseInstructor . No entanto, recomendamos que você use um nome que
descreve a relação.
Modelos de dados começam simples e aumentam. PJTs (junções sem conteúdo) evoluem com frequência para
incluir o conteúdo. Começando com um nome descritivo de entidade, o nome não precisa ser alterado quando a
tabela de junção é alterada. O ideal é que a entidade de junção tenha seu próprio nome natural (possivelmente,
uma única palavra) no domínio de negócios. Por exemplo, Manuais e Clientes podem ser vinculados com uma
entidade de junção chamada Ratings. Para a relação muitos para muitos de Instrutor para Cursos,
CourseAssignment é preferível a CourseInstructor .
Chave composta
As FKs não permitem valor nulo. As duas FKs em CourseAssignment ( InstructorID e CourseID ) juntas
identificam exclusivamente cada linha da tabela CourseAssignment . CourseAssignment não exige um PK dedicado.
As propriedades InstructorID e CourseID funcionam como uma PK composta. A única maneira de especificar
PKs compostas no EF Core é com a API fluente. A próxima seção mostra como configurar a PK composta.
A chave composta garante:
Várias linhas são permitidas para um curso.
Várias linhas são permitidas para um instrutor.
Não é permitido ter várias linhas para o mesmo instrutor e curso.
A entidade de junção Enrollment define sua própria PK e, portanto, duplicatas desse tipo são possíveis. Para
impedir duplicatas como essas:
Adicione um índice exclusivo nos campos de FK ou
Configure Enrollment com uma chave primária composta semelhante a CourseAssignment . Para obter mais
informações, consulte Índices.
Atualizar o contexto de BD
Adicione o seguinte código realçado a Data/SchoolContext.cs:
{
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}
public DbSet<Course> Courses { get; set; }

public DbSet<Enrollment> Enrollment { get; set; }
public DbSet<Student> Student { get; set; }
public DbSet<Department> Departments { get; set; }
public DbSet<Instructor> Instructors { get; set; }
public DbSet<OfficeAssignment> OfficeAssignments { get; set; }
public DbSet<CourseAssignment> CourseAssignments { get; set; }
protected override void OnModelCreating(ModelBuilder modelBuilder)

{
modelBuilder.Entity<Course>().ToTable("Course");
modelBuilder.Entity<Enrollment>().ToTable("Enrollment");
modelBuilder.Entity<Student>().ToTable("Student");
modelBuilder.Entity<Department>().ToTable("Department");
modelBuilder.Entity<Instructor>().ToTable("Instructor");
modelBuilder.Entity<OfficeAssignment>().ToTable("OfficeAssignment");
modelBuilder.Entity<CourseAssignment>().ToTable("CourseAssignment");
modelBuilder.Entity<CourseAssignment>()
.HasKey(c => new { c.CourseID, c.InstructorID });
}
}
}
O código anterior adiciona novas entidades e configura a PK composta da entidade CourseAssignment .

Alternativa de API fluente para atributos
O método OnModelCreating no código anterior usa a API fluente para configurar o comportamento do EF Core. A
API é chamada "fluente" porque geralmente é usada pelo encadeamento de uma série de chamadas de método
em uma única instrução. O seguinte código é um exemplo da API fluente:

{
modelBuilder.Entity<Blog>()
.Property(b => b.Url)
.IsRequired();
}
Neste tutorial, a API fluente é usada apenas para o mapeamento do BD que não pode ser feito com atributos. No
entanto, a API fluente pode especificar a maioria das regras de formatação, validação e mapeamento que pode
ser feita com atributos.
Alguns atributos como MinimumLength não podem ser aplicados com a API fluente. MinimumLength não altera o
esquema; apenas aplica uma regra de validação de tamanho mínimo.
Alguns desenvolvedores preferem usar a API fluente exclusivamente para que possam manter suas classes de
entidade "limpas". Atributos e a API fluente podem ser combinados. Há algumas configurações que apenas
podem ser feitas com a API fluente (especificando uma PK composta). Há algumas configurações que apenas
podem ser feitas com atributos ( MinimumLength ). A prática recomendada para uso de atributos ou da API fluente:
Escolha uma dessas duas abordagens.
Use a abordagem escolhida da forma mais consistente possível.
Alguns dos atributos usados neste tutorial são usados para:
Somente validação (por exemplo, MinimumLength ).
Apenas configuração do EF Core (por exemplo, HasKey ).
Validação e configuração do EF Core (por exemplo, [StringLength(50)] ).
Para obter mais informações sobre atributos vs. API fluente, consulte Métodos de configuração.
Diagrama de entidade mostrando relações

A ilustração a seguir mostra o diagrama criado pelo EF Power Tools para o modelo Escola concluído.
O diagrama anterior mostra:
Várias linhas de relação um-para-muitos (1 para *).
A linha de relação um para zero ou um (1 para 0..1) entre as entidades Instructor e OfficeAssignment .
A linha de relação zero-ou-um-para-muitos (0..1 para *) entre as entidades Instructor e Department .
Propagar o BD com os dados de teste

Atualize o código em Data/DbInitializer.cs:
using System;
using System.Linq;
namespace ContosoUniversity.Data
{
{
{
//context.Database.EnsureCreated();
if (context.Student.Any())
{
}

{
new Student { FirstMidName = "Carson", LastName = "Alexander",
EnrollmentDate = DateTime.Parse("2010-09-01") },
new Student { FirstMidName = "Meredith", LastName = "Alonso",
new Student { FirstMidName = "Arturo", LastName = "Anand",
new Student { FirstMidName = "Gytis", LastName = "Barzdukas",
new Student { FirstMidName = "Yan", LastName = "Li",
new Student { FirstMidName = "Peggy", LastName = "Justice",
new Student { FirstMidName = "Laura", LastName = "Norman",
new Student { FirstMidName = "Nino", LastName = "Olivetto",
EnrollmentDate = DateTime.Parse("2005-09-01") }
};

{
context.Student.Add(s);
}
var instructors = new Instructor[]

{
new Instructor { FirstMidName = "Kim", LastName = "Abercrombie",
HireDate = DateTime.Parse("1995-03-11") },
new Instructor { FirstMidName = "Fadi", LastName = "Fakhouri",
new Instructor { FirstMidName = "Roger", LastName = "Harui",
new Instructor { FirstMidName = "Candace", LastName = "Kapoor",
new Instructor { FirstMidName = "Roger", LastName = "Zheng",
HireDate = DateTime.Parse("2004-02-12") }
};
foreach (Instructor i in instructors)

{
context.Instructors.Add(i);
}
var departments = new Department[]

{
new Department { Name = "English", Budget = 350000,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Abercrombie").ID },
new Department { Name = "Mathematics", Budget = 100000,
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID },
new Department { Name = "Engineering", Budget = 350000,
InstructorID = instructors.Single( i => i.LastName == "Harui").ID },
new Department { Name = "Economics", Budget = 100000,
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID }
};
foreach (Department d in departments)

{
context.Departments.Add(d);
}

{
new Course {CourseID = 1050, Title = "Chemistry", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "Engineering").DepartmentID
},
new Course {CourseID = 4022, Title = "Microeconomics", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "Economics").DepartmentID
},
new Course {CourseID = 4041, Title = "Macroeconomics", Credits = 3,
},
new Course {CourseID = 1045, Title = "Calculus", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 3141, Title = "Trigonometry", Credits = 4,
},
new Course {CourseID = 2021, Title = "Composition", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
new Course {CourseID = 2042, Title = "Literature", Credits = 4,
},
};

{
context.Courses.Add(c);
}
var officeAssignments = new OfficeAssignment[]

{
new OfficeAssignment {
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID,
Location = "Smith 17" },
InstructorID = instructors.Single( i => i.LastName == "Harui").ID,
Location = "Gowan 27" },
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID,
Location = "Thompson 304" },
};
foreach (OfficeAssignment o in officeAssignments)

{
context.OfficeAssignments.Add(o);
}
var courseInstructors = new CourseAssignment[]

{
new CourseAssignment {
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID,
InstructorID = instructors.Single(i => i.LastName == "Kapoor").ID
},
InstructorID = instructors.Single(i => i.LastName == "Harui").ID
},
CourseID = courses.Single(c => c.Title == "Microeconomics" ).CourseID,
InstructorID = instructors.Single(i => i.LastName == "Zheng").ID
},
},
CourseID = courses.Single(c => c.Title == "Macroeconomics" ).CourseID,
},
CourseID = courses.Single(c => c.Title == "Calculus" ).CourseID,
InstructorID = instructors.Single(i => i.LastName == "Fakhouri").ID
},
CourseID = courses.Single(c => c.Title == "Trigonometry" ).CourseID,
},
CourseID = courses.Single(c => c.Title == "Composition" ).CourseID,
InstructorID = instructors.Single(i => i.LastName == "Abercrombie").ID
},
CourseID = courses.Single(c => c.Title == "Literature" ).CourseID,
},
};
foreach (CourseAssignment ci in courseInstructors)

{
context.CourseAssignments.Add(ci);
}

{
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
Grade = Grade.A
},
new Enrollment {
Grade = Grade.C
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
Grade = Grade.B
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID
},
new Enrollment {
CourseID = courses.Single(c => c.Title == "Microeconomics").CourseID,
Grade = Grade.B
},
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Barzdukas").ID,
CourseID = courses.Single(c => c.Title == "Chemistry").CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Li").ID,
CourseID = courses.Single(c => c.Title == "Composition").CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Justice").ID,
CourseID = courses.Single(c => c.Title == "Literature").CourseID,
Grade = Grade.B
}
};

{
var enrollmentInDataBase = context.Enrollment.Where(
s =>
s.Student.ID == e.StudentID &&
s.Course.CourseID == e.CourseID).SingleOrDefault();
if (enrollmentInDataBase == null)
{
context.Enrollment.Add(e);
}
}
}
}
}
O código anterior fornece dados de semente para as novas entidades. A maioria desse código cria novos objetos
de entidade e carrega dados de exemplo. Os dados de exemplo são usados para teste. O código anterior cria as
seguintes relações muitos para muitos:
Enrollments
CourseAssignment
Adicionar uma migração

Compile o projeto.
Visual Studio
CLI do .NET Core
Add-Migration ComplexDataModel
O comando anterior exibe um aviso sobre a possível perda de dados.
An operation was scaffolded that may result in the loss of data.

Please review the migration for accuracy.
Done. To undo this action, use 'ef migrations remove'
Se o comando database update é executado, o seguinte erro é produzido:

The ALTER TABLE statement conflicted with the FOREIGN KEY constraint
"FK_dbo.Course_dbo.Department_DepartmentID". The conflict occurred in
database "ContosoUniversity", table "dbo.Department", column 'DepartmentID'.
Aplicar a migração
Agora que você tem um banco de dados existente, precisa pensar sobre como aplicar as alterações futuras a ele.
Este tutorial mostra duas abordagens:
Remover e recriar o banco de dados
Aplicar a migração ao banco de dados existente. Embora esse método seja mais complexo e demorado, é a
abordagem preferencial para ambientes de produção do mundo real. Observação: essa é uma seção opcional
do tutorial. Você pode remover e recriar etapas e ignorar esta seção. Se você quiser seguir as etapas nesta
seção, não realize as etapas de remover e recriar.
Remover e recriar o banco de dados
O código no DbInitializer atualizado adiciona dados de semente às novas entidades. Para forçar o EF Core a
criar um novo BD, remova e atualize o BD:
Visual Studio
CLI do .NET Core
No PMC (Console do Gerenciador de Pacotes), execute o seguinte comando:
Drop-Database
Update-Database
Execute Get-Help about_EntityFrameworkCore no PMC para obter informações de ajuda.

Execute o aplicativo. A execução do aplicativo executa o método DbInitializer.Initialize .O
DbInitializer.Initialize popula o novo BD.
Abra o BD no SSOX:
Se o SSOX for aberto anteriormente, clique no botão Atualizar.
Expanda o nó Tabelas. As tabelas criadas são exibidas.
Examine a tabela CourseAssignment:

Clique com o botão direito do mouse na tabela CourseAssignment e selecione Exibir Dados.
Verifique se a tabela CourseAssignment contém dados.
Aplicar a migração ao banco de dados existente

Esta seção é opcional. Estas etapas só funcionarão se você tiver ignorado a seção Remover e recriar o banco de
dados anterior.
Quando as migrações são executadas com os dados existentes, pode haver restrições de FK que não são
atendidas com os dados existentes. Com os dados de produção, é necessário executar etapas para migrar os
dados existentes. Esta seção fornece um exemplo de correção de violações de restrição de FK. Não faça essas
alterações de código sem um backup. Não faça essas alterações de código se você concluir a seção anterior e
atualizou o banco de dados.
O arquivo {timestamp }_ComplexDataModel.cs contém o seguinte código:
migrationBuilder.AddColumn<int>(
name: "DepartmentID",
table: "Course",
type: "int",
nullable: false,
defaultValue: 0);
O código anterior adiciona uma FK DepartmentID que não permite valor nulo à tabela Course . O BD do tutorial
anterior contém linhas em Course e, portanto, essa tabela não pode ser atualizada por migrações.
Para fazer a migração ComplexDataModel funcionar com os dados existentes:
Altere o código para dar à nova coluna ( DepartmentID ) um valor padrão.
Crie um departamento fictício chamado "Temp" para atuar como o departamento padrão.
Corrigir as restrições de chave estrangeira
Atualize o método Up das classes ComplexDataModel :
Abra o arquivo {timestamp }_ComplexDataModel.cs.
Comente a linha de código que adiciona a coluna DepartmentID à tabela Course .
migrationBuilder.AlterColumn<string>(
name: "Title",
table: "Course",
maxLength: 50,
nullable: true,
oldClrType: typeof(string),
oldNullable: true);
//migrationBuilder.AddColumn<int>(
// name: "DepartmentID",
// table: "Course",
// nullable: false,
// defaultValue: 0);
Adicione o código realçado a seguir. O novo código é inserido após o bloco .CreateTable( name: "Department" :
[!code-csharp]
Com as alterações anteriores, as linhas Course existentes estarão relacionadas ao departamento "Temp" após a
execução do método ComplexDataModel Up .
Um aplicativo de produção:
Inclui código ou scripts para adicionar linhas Department e linhas Course relacionadas às novas linhas
Department .
Não usa o departamento "Temp" nem o valor padrão para Course.DepartmentID .
O próximo tutorial abrange os dados relacionados.
Ler dados relacionados – 6 de 8

Neste tutorial, os dados relacionados são lidos e exibidos. Dados relacionados são dados que o EF Core carrega
nas propriedades de navegação.
Caso tenha problemas que não consiga resolver, baixe ou exiba o aplicativo concluído. Instruções de download.
As seguintes ilustrações mostram as páginas concluídas para este tutorial:
Carregamento adiantado, explícito e lento de dados relacionados
Há várias maneiras pelas quais o EF Core pode carregar dados relacionados nas propriedades de navegação de
uma entidade:
Carregamento adiantado. O carregamento adiantado é quando uma consulta para um tipo de entidade
também carrega entidades relacionadas. Quando a entidade é lida, seus dados relacionados são
recuperados. Normalmente, isso resulta em uma única consulta de junção que recupera todos os dados
necessários. O EF Core emitirá várias consultas para alguns tipos de carregamento adiantado. A emissão
de várias consultas pode ser mais eficiente do que era o caso para algumas consultas no EF6 quando havia
uma única consulta. O carregamento adiantado é especificado com os métodos Include e ThenInclude .
O carregamento adiantado envia várias consultas quando a navegação de coleção é incluída:

Uma consulta para a consulta principal
Uma consulta para cada "borda" de coleção na árvore de carregamento.
Separe consultas com Load : os dados podem ser recuperados em consultas separadas e o EF Core
"corrige" as propriedades de navegação. "Correção" significa que o EF Core popula automaticamente as
propriedades de navegação. A separação de consultas com Load é mais parecida com o carregamento
explícito do que com o carregamento adiantado.
Observação: o EF Core corrige automaticamente as propriedades de navegação para outras entidades que
foram carregadas anteriormente na instância do contexto. Mesmo se os dados de uma propriedade de
navegação não foram incluídos de forma explícita, a propriedade ainda pode ser populada se algumas ou
todas as entidades relacionadas foram carregadas anteriormente.
Carregamento explícito. Quando a entidade é lida pela primeira vez, os dados relacionados não são
recuperados. Um código precisa ser escrito para recuperar os dados relacionados quando eles forem
necessários. O carregamento explícito com consultas separadas resulta no envio de várias consultas ao BD.
Com o carregamento explícito, o código especifica as propriedades de navegação a serem carregadas. Use
o método Load para fazer o carregamento explícito. Por exemplo:
Carregamento lento. O carregamento lento foi adicionado ao EF Core na versão 2.1. Quando a entidade é
lida pela primeira vez, os dados relacionados não são recuperados. Na primeira vez que uma propriedade
de navegação é acessada, os dados necessários para essa propriedade de navegação são recuperados
automaticamente. Uma consulta é enviada para o BD sempre que uma propriedade de navegação é
acessada pela primeira vez.
O operador Select carrega somente os dados relacionados necessários.
Criar uma página Course que exibe o nome do departamento

A entidade Course inclui uma propriedade de navegação que contém a entidade Department . A entidade
Department contém o departamento ao qual o curso é atribuído.
Para exibir o nome do departamento atribuído em uma lista de cursos:
Obtenha a propriedade Name da entidade Department .
A entidade Department é obtida da propriedade de navegação Course.Department .
Gerar o modelo Curso por scaffolding

Visual Studio
CLI do .NET Core
Siga as instruções em Gere um modelo de aluno por scaffold e use Course para a classe de modelo.
O comando anterior gera o modelo Course por scaffolding. Abra o projeto no Visual Studio.
Abra Pages/Courses/Index.cshtml.cs e examine o método OnGetAsync . O mecanismo de scaffolding especificou o
carregamento adiantado para a propriedade de navegação Department . O método Include especifica o
carregamento adiantado.
Execute o aplicativo e selecione o link Cursos. A coluna de departamento exibe a DepartmentID , que não é útil.

{
Course = await _context.Courses
.Include(c => c.Department)
.AsNoTracking()
.ToListAsync();
}
O código anterior adiciona AsNoTracking . AsNoTracking melhora o desempenho porque as entidades retornadas
não são controladas. As entidades não são controladas porque elas não são atualizadas no contexto atual.
Atualize Pages/Courses/Index.cshtml com a seguinte marcação realçada:
@page
@model ContosoUniversity.Pages.Courses.IndexModel
@{
ViewData["Title"] = "Courses";
}
<h2>Courses</h2>
<p>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Course[0].CourseID)
</th>
<th>
@Html.DisplayNameFor(model => model.Course[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Course[0].Credits)
</th>
<th>
@Html.DisplayNameFor(model => model.Course[0].Department)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Course)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.CourseID)
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.Credits)
</td>
<td>
@Html.DisplayFor(modelItem => item.Department.Name)
</td>
<td>
<a asp-page="./Edit" asp-route-id="@item.CourseID">Edit</a> |
<a asp-page="./Details" asp-route-id="@item.CourseID">Details</a> |
<a asp-page="./Delete" asp-route-id="@item.CourseID">Delete</a>
</td>
</tr>
}
</tbody>
</table>
As seguintes alterações foram feitas na biblioteca gerada por código em scaffolding:

Alterou o cabeçalho de Índice para Cursos.
Adicionou uma coluna Número que mostra o valor da propriedade CourseID . Por padrão, as chaves
primárias não são geradas por scaffolding porque normalmente não têm sentido para os usuários finais.
No entanto, nesse caso, a chave primária é significativa.
Alterou a coluna Departamento para que ela exiba o nome de departamento. O código exibe a
propriedade Name da entidade Department que é carregada na propriedade de navegação Department :
Execute o aplicativo e selecione a guia Cursos para ver a lista com nomes de departamentos.
Carregando dados relacionados com Select

O método OnGetAsync carrega dados relacionados com o método Include :

{
.AsNoTracking()
.ToListAsync();
}
O operador Select carrega somente os dados relacionados necessários. Para itens únicos, como o
Department.Name, ele usa um SQL INNER JOIN. Para coleções, ele usa outro acesso ao banco de dados, assim
como o operador Include em coleções.
O seguinte código carrega dados relacionados com o método Select :
public IList<CourseViewModel> CourseVM { get; set; }

{
CourseVM = await _context.Courses
.Select(p => new CourseViewModel
{
CourseID = p.CourseID,
Title = p.Title,
Credits = p.Credits,
DepartmentName = p.Department.Name
}).ToListAsync();
}
O CourseViewModel :
public class CourseViewModel
{
public string DepartmentName { get; set; }
}
Consulte IndexSelect.cshtml e IndexSelect.cshtml.cs para obter um exemplo completo.
Criar uma página Instrutores que mostra Cursos e Registros

Nesta seção, a página Instrutores é criada.
Essa página lê e exibe dados relacionados das seguintes maneiras:
A lista de instrutores exibe dados relacionados da entidade OfficeAssignment (Office na imagem anterior). As
entidades Instructor e OfficeAssignment estão em uma relação um para zero ou um. O carregamento
adiantado é usado para as entidades OfficeAssignment . O carregamento adiantado costuma ser mais eficiente
quando os dados relacionados precisam ser exibidos. Nesse caso, as atribuições de escritório para os
instrutores são exibidas.
Quando o usuário seleciona um instrutor (Pedro na imagem anterior), as entidades Course relacionadas são
exibidas. As entidades Instructor e Course estão em uma relação muitos para muitos. O carregamento
adiantado é usado para entidades Course e suas entidades Department relacionadas. Nesse caso, consultas
separadas podem ser mais eficientes porque somente os cursos para o instrutor selecionado são necessários.
Este exemplo mostra como usar o carregamento adiantado para propriedades de navegação em entidades que
estão nas propriedades de navegação.
Quando o usuário seleciona um curso (Química na imagem anterior), os dados relacionados da entidade
Enrollments são exibidos. Na imagem anterior, o nome do aluno e a nota são exibidos. As entidades Course e
Enrollment estão em uma relação um -para-muitos.
Criar um modelo de exibição para a exibição Índice de Instrutor

A página Instrutores mostra dados de três tabelas diferentes. É criado um modelo de exibição que inclui as três
entidades que representam as três tabelas.
Na pasta SchoolViewModels, crie InstructorIndexData.cs com o seguinte código:
using System;
using System.Linq;
{
public class InstructorIndexData
{
public IEnumerable<Instructor> Instructors { get; set; }
public IEnumerable<Course> Courses { get; set; }
public IEnumerable<Enrollment> Enrollments { get; set; }
}
}
Gerar o modelo Instrutor por scaffolding

Visual Studio
CLI do .NET Core
Siga as instruções em Gere um modelo de aluno por scaffold e use Instructor para a classe de modelo.
O comando anterior gera o modelo Instructor por scaffolding. Execute o aplicativo e navegue para a página
Instrutores.
Substitua Pages/Instructors/Index.cshtml.cs pelo seguinte código:
using ContosoUniversity.Models.SchoolViewModels; // Add VM
using System.Linq;
namespace ContosoUniversity.Pages.Instructors
{
{
private readonly ContosoUniversity.Data.SchoolContext _context;
public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}
public InstructorIndexData Instructor { get; set; }

public async Task OnGetAsync(int? id)

{
Instructor = new InstructorIndexData();
Instructor.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();
if (id != null)
{
InstructorID = id.Value;
}
}
}
}
O método OnGetAsync aceita dados de rota opcionais para a ID do instrutor selecionado.

Examine a consulta no arquivo Pages/Instructors/Index.cshtml:

.AsNoTracking()
.ToListAsync();
A consulta tem duas inclusões:

OfficeAssignment : exibido na exibição de instrutores.
CourseAssignments : que exibe os cursos ministrados.
Atualizar a página Índice de instrutores

Atualize Pages/Instructors/Index.cshtml com a seguinte marcação:
@page "{id:int?}"
@model ContosoUniversity.Pages.Instructors.IndexModel
@{
ViewData["Title"] = "Instructors";
}
<h2>Instructors</h2>
<p>
</p>
<thead>
<tr>
<th>Last Name</th>
<th>First Name</th>
<th>Hire Date</th>
<th>Office</th>
<th>Courses</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Instructor.Instructors)
{
string selectedRow = "";
if (item.ID == Model.InstructorID)
{
selectedRow = "success";
}
<tr class="@selectedRow">
<td>
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.HireDate)
</td>
<td>
@if (item.OfficeAssignment != null)
{
@item.OfficeAssignment.Location
}
</td>
<td>
@{
foreach (var course in item.CourseAssignments)
{
@course.Course.CourseID @: @course.Course.Title <br />
}
}
</td>
<td>
<a asp-page="./Index" asp-route-id="@item.ID">Select</a> |
</td>
</tr>
}
</tbody>
</table>
A marcação anterior faz as seguintes alterações:
Atualiza a diretiva page de @page para @page "{id:int?}" . "{id:int?}" é um modelo de rota. O modelo
de rota altera cadeias de consulta de inteiro na URL para dados de rota. Por exemplo, clicar no link
Selecionar de um o instrutor apenas com a diretiva @page produz uma URL semelhante à seguinte:
http://localhost:1234/Instructors?id=2
Quando a diretiva de página é @page "{id:int?}" , a URL anterior é:

http://localhost:1234/Instructors/2
O título de página é Instrutores.

Adicionou uma coluna Office que exibe item.OfficeAssignment.Location somente se
item.OfficeAssignment não é nulo. Como essa é uma relação um para zero ou um, pode não haver uma
entidade OfficeAssignment relacionada.

{
}
Adicionou uma coluna Courses que exibe os cursos ministrados por cada instrutor. Consulte Transição de
linha explícita com @: para obter mais informações sobre essa sintaxe Razor.
Adicionou um código que adiciona class="success" dinamicamente ao elemento tr do instrutor
selecionado. Isso define uma cor da tela de fundo para a linha selecionada usando uma classe Bootstrap.

if (item.CourseID == Model.CourseID)
{
}
Adicionou um novo hiperlink rotulado Selecionar. Este link envia a ID do instrutor selecionado para o
método Index e define uma cor da tela de fundo.
<a asp-action="Index" asp-route-id="@item.ID">Select</a> |
Execute o aplicativo e selecione a guia Instrutores. A página exibe o Location (escritório) da entidade
OfficeAssignment relacionada. Se OfficeAssignment é nulo, uma célula de tabela vazia é exibida.
Clique no link Selecionar. O estilo de linha é alterado.
Adicionar cursos ministrados pelo instrutor selecionado
Atualize o método OnGetAsync em Pages/Instructors/Index.cshtml.cs com o seguinte código:
public async Task OnGetAsync(int? id, int? courseID)

{
.ThenInclude(i => i.Department)
.AsNoTracking()
.ToListAsync();
if (id != null)
{
Instructor instructor = Instructor.Instructors.Where(
i => i.ID == id.Value).Single();
Instructor.Courses = instructor.CourseAssignments.Select(s => s.Course);
}
if (courseID != null)
{
CourseID = courseID.Value;
Instructor.Enrollments = Instructor.Courses.Where(
x => x.CourseID == courseID).Single().Enrollments;
}
}
Adicione public int CourseID { get; set; }

{
public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}
public InstructorIndexData Instructor { get; set; }


{
.AsNoTracking()
.ToListAsync();
if (id != null)
{
}
{
}
}
Examine a consulta atualizada:

.AsNoTracking()
.ToListAsync();
A consulta anterior adiciona as entidades Department .

O código a seguir é executado quando o instrutor é selecionado ( id != null ). O instrutor selecionado é
recuperado da lista de instrutores no modelo de exibição. Em seguida, a propriedade Courses do modelo de
exibição é carregada com as entidades Course da propriedade de navegação CourseAssignments desse instrutor.
if (id != null)
{
}
O método Where retorna uma coleção. No método Where anterior, uma única entidade Instructor é retornada.
O método Single converte a coleção em uma única entidade Instructor . A entidade Instructor fornece acesso
à propriedade CourseAssignments . CourseAssignments fornece acesso às entidades Course relacionadas.
O método Single é usado em uma coleção quando a coleção tem apenas um item. O método Single gera uma
exceção se a coleção está vazia ou se há mais de um item. Uma alternativa é SingleOrDefault , que retorna um
valor padrão (nulo, nesse caso) se a coleção está vazia. O uso de SingleOrDefault é uma coleção vazia:
Resulta em uma exceção (da tentativa de encontrar uma propriedade Courses em uma referência nula).
A mensagem de exceção indica menos claramente a causa do problema.
O seguinte código popula a propriedade Enrollments do modelo de exibição quando um curso é selecionado:
{
}
Adicione a seguinte marcação ao final do Razor Page Pages/Courses/Index.cshtml:

</td>
</tr>
}
</tbody>
</table>
@if (Model.Instructor.Courses != null)

{
<h3>Courses Taught by Selected Instructor</h3>
<tr>
<th></th>
<th>Number</th>
<th>Title</th>
<th>Department</th>
</tr>
@foreach (var item in Model.Instructor.Courses)

{
if (item.CourseID == Model.CourseID)
{
}
<td>
<a asp-page="./Index" asp-route-courseID="@item.CourseID">Select</a>
</td>
<td>
@item.CourseID
</td>
<td>
@item.Title
</td>
<td>
@item.Department.Name
</td>
</tr>
}
</table>
}
A marcação anterior exibe uma lista de cursos relacionados a um instrutor quando um instrutor é selecionado.
Teste o aplicativo. Clique em um link Selecionar na página Instrutores.
Mostrar dados de alunos
Nesta seção, o aplicativo é atualizado para mostrar os dados de alunos de um curso selecionado.
Atualize a consulta no método OnGetAsync em Pages/Instructors/Index.cshtml.cs com o seguinte código:

.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.ToListAsync();
Atualize Pages/Instructors/Index.cshtml. Adicione a seguinte marcação ao final do arquivo:

@if (Model.Instructor.Enrollments != null)
{
<h3>
Students Enrolled in Selected Course
</h3>
<tr>
<th>Name</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.Instructor.Enrollments)
{
<tr>
<td>
@item.Student.FullName
</td>
<td>
</td>
</tr>
}
</table>
}
A marcação anterior exibe uma lista dos alunos registrados no curso selecionado.
Atualize a página e selecione um instrutor. Selecione um curso para ver a lista de alunos registrados e suas notas.
Usando Single
O método Single pode passar a condição Where em vez de chamar o método Where separadamente:
{

.AsNoTracking()
.ToListAsync();
if (id != null)
{
Instructor instructor = Instructor.Instructors.Single(
i => i.ID == id.Value);
Instructor.Courses = instructor.CourseAssignments.Select(
s => s.Course);
}
{
Instructor.Enrollments = Instructor.Courses.Single(
x => x.CourseID == courseID).Enrollments;
}
}
A abordagem Single anterior não oferece nenhum benefício em relação ao uso de Where . Alguns
desenvolvedores preferem o estilo de abordagem Single .
Carregamento explícito
O código atual especifica o carregamento adiantado para Enrollments e Students :

.AsNoTracking()
.ToListAsync();
Suponha que os usuários raramente desejem ver registros em um curso. Nesse caso, uma otimização será
carregar apenas os dados de registro se eles forem solicitados. Nesta seção, o OnGetAsync é atualizado para usar
o carregamento explícito de Enrollments e Students .
Atualize o OnGetAsync com o seguinte código:
{
//.Include(i => i.CourseAssignments)
// .ThenInclude(i => i.Course)
// .ThenInclude(i => i.Enrollments)
// .ThenInclude(i => i.Student)
// .AsNoTracking()
.ToListAsync();
if (id != null)
{
}
{
var selectedCourse = Instructor.Courses.Where(x => x.CourseID == courseID).Single();
await _context.Entry(selectedCourse).Collection(x => x.Enrollments).LoadAsync();
foreach (Enrollment enrollment in selectedCourse.Enrollments)
{
await _context.Entry(enrollment).Reference(x => x.Student).LoadAsync();
}
Instructor.Enrollments = selectedCourse.Enrollments;
}
}
O código anterior remove as chamadas do método ThenInclude para dados de registro e de alunos. Se um curso
é selecionado, o código realçado recupera:
As entidades Enrollment para o curso selecionado.
As entidades Student para cada Enrollment .
Observe que o código anterior comenta .AsNoTracking() . As propriedades de navegação apenas podem ser
carregadas de forma explícita para entidades controladas.
Teste o aplicativo. De uma perspectiva dos usuários, o aplicativo se comporta de forma idêntica à versão anterior.
O próximo tutorial mostra como atualizar os dados relacionados.
Atualizar dados relacionados – 7 de 8

Este tutorial demonstra como atualizar dados relacionados. Caso tenha problemas que não consiga resolver, baixe
ou exiba o aplicativo concluído. Instruções de download.
As ilustrações a seguir mostram algumas das páginas concluídas.
Examine e teste as páginas de cursos Criar e Editar. Crie um novo curso. O departamento é selecionado por sua
chave primária (um inteiro), não pelo nome. Edite o novo curso. Quando concluir o teste, exclua o novo curso.
Criar uma classe base para compartilhar um código comum

As páginas Cursos/Criar e Cursos/Editar precisam de uma lista de nomes de departamentos. Crie a classe base
Pages/Courses/DepartmentNamePageModel.cshtml.cs para as páginas Criar e Editar:
using System.Linq;
namespace ContosoUniversity.Pages.Courses
{
public class DepartmentNamePageModel : PageModel
{
public SelectList DepartmentNameSL { get; set; }
public void PopulateDepartmentsDropDownList(SchoolContext _context,

object selectedDepartment = null)
{
var departmentsQuery = from d in _context.Departments
orderby d.Name // Sort by name.
select d;
DepartmentNameSL = new SelectList(departmentsQuery.AsNoTracking(),

"DepartmentID", "Name", selectedDepartment);
}
}
}
O código anterior cria uma SelectList para conter a lista de nomes de departamentos. Se selectedDepartment for
especificado, esse departamento estará selecionado na SelectList .
As classes de modelo da página Criar e Editar serão derivadas de DepartmentNamePageModel .
Personalizar as páginas Courses

Quando uma nova entidade de curso é criada, ela precisa ter uma relação com um departamento existente. Para
adicionar um departamento durante a criação de um curso, a classe base para Create e Edit contém uma lista
suspensa para seleção do departamento. A lista suspensa define a propriedade Course.DepartmentID de FK (chave
estrangeira). O EF Core usa a Course.DepartmentID FK para carregar a propriedade de navegação Department .
Atualize o modelo da página Criar com o seguinte código:
{
public class CreateModel : DepartmentNamePageModel
{
public CreateModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

{
PopulateDepartmentsDropDownList(_context);
return Page();
}
[BindProperty]

{
{
return Page();
}
var emptyCourse = new Course();
if (await TryUpdateModelAsync<Course>(
emptyCourse,
"course", // Prefix for form value.
s => s.CourseID, s => s.DepartmentID, s => s.Title, s => s.Credits))
{
_context.Courses.Add(emptyCourse);
}
// Select DepartmentID if TryUpdateModelAsync fails.

PopulateDepartmentsDropDownList(_context, emptyCourse.DepartmentID);
return Page();
}
}
}
O código anterior:
Deriva de DepartmentNamePageModel .
Usa TryUpdateModelAsync para impedir o excesso de postagem.
Substitui ViewData["DepartmentID"] por DepartmentNameSL (da classe base).
ViewData["DepartmentID"] é substituído pelo DepartmentNameSL fortemente tipado. Modelos fortemente tipados

são preferíveis aos fracamente tipados. Para obter mais informações, consulte Dados fracamente tipados
(ViewData e ViewBag).
Atualizar a página Criar Cursos
Atualize Pages/Courses/Create.cshtml com a seguinte marcação:
@page
@model ContosoUniversity.Pages.Courses.CreateModel
@{
ViewData["Title"] = "Create Course";
}
<h2>Create</h2>
<h4>Course</h4>
<hr />
<div class="row">
<label asp-for="Course.CourseID" class="control-label"></label>
<input asp-for="Course.CourseID" class="form-control" />
<span asp-validation-for="Course.CourseID" class="text-danger"></span>
</div>
<label asp-for="Course.Title" class="control-label"></label>
<input asp-for="Course.Title" class="form-control" />
<span asp-validation-for="Course.Title" class="text-danger"></span>
</div>
<label asp-for="Course.Credits" class="control-label"></label>
<input asp-for="Course.Credits" class="form-control" />
<span asp-validation-for="Course.Credits" class="text-danger"></span>
</div>
<label asp-for="Course.Department" class="control-label"></label>
<select asp-for="Course.DepartmentID" class="form-control"
asp-items="@Model.DepartmentNameSL">
<option value="">-- Select Department --</option>
</select>
<span asp-validation-for="Course.DepartmentID" class="text-danger" />
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}

Altera a legenda de DepartmentID para Departamento.
Substitui "ViewBag.DepartmentID" por DepartmentNameSL (da classe base).
Adiciona a opção "Selecionar Departamento". Essa alteração renderiza "Selecionar Departamento", em vez do
departamento primeiro.
Adiciona uma mensagem de validação quando o departamento não está selecionado.
A Página do Razor usa a opção Selecionar Auxiliar de Marcação:
asp-items="@Model.DepartmentNameSL">
</select>
<span asp-validation-for="Course.DepartmentID" class="text-danger" />
</div>
Teste a página Criar. A página Criar exibe o nome do departamento em vez de a ID do departamento.
Atualize a página Editar Cursos.
Atualize o modelo de página de edição com o seguinte código:
{
public class EditModel : DepartmentNamePageModel
{
public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}

.Include(c => c.Department).FirstOrDefaultAsync(m => m.CourseID == id);
if (Course == null)
{
return NotFound();
}
// Select current DepartmentID.

PopulateDepartmentsDropDownList(_context,Course.DepartmentID);
return Page();
}

{
{
return Page();
}
var courseToUpdate = await _context.Courses.FindAsync(id);
if (await TryUpdateModelAsync<Course>(
courseToUpdate,
"course", // Prefix for form value.
c => c.Credits, c => c.DepartmentID, c => c.Title))
{
}
// Select DepartmentID if TryUpdateModelAsync fails.

PopulateDepartmentsDropDownList(_context, courseToUpdate.DepartmentID);
return Page();
}
}
}
As alterações são semelhantes às feitas no modelo da página Criar. No código anterior,

PopulateDepartmentsDropDownList passa a ID do departamento, que seleciona o departamento especificado na lista
suspensa.
Atualize Pages/Courses/Edit.cshtml com a seguinte marcação:
@page
@model ContosoUniversity.Pages.Courses.EditModel
@{
}
<h2>Edit</h2>
<h4>Course</h4>
<hr />
<div class="row">
<input type="hidden" asp-for="Course.CourseID" />
<label asp-for="Course.CourseID" class="control-label"></label>
<div>@Html.DisplayFor(model => model.Course.CourseID)</div>
</div>
<label asp-for="Course.Title" class="control-label"></label>
<input asp-for="Course.Title" class="form-control" />
<span asp-validation-for="Course.Title" class="text-danger"></span>
</div>
<label asp-for="Course.Credits" class="control-label"></label>
<input asp-for="Course.Credits" class="form-control" />
<span asp-validation-for="Course.Credits" class="text-danger"></span>
</div>
asp-items="@Model.DepartmentNameSL"></select>
<span asp-validation-for="Course.DepartmentID" class="text-danger"></span>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}

Exibe a ID do curso. Geralmente, a PK (chave primária) de uma entidade não é exibida. Em geral, PKs não têm
sentido para os usuários. Nesse caso, o PK é o número do curso.
Altera a legenda de DepartmentID para Departamento.
Substitui "ViewBag.DepartmentID" por DepartmentNameSL (da classe base).
A página contém um campo oculto ( <input type="hidden"> ) para o número do curso. A adição de um auxiliar de
marcação <label> com asp-for="Course.CourseID" não elimina a necessidade do campo oculto.
<input type="hidden"> é necessário para que o número seja incluído nos dados postados quando o usuário clicar
em Salvar.
Teste o código atualizado. Crie, edite e exclua um curso.
Adicionar AsNoTracking aos modelos de página Detalhes e Excluir

AsNoTracking pode melhorar o desempenho quando o acompanhamento não é necessário. Adicione
AsNoTracking ao modelo de página Excluir e Detalhes. O seguinte código mostra o modelo de página Excluir
atualizado:

{
public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
.FirstOrDefaultAsync(m => m.CourseID == id);
if (Course == null)
{
return NotFound();
}
return Page();
}

{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
if (Course != null)
{
_context.Courses.Remove(Course);
}
}
}
Atualize o método OnGetAsync no arquivo Pages/Courses/Details.cshtml.cs:

{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
if (Course == null)
{
return NotFound();
}
return Page();
}
Modificar as páginas Excluir e Detalhes

Atualize a página Excluir do Razor com a seguinte marcação:
@page
@model ContosoUniversity.Pages.Courses.DeleteModel
@{
}
<h2>Delete</h2>

<div>
<h4>Course</h4>
<hr />
<dt>
@Html.DisplayNameFor(model => model.Course.CourseID)
</dt>
<dd>
@Html.DisplayFor(model => model.Course.CourseID)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Course.Title)
</dt>
<dd>
@Html.DisplayFor(model => model.Course.Title)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Course.Credits)
</dt>
<dd>
@Html.DisplayFor(model => model.Course.Credits)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Course.Department)
</dt>
<dd>
@Html.DisplayFor(model => model.Course.Department.DepartmentID)
</dd>
</dl>
<input type="hidden" asp-for="Course.CourseID" />
</form>
</div>
Faça as mesmas alterações na página Detalhes.

Testar as páginas Curso
Teste as páginas Criar, Editar, Detalhes e Excluir.
Atualizar as páginas do instrutor

As seções a seguir atualizam as páginas do instrutor.
Adicionar local do escritório
Ao editar um registro de instrutor, é recomendável atualizar a atribuição de escritório do instrutor.A entidade
Instructor tem uma relação um para zero ou um com a entidade OfficeAssignment . O código do instrutor
precisa manipular:
Se o usuário limpar a atribuição de escritório, exclua a entidade OfficeAssignment .
Se o usuário inserir uma atribuição de escritório e ela estava vazia, crie uma nova entidade OfficeAssignment .
Se o usuário alterar a atribuição de escritório, atualize a entidade OfficeAssignment .
Atualize o modelo de página Editar Instrutores com o seguinte código:

{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
Instructor = await _context.Instructors

.AsNoTracking()
if (Instructor == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
var instructorToUpdate = await _context.Instructors

.FirstOrDefaultAsync(s => s.ID == id);
if (await TryUpdateModelAsync<Instructor>(
instructorToUpdate,
"Instructor",
i => i.FirstMidName, i => i.LastName,
i => i.HireDate, i => i.OfficeAssignment))
{
if (String.IsNullOrWhiteSpace(
instructorToUpdate.OfficeAssignment?.Location))
{
instructorToUpdate.OfficeAssignment = null;
}
}
}
}
O código anterior:
Obtém a entidade Instructor atual do banco de dados usando o carregamento adiantado para a propriedade
de navegação OfficeAssignment .
Atualiza a entidade Instructor recuperada com valores do associador de modelos. TryUpdateModel impede o
excesso de postagem.
Se o local do escritório estiver em branco, Instructor.OfficeAssignment será definido como nulo. Quando
Instructor.OfficeAssignment é nulo, a linha relacionada na tabela OfficeAssignment é excluída.
Atualizar a página Editar Instrutor

Atualize Pages/Instructors/Edit.cshtml com o local do escritório:
@page
@model ContosoUniversity.Pages.Instructors.EditModel
@{
}
<h2>Edit</h2>
<h4>Instructor</h4>
<hr />
<div class="row">
<input type="hidden" asp-for="Instructor.ID" />
<label asp-for="Instructor.LastName" class="control-label"></label>
<input asp-for="Instructor.LastName" class="form-control" />
<span asp-validation-for="Instructor.LastName" class="text-danger"></span>
</div>
<label asp-for="Instructor.FirstMidName" class="control-label"></label>
<input asp-for="Instructor.FirstMidName" class="form-control" />
<span asp-validation-for="Instructor.FirstMidName" class="text-danger"></span>
</div>
<label asp-for="Instructor.HireDate" class="control-label"></label>
<input asp-for="Instructor.HireDate" class="form-control" />
<span asp-validation-for="Instructor.HireDate" class="text-danger"></span>
</div>
<label asp-for="Instructor.OfficeAssignment.Location" class="control-label"></label>
<input asp-for="Instructor.OfficeAssignment.Location" class="form-control" />
<span asp-validation-for="Instructor.OfficeAssignment.Location" class="text-danger" />
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
Verifique se você pode alterar o local do escritório de um instrutor.
Adicionar atribuições de Curso à página Editar Instrutor

Os instrutores podem ministrar a quantidade de cursos que desejarem. Nesta seção, você adiciona a capacidade
de alterar as atribuições de curso. A seguinte imagem mostra a página Editar Instrutor atualizada:
Course e Instructor têm uma relação muitos para muitos. Para adicionar e remover relações, adicione e remova
entidades do conjunto de entidades de junção CourseAssignments .
As caixas de seleção permitem alterações em cursos aos quais um instrutor é atribuído. Uma caixa de seleção é
exibida para cada curso no banco de dados. Os cursos aos quais o instrutor é atribuído estão marcados. O usuário
pode marcar ou desmarcar as caixas de seleção para alterar as atribuições de curso. Se a quantidade de cursos for
muito maior:
Provavelmente, você usará outra interface do usuário para exibir os cursos.
O método de manipulação de uma entidade de junção para criar ou excluir relações não será alterado.
Adicionar classes para dar suporte às páginas Criar e Editar Instrutor
Crie SchoolViewModels/AssignedCourseData.cs com o seguinte código:
{
public class AssignedCourseData
{
public bool Assigned { get; set; }
}
}
A classe AssignedCourseData contém dados para criar as caixas de seleção para os cursos atribuídos por um
instrutor.
Crie a classe base Pages/Instructors/InstructorCoursesPageModel.cshtml.cs:
using System.Linq;
{
public class InstructorCoursesPageModel : PageModel
{
public List<AssignedCourseData> AssignedCourseDataList;
public void PopulateAssignedCourseData(SchoolContext context,

Instructor instructor)
{
var allCourses = context.Courses;
var instructorCourses = new HashSet<int>(
instructor.CourseAssignments.Select(c => c.CourseID));
AssignedCourseDataList = new List<AssignedCourseData>();
foreach (var course in allCourses)
{
AssignedCourseDataList.Add(new AssignedCourseData
{
CourseID = course.CourseID,
Title = course.Title,
Assigned = instructorCourses.Contains(course.CourseID)
});
}
}
public void UpdateInstructorCourses(SchoolContext context,

string[] selectedCourses, Instructor instructorToUpdate)
{
if (selectedCourses == null)
{
instructorToUpdate.CourseAssignments = new List<CourseAssignment>();
return;
}
var selectedCoursesHS = new HashSet<string>(selectedCourses);

var instructorCourses = new HashSet<int>
(instructorToUpdate.CourseAssignments.Select(c => c.Course.CourseID));
foreach (var course in context.Courses)
{
if (selectedCoursesHS.Contains(course.CourseID.ToString()))
{
if (!instructorCourses.Contains(course.CourseID))
{
instructorToUpdate.CourseAssignments.Add(
new CourseAssignment
{
InstructorID = instructorToUpdate.ID,
CourseID = course.CourseID
});
}
}
else
{
if (instructorCourses.Contains(course.CourseID))
{
CourseAssignment courseToRemove
CourseAssignment courseToRemove
= instructorToUpdate
.CourseAssignments
.SingleOrDefault(i => i.CourseID == course.CourseID);
context.Remove(courseToRemove);
}
}
}
}
}
}
A InstructorCoursesPageModel é a classe base que será usada para os modelos de página Editar e Criar.
PopulateAssignedCourseData lê todas as entidades Course para popular AssignedCourseDataList . Para cada curso,
o código define a CourseID , o título e se o instrutor está ou não atribuído ao curso. Um HashSet é usado para
criar pesquisas eficientes.
Modelo de página Editar Instrutor
Atualize o modelo de página Editar Instrutor com o seguinte código:
public class EditModel : InstructorCoursesPageModel
{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
Instructor = await _context.Instructors

.Include(i => i.CourseAssignments).ThenInclude(i => i.Course)
.AsNoTracking()
{
return NotFound();
}
PopulateAssignedCourseData(_context, Instructor);
return Page();
}
public async Task<IActionResult> OnPostAsync(int? id, string[] selectedCourses)

{
{
return Page();
}

.FirstOrDefaultAsync(s => s.ID == id);
instructorToUpdate,
"Instructor",
{
if (String.IsNullOrWhiteSpace(
instructorToUpdate.OfficeAssignment?.Location))
{
}
UpdateInstructorCourses(_context, selectedCourses, instructorToUpdate);
}
UpdateInstructorCourses(_context, selectedCourses, instructorToUpdate);
PopulateAssignedCourseData(_context, instructorToUpdate);
return Page();
}
}
O código anterior manipula as alterações de atribuição de escritório.
Atualize a Exibição do Razor do instrutor:
@page
@model ContosoUniversity.Pages.Instructors.EditModel
@{
}
<h2>Edit</h2>
<h4>Instructor</h4>
<hr />
<div class="row">
<input type="hidden" asp-for="Instructor.ID" />
</div>
</div>
</div>
</div>
<table>
<tr>
@{
int cnt = 0;
foreach (var course in Model.AssignedCourseDataList)

{
if (cnt++ % 3 == 0)
{
@:</tr><tr>
}
@:<td>
<input type="checkbox"
name="selectedCourses"
value="@course.CourseID"
@(Html.Raw(course.Assigned ? "checked=\"checked\"" : "")) />
@course.CourseID @: @course.Title
@:</td>
}
@:</tr>
}
</table>
</div>
</div>
</div>
</form>
</div>
</div>
</div>
<div>
</div>
@section Scripts {
}
NOTE
Quando você cola o código no Visual Studio, as quebras de linha são alteradas de uma forma que divide o código. Pressione
Ctrl+Z uma vez para desfazer a formatação automática. A tecla de atalho Ctrl+Z corrige as quebras de linha para que elas se
pareçam com o que você vê aqui. O recuo não precisa ser perfeito, mas cada uma das linhas @</tr><tr> , @:<td> ,
@:</td> e @:</tr> precisa estar em uma única linha, conforme mostrado. Com o bloco de novo código selecionado,
pressione Tab três vezes para alinhar o novo código com o código existente. Vote ou examine o status deste bug com este
link.
Esse código anterior cria uma tabela HTML que contém três colunas. Cada coluna tem uma caixa de seleção e
uma legenda que contém o número e o título do curso. Todas as caixas de seleção têm o mesmo nome
("selectedCourses"). O uso do mesmo nome instrui o associador de modelos a tratá-las como um grupo. O
atributo de valor de cada caixa de seleção é definido como CourseID . Quando a página é postada, o associador de
modelos passa uma matriz que consiste nos valores CourseID para apenas as caixas de seleção marcadas.
Quando as caixas de seleção são inicialmente renderizadas, os cursos atribuídos ao instrutor têm atributos
marcados.
Execute o aplicativo e teste a página Editar Instrutor atualizada. Altere algumas atribuições de curso. As alterações
são refletidas na página Índice.
Observação: a abordagem usada aqui para editar os dados de curso do instrutor funciona bem quando há uma
quantidade limitada de cursos. Para coleções muito maiores, uma interface do usuário e um método de
atualização diferentes são mais utilizáveis e eficientes.
Atualizar a página Criar Instrutor
Atualize o modelo de página Criar instrutor com o seguinte código:
{
public class CreateModel : InstructorCoursesPageModel
{
public CreateModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

{
var instructor = new Instructor();
instructor.CourseAssignments = new List<CourseAssignment>();
// Provides an empty collection for the foreach loop

// foreach (var course in Model.AssignedCourseDataList)
// in the Create Razor page.
PopulateAssignedCourseData(_context, instructor);
return Page();
}
[BindProperty]
public async Task<IActionResult> OnPostAsync(string[] selectedCourses)

{
{
return Page();
}
var newInstructor = new Instructor();

if (selectedCourses != null)
{
newInstructor.CourseAssignments = new List<CourseAssignment>();
foreach (var course in selectedCourses)
{
var courseToAdd = new CourseAssignment
{
CourseID = int.Parse(course)
};
newInstructor.CourseAssignments.Add(courseToAdd);
}
}
newInstructor,
"Instructor",
{
_context.Instructors.Add(newInstructor);
}
PopulateAssignedCourseData(_context, newInstructor);
return Page();
}
}
}
O código anterior é semelhante ao código de Pages/Instructors/Edit.cshtml.cs.

Atualize a página Criar instrutor do Razor com a seguinte marcação:
@page
@model ContosoUniversity.Pages.Instructors.CreateModel
@{
}
<h2>Create</h2>
<h4>Instructor</h4>
<hr />
<div class="row">
</div>
</div>
</div>
</div>
<table>
<tr>
@{
int cnt = 0;
foreach (var course in Model.AssignedCourseDataList)

{
if (cnt++ % 3 == 0)
{
@:</tr><tr>
}
@:<td>
@:</td>
}
@:</tr>
}
</table>
</div>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
Teste a página Criar Instrutor.

Atualize o modelo da página Excluir com o seguinte código:
using System.Linq;
{
{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
Instructor = await _context.Instructors.SingleAsync(m => m.ID == id);
{
return NotFound();
}
return Page();
}
public async Task<IActionResult> OnPostAsync(int id)

{
Instructor instructor = await _context.Instructors
.SingleAsync(i => i.ID == id);
var departments = await _context.Departments

.Where(d => d.InstructorID == id)
.ToListAsync();
departments.ForEach(d => d.InstructorID = null);
_context.Instructors.Remove(instructor);
}
}
}
O código anterior faz as seguintes alterações:

Usa o carregamento adiantado para a propriedade de navegação CourseAssignments . CourseAssignments
deve ser incluído ou eles não são excluídos quando o instrutor é excluído. Para evitar a necessidade de lê-
las, configure a exclusão em cascata no banco de dados.
Se o instrutor a ser excluído é atribuído como administrador de qualquer departamento, remove a
atribuição de instrutor desse departamento.
Simultaneidade – 8 de 8
Por Rick Anderson, Tom Dykstra e Jon P Smith

Este tutorial mostra como lidar com conflitos quando os mesmos usuários atualizam uma entidade
simultaneamente. Caso tenha problemas que não consiga resolver, baixe ou exiba o aplicativo concluído.
Instruções de download.
Conflitos de simultaneidade
Um conflito de simultaneidade ocorre quando:
Um usuário navega para a página de edição de uma entidade.
Outro usuário atualiza a mesma entidade antes que a primeira alteração do usuário seja gravada no BD.
Se a detecção de simultaneidade não estiver habilitada, quando ocorrerem atualizações simultâneas:
A última atualização vencerá. Ou seja, os últimos valores de atualização serão salvos no BD.
A primeira das atualizações atuais será perdida.
Simultaneidade otimista
A simultaneidade otimista permite que conflitos de simultaneidade ocorram e, em seguida, responde
adequadamente quando ocorrem. Por exemplo, Alice visita a página Editar Departamento e altera o orçamento
para o departamento de inglês de US$ 350.000,00 para US$ 0,00.
Antes que Alice clique em Salvar, Julio visita a mesma página e altera o campo Data de Início de 1/9/2007 para
1/9/2013.
Alice clica em Salvar primeiro e vê a alteração quando o navegador exibe a página Índice.
Julio clica em Salvar em uma página Editar que ainda mostra um orçamento de US$ 350.000,00. O que
acontece em seguida é determinado pela forma como você lida com conflitos de simultaneidade.
A simultaneidade otimista inclui as seguintes opções:
Controle qual propriedade um usuário modificou e atualize apenas as colunas correspondentes no BD.
No cenário, não haverá perda de dados. Propriedades diferentes foram atualizadas pelos dois usuários.
Na próxima vez que alguém navegar no departamento de inglês, verá as alterações de Alice e Julio. Esse
método de atualização pode reduzir o número de conflitos que podem resultar em perda de dados. Essa
abordagem:
Não poderá evitar a perda de dados se forem feitas alterações concorrentes na mesma propriedade.
Geralmente, não é prática em um aplicativo Web. Ela exige um estado de manutenção significativo
para controlar todos os valores buscados e novos valores. Manter grandes quantidades de estado
pode afetar o desempenho do aplicativo.
Pode aumentar a complexidade do aplicativo comparado à detecção de simultaneidade em uma
entidade.
Você não pode deixar a alteração de Julio substituir a alteração de Alice.
Na próxima vez que alguém navegar pelo departamento de inglês, verá 1/9/2013 e o valor de US$
350.000,00 buscado. Essa abordagem é chamada de um cenário O cliente vence ou O último vence.
(Todos os valores do cliente têm precedência sobre o conteúdo do armazenamento de dados.) Se você
não fizer nenhuma codificação para a manipulação de simultaneidade, o cenário O cliente vence ocorrerá
automaticamente.
Você pode impedir que as alterações de Julio sejam atualizadas no BD. Normalmente, o aplicativo:
Exibe uma mensagem de erro.
Mostra o estado atual dos dados.
Permite ao usuário aplicar as alterações novamente.
Isso é chamado de um cenário O armazenamento vence. (Os valores do armazenamento de dados têm
precedência sobre os valores enviados pelo cliente.) Você implementará o cenário O armazenamento
vence neste tutorial. Esse método garante que nenhuma alteração é substituída sem que um usuário seja
alertado.
Tratamento de simultaneidade
Quando uma propriedade é configurada como um token de simultaneidade:
O EF Core verifica se a propriedade não foi modificada depois que foi buscada. A verificação ocorre quando
SaveChanges ou SaveChangesAsync é chamado.
Se a propriedade tiver sido alterada depois que ela foi buscada, uma DbUpdateConcurrencyException será
gerada.
O BD e o modelo de dados precisam ser configurados para dar suporte à geração de
DbUpdateConcurrencyException .
Detectando conflitos de simultaneidade em uma propriedade

Os conflitos de simultaneidade podem ser detectados no nível do propriedade com o atributo
ConcurrencyCheck. O atributo pode ser aplicado a várias propriedades no modelo. Para obter mais informações,
consulte Data Annotations-ConcurrencyCheck.
O atributo [ConcurrencyCheck] não é usado neste tutorial.
Detectando conflitos de simultaneidade em uma linha
Para detectar conflitos de simultaneidade, uma coluna de controle de rowversion é adicionada ao modelo.
rowversion :
É específico ao SQL Server. Outros bancos de dados podem não fornecer um recurso semelhante.
É usado para determinar se uma entidade não foi alterada desde que foi buscada no BD.
O BD gera um número rowversion sequencial que é incrementado sempre que a linha é atualizada. Em um
comando Update ou Delete , a cláusula Where inclui o valor buscado de rowversion . Se a linha que está sendo
atualizada foi alterada:
rowversionnão corresponde ao valor buscado.
Os comandos Update ou Delete não encontram uma linha porque a cláusula Where inclui a rowversion
buscada.
Uma DbUpdateConcurrencyException é gerada.
No EF Core, quando nenhuma linha é atualizada por um comando Update ou Delete , uma exceção de
simultaneidade é gerada.
Adicionar uma propriedade de controle à entidade Department
Em Models/Department.cs, adicione uma propriedade de controle chamada RowVersion:
using System;
{
{

[Timestamp]
public byte[] RowVersion { get; set; }

}
}
O atributo Timestamp especifica que essa coluna é incluída na cláusula Where dos comandos Update e Delete .
O atributo é chamado Timestamp porque as versões anteriores do SQL Server usavam um tipo de dados
timestamp do SQL antes de o tipo rowversion SQL substituí-lo.
A API fluente também pode especificar a propriedade de controle:
.Property<byte[]>("RowVersion")
.IsRowVersion();
O seguinte código mostra uma parte do T-SQL gerado pelo EF Core quando o nome do Departamento é
atualizado:
SET NOCOUNT ON;
UPDATE [Department] SET [Name] = @p0
WHERE [DepartmentID] = @p1 AND [RowVersion] = @p2;
SELECT [RowVersion]
FROM [Department]
WHERE @@ROWCOUNT = 1 AND [DepartmentID] = @p1;
O código anterior realçado mostra a cláusula WHERE que contém RowVersion . Se o BD RowVersion não for igual
ao parâmetro RowVersion ( @p2 ), nenhuma linha será atualizada.
O seguinte código realçado mostra o T-SQL que verifica exatamente se uma linha foi atualizada:
SET NOCOUNT ON;

UPDATE [Department] SET [Name] = @p0
WHERE [DepartmentID] = @p1 AND [RowVersion] = @p2;
SELECT [RowVersion]
FROM [Department]
WHERE @@ROWCOUNT = 1 AND [DepartmentID] = @p1;
@@ROWCOUNT retorna o número de linhas afetadas pela última instrução. Quando nenhuma linha é
atualizada, o EF Core gera uma DbUpdateConcurrencyException .
Veja o T-SQL gerado pelo EF Core na janela de Saída do Visual Studio.
Atualizar o BD
A adição da propriedade RowVersion altera o modelo de BD, o que exige uma migração.
Compile o projeto. Insira o seguinte em uma janela Comando:
dotnet ef migrations add RowVersion

Os comandos anteriores:
Adicionam o arquivo de migração Migrations/{time stamp }_RowVersion.cs.
Atualizam o arquivo Migrations/SchoolContextModelSnapshot.cs. A atualização adiciona o seguinte
código realçado ao método BuildModel :
modelBuilder.Entity("ContosoUniversity.Models.Department", b =>
{
b.Property<int>("DepartmentID")
.ValueGeneratedOnAdd();
b.Property<decimal>("Budget")
.HasColumnType("money");
b.Property<int?>("InstructorID");
b.Property<string>("Name")
.HasMaxLength(50);
b.Property<byte[]>("RowVersion")
.IsConcurrencyToken()
.ValueGeneratedOnAddOrUpdate();
b.Property<DateTime>("StartDate");
b.HasKey("DepartmentID");
b.HasIndex("InstructorID");
b.ToTable("Department");
});
Executam migrações para atualizar o BD.
Gerar o modelo Departamentos por scaffolding

Visual Studio
CLI do .NET Core
Siga as instruções em Gere um modelo de aluno por scaffold e use Department para a classe de modelo.
O comando anterior gera o modelo Department por scaffolding. Abra o projeto no Visual Studio.
Compile o projeto.
Atualizar a página Índice de Departamentos
O mecanismo de scaffolding criou uma coluna RowVersion para a página Índice, mas esse campo não deve ser
exibido. Neste tutorial, o último byte da RowVersion é exibido para ajudar a entender a simultaneidade. O último
byte não tem garantia de ser exclusivo. Um aplicativo real não exibe RowVersion ou o último byte de RowVersion
.
Atualize a página Índice:
Substitua Índice por Departamentos.
Substitua a marcação que contém RowVersion pelo último byte de RowVersion .
Substitua FirstMidName por FullName.
A seguinte marcação mostra a página atualizada:
@page
@model ContosoUniversity.Pages.Departments.IndexModel
@{
ViewData["Title"] = "Departments";
}
<h2>Departments</h2>
<p>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Department[0].Name)
</th>
<th>
@Html.DisplayNameFor(model => model.Department[0].Budget)
</th>
<th>
@Html.DisplayNameFor(model => model.Department[0].StartDate)
</th>
<th>
@Html.DisplayNameFor(model => model.Department[0].Administrator)
</th>
<th>
RowVersion
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Department) {
<tr>
<td>
@Html.DisplayFor(modelItem => item.Name)
</td>
<td>
@Html.DisplayFor(modelItem => item.Budget)
</td>
<td>
@Html.DisplayFor(modelItem => item.StartDate)
</td>
<td>
@Html.DisplayFor(modelItem => item.Administrator.FullName)
</td>
<td>
@item.RowVersion[7]
</td>
<td>
<a asp-page="./Edit" asp-route-id="@item.DepartmentID">Edit</a> |
<a asp-page="./Details" asp-route-id="@item.DepartmentID">Details</a> |
<a asp-page="./Delete" asp-route-id="@item.DepartmentID">Delete</a>
</td>
</tr>
}
</tbody>
</table>
Atualizar o modelo da página Editar

Atualize pages\departments\edit.cshtml.cs com o seguinte código:
using System.Linq;
namespace ContosoUniversity.Pages.Departments
{
{

{
_context = context;
}
[BindProperty]
// Replace ViewData["InstructorID"]
public SelectList InstructorNameSL { get; set; }

{
Department = await _context.Departments
.Include(d => d.Administrator) // eager loading
.AsNoTracking() // tracking not required
.FirstOrDefaultAsync(m => m.DepartmentID == id);
if (Department == null)
{
return NotFound();
}
// Use strongly typed data rather than ViewData.

InstructorNameSL = new SelectList(_context.Instructors,
"ID", "FirstMidName");
return Page();
}

{
{
return Page();
}
var departmentToUpdate = await _context.Departments

.Include(i => i.Administrator)
// null means Department was deleted by another user.

if (departmentToUpdate == null)
{
return await HandleDeletedDepartment();
}
// Update the RowVersion to the value when this entity was

// fetched. If the entity has been updated after it was
// fetched, RowVersion won't match the DB RowVersion and
// a DbUpdateConcurrencyException is thrown.
// A second postback will make them match, unless a new
// concurrency issue happens.
_context.Entry(departmentToUpdate)
.Property("RowVersion").OriginalValue = Department.RowVersion;
if (await TryUpdateModelAsync<Department>(
departmentToUpdate,
"Department",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
}
catch (DbUpdateConcurrencyException ex)
{
var exceptionEntry = ex.Entries.Single();
var clientValues = (Department)exceptionEntry.Entity;
var databaseEntry = exceptionEntry.GetDatabaseValues();
if (databaseEntry == null)
{
ModelState.AddModelError(string.Empty, "Unable to save. " +
"The department was deleted by another user.");
return Page();
}
var dbValues = (Department)databaseEntry.ToObject();

await setDbErrorMessage(dbValues, clientValues, _context);
// Save the current RowVersion so next postback

// matches unless an new concurrency issue happens.
Department.RowVersion = (byte[])dbValues.RowVersion;
// Must clear the model error for the next postback.
ModelState.Remove("Department.RowVersion");
}
}
InstructorNameSL = new SelectList(_context.Instructors,

"ID", "FullName", departmentToUpdate.InstructorID);
return Page();
}
private async Task<IActionResult> HandleDeletedDepartment()

{
Department deletedDepartment = new Department();
// ModelState contains the posted data because of the deletion error and will overide the
Department instance values when displaying Page().
ModelState.AddModelError(string.Empty,
"Unable to save. The department was deleted by another user.");
InstructorNameSL = new SelectList(_context.Instructors, "ID", "FullName",
Department.InstructorID);
return Page();
}
private async Task setDbErrorMessage(Department dbValues,

Department clientValues, SchoolContext context)
{
if (dbValues.Name != clientValues.Name)
{
ModelState.AddModelError("Department.Name",
$"Current value: {dbValues.Name}");
}
if (dbValues.Budget != clientValues.Budget)
{
ModelState.AddModelError("Department.Budget",
$"Current value: {dbValues.Budget:c}");
}
if (dbValues.StartDate != clientValues.StartDate)
{
ModelState.AddModelError("Department.StartDate",
$"Current value: {dbValues.StartDate:d}");
}
if (dbValues.InstructorID != clientValues.InstructorID)
{
Instructor dbInstructor = await _context.Instructors
.FindAsync(dbValues.InstructorID);
ModelState.AddModelError("Department.InstructorID",
$"Current value: {dbInstructor?.FullName}");
}
"The record you attempted to edit "
+ "was modified by another user after you. The "
+ "edit operation was canceled and the current values in the database "
+ "have been displayed. If you still want to edit this record, click "
+ "the Save button again.");
}
}
}
Para detectar um problema de simultaneidade, o OriginalValue é atualizado com o valor rowVersion da entidade
que foi buscada. O EF Core gera um comando SQL UPDATE com uma cláusula WHERE que contém o valor
RowVersion original. Se nenhuma linha for afetada pelo comando UPDATE (nenhuma linha tem o valor
RowVersion original), uma exceção DbUpdateConcurrencyException será gerada.

{
{
return Page();
}
var departmentToUpdate = await _context.Departments

// null means Department was deleted by another user.

{
return await HandleDeletedDepartment();
}
// Update the RowVersion to the value when this entity was

// fetched. If the entity has been updated after it was
// fetched, RowVersion won't match the DB RowVersion and
// a DbUpdateConcurrencyException is thrown.
// A second postback will make them match, unless a new
// concurrency issue happens.
_context.Entry(departmentToUpdate)
.Property("RowVersion").OriginalValue = Department.RowVersion;
No código anterior, Department.RowVersion é o valor quando a entidade foi buscada. OriginalValue é o valor no
BD quando FirstOrDefaultAsync foi chamado nesse método.
O seguinte código obtém os valores de cliente (os valores postados nesse método) e os valores do BD:
try
{
}
{
{
return Page();
}


}
O seguinte código adiciona uma mensagem de erro personalizada a cada coluna que tem valores de BD
diferentes daqueles que foram postados em OnPostAsync :
private async Task setDbErrorMessage(Department dbValues,

Department clientValues, SchoolContext context)
{
if (dbValues.Name != clientValues.Name)
{
ModelState.AddModelError("Department.Name",
$"Current value: {dbValues.Name}");
}
if (dbValues.Budget != clientValues.Budget)
{
ModelState.AddModelError("Department.Budget",
$"Current value: {dbValues.Budget:c}");
}
if (dbValues.StartDate != clientValues.StartDate)
{
ModelState.AddModelError("Department.StartDate",
$"Current value: {dbValues.StartDate:d}");
}
if (dbValues.InstructorID != clientValues.InstructorID)
{
Instructor dbInstructor = await _context.Instructors
.FindAsync(dbValues.InstructorID);
ModelState.AddModelError("Department.InstructorID",
$"Current value: {dbInstructor?.FullName}");
}
"The record you attempted to edit "
+ "was modified by another user after you. The "
+ "the Save button again.");
}
O código realçado a seguir define o valor RowVersion com o novo valor recuperado do BD. Na próxima vez que
o usuário clicar em Salvar, somente os erros de simultaneidade que ocorrerem desde a última exibição da
página Editar serão capturados.
try
{
}
{
{
return Page();
}


}
A instrução ModelState.Remove é obrigatória porque ModelState tem o valor RowVersion antigo. Na Página do
Razor, o valor ModelState de um campo tem precedência sobre os valores de propriedade do modelo, quando
ambos estão presentes.

Atualize Pages/Departments/Edit.cshtml com a seguinte marcação:
@page "{id:int}"
@model ContosoUniversity.Pages.Departments.EditModel
@{
}
<h2>Edit</h2>
<h4>Department</h4>
<hr />
<div class="row">
<input type="hidden" asp-for="Department.DepartmentID" />
<input type="hidden" asp-for="Department.RowVersion" />
<label>RowVersion</label>
@Model.Department.RowVersion[7]
</div>
<label asp-for="Department.Name" class="control-label"></label>
<input asp-for="Department.Name" class="form-control" />
<span asp-validation-for="Department.Name" class="text-danger"></span>
</div>
<label asp-for="Department.Budget" class="control-label"></label>
<input asp-for="Department.Budget" class="form-control" />
<span asp-validation-for="Department.Budget" class="text-danger"></span>
</div>
<label asp-for="Department.StartDate" class="control-label"></label>
<input asp-for="Department.StartDate" class="form-control" />
<span asp-validation-for="Department.StartDate" class="text-danger">
</span>
</div>
<label class="control-label">Instructor</label>
<select asp-for="Department.InstructorID" class="form-control"
asp-items="@Model.InstructorNameSL"></select>
<span asp-validation-for="Department.InstructorID" class="text-danger">
</span>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
A marcação anterior:
Atualiza a diretiva page de @page para @page "{id:int}" .
Adiciona uma versão de linha oculta. RowVersion deve ser adicionado para que o postback associe o valor.
Exibe o último byte de RowVersion para fins de depuração.
Substitui ViewData pelo InstructorNameSL fortemente tipado.
Testar conflitos de simultaneidade com a página Editar

Abra duas instâncias de navegadores de Editar no departamento de inglês:
Execute o aplicativo e selecione Departamentos.
Clique com o botão direito do mouse no hiperlink Editar do departamento de inglês e selecione Abrir em
uma nova guia.
Na primeira guia, clique no hiperlink Editar do departamento de inglês.
As duas guias do navegador exibem as mesmas informações.
Altere o nome na primeira guia do navegador e clique em Salvar.
O navegador mostra a página de Índice com o valor alterado e o indicador de rowVersion atualizado. Observe o
indicador de rowVersion atualizado: ele é exibido no segundo postback na outra guia.
Altere outro campo na segunda guia do navegador.
Clique em Salvar. Você verá mensagens de erro em todos os campos que não correspondem aos valores do
BD:
Essa janela do navegador não pretendia alterar o campo Name. Copie e cole o valor atual (Languages) para o
campo Name. Saída da guia. A validação do lado do cliente remove a mensagem de erro.
Clique em Salvar novamente. O valor inserido na segunda guia do navegador foi salvo. Você verá os valores
salvos na página Índice.

Atualize o modelo da página Excluir com o seguinte código:
namespace ContosoUniversity.Pages.Departments
{
{
{
_context = context;
}
[BindProperty]
public string ConcurrencyErrorMessage { get; set; }
public async Task<IActionResult> OnGetAsync(int id, bool? concurrencyError)

{
Department = await _context.Departments
.Include(d => d.Administrator)
.AsNoTracking()
if (Department == null)
{
return NotFound();
}
if (concurrencyError.GetValueOrDefault())
{
ConcurrencyErrorMessage = "The record you attempted to delete "
+ "was modified by another user after you selected delete. "
+ "The delete operation was canceled and the current values in the "
+ "database have been displayed. If you still want to delete this "
+ "record, click the Delete button again.";
}
return Page();
}

{
try
{
if (await _context.Departments.AnyAsync(
m => m.DepartmentID == id))
{
// Department.rowVersion value is from when the entity
// was fetched. If it doesn't match the DB, a
// DbUpdateConcurrencyException exception is thrown.
_context.Departments.Remove(Department);
}
}
{
return RedirectToPage("./Delete",
new { concurrencyError = true, id = id });
}
}
}
}
A página Excluir detectou conflitos de simultaneidade quando a entidade foi alterada depois de ser buscada.
Department.RowVersion é a versão de linha quando a entidade foi buscada. Quando o EF Core cria o comando
SQL DELETE, ele inclui uma cláusula WHERE com RowVersion . Se o comando SQL DELETE não resultar em
nenhuma linha afetada:
A RowVersion no comando SQL DELETE não corresponderá a RowVersion no BD.
Uma exceção DbUpdateConcurrencyException é gerada.
OnGetAsync é chamado com o concurrencyError .
Atualize Pages/Departments/Delete.cshtml com o seguinte código:
@page "{id:int}"
@model ContosoUniversity.Pages.Departments.DeleteModel
@{
}
<h2>Delete</h2>
<p class="text-danger">@Model.ConcurrencyErrorMessage</p>

<div>
<h4>Department</h4>
<hr />
<dt>
@Html.DisplayNameFor(model => model.Department.Name)
</dt>
<dd>
@Html.DisplayFor(model => model.Department.Name)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Department.Budget)
</dt>
<dd>
@Html.DisplayFor(model => model.Department.Budget)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Department.StartDate)
</dt>
<dd>
@Html.DisplayFor(model => model.Department.StartDate)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Department.RowVersion)
</dt>
<dd>
@Html.DisplayFor(model => model.Department.RowVersion[7])
</dd>
<dt>
@Html.DisplayNameFor(model => model.Department.Administrator)
</dt>
<dd>
@Html.DisplayFor(model => model.Department.Administrator.FullName)
</dd>
</dl>
<input type="hidden" asp-for="Department.DepartmentID" />
<input type="hidden" asp-for="Department.RowVersion" />
</div>
</form>
</div>

Atualiza a diretiva page de @page para @page "{id:int}" .
Adiciona uma mensagem de erro.
Substitua FirstMidName por FullName no campo Administrador.
Altere RowVersion para exibir o último byte.
Adiciona uma versão de linha oculta. RowVersion deve ser adicionado para que o postback associe o valor.
Testar conflitos de simultaneidade com a página Excluir
Crie um departamento de teste.
Abra duas instâncias dos navegadores de Excluir no departamento de teste:
Execute o aplicativo e selecione Departamentos.
Clique com o botão direito do mouse no hiperlink Excluir do departamento de teste e selecione Abrir em
uma nova guia.
Clique no hiperlink Editar do departamento de teste.
As duas guias do navegador exibem as mesmas informações.
Altere o orçamento na primeira guia do navegador e clique em Salvar.
O navegador mostra a página de Índice com o valor alterado e o indicador de rowVersion atualizado. Observe o
indicador de rowVersion atualizado: ele é exibido no segundo postback na outra guia.
Exclua o departamento de teste na segunda guia. Um erro de simultaneidade é exibido com os valores atuais do
BD. Clicar em Excluir exclui a entidade, a menos que RowVersion tenha sido atualizada e o departamento tenha
sido excluído.
Consulte Herança para saber como herdar um modelo de dados.
Recursos adicionais
Tokens de simultaneidade no EF Core
Lidar com a simultaneidade no EF Core
A N T E R IO R
ASP.NET Core MVC com EF Core – série de tutoriais
Páginas Razor é uma nova alternativa no ASP.NET Core 2.0, um modelo de programação baseado em página que
torna a criação da interface do usuário da Web mais fácil e produtiva. É recomendável tentar o tutorial das Páginas
Razor na versão do MVC. O tutorial Páginas do Razor:
1. Introdução
4. Migrações
9. Herança
10. Tópicos avançados
ASP.NET Core MVC com o Entity Framework Core –
tutorial – 1 de 10
Este tutorial não foi atualizado para o ASP.NET Core 2.1. A versão deste tutorial para o ASP.NET Core 2.0 pode
ser consultada selecionando ASP.NET Core 2.0 acima do sumário ou na parte superior da página:
A versão deste tutorial do Razor Pages para o ASP.NET Core 2.1 conta com várias melhorias em relação à
versão 2.0.
O tutorial do 2.0 ensina a usar o ASP.NET Core MVC e o Entity Framework Core com controladores e
exibições. O Razor Pages é um modelo de programação baseado em página que torna a criação da interface do
usuário da Web mais fácil e produtiva. É recomendável tentar o tutorial das Páginas Razor na versão do MVC.
O tutorial Páginas do Razor:
É mais fácil de acompanhar. Por exemplo, o código de scaffolding foi bastante simplificado.
Se você escolher este tutorial em vez da versão Razor Pages, deixe uma observação explicando o motivo nesta
discussão do GitHub.
Páginas Razor é uma nova alternativa no ASP.NET Core 2.0, um modelo de programação baseado em página
que torna a criação da interface do usuário da Web mais fácil e produtiva. É recomendável tentar o tutorial das
Páginas Razor na versão do MVC. O tutorial Páginas do Razor:
O aplicativo Web de exemplo Contoso University demonstra como criar aplicativos Web ASP.NET Core 2.0
MVC usando o EF (Entity Framework) Core 2.0 e o Visual Studio 2017.
O aplicativo de exemplo é um site de uma Contoso University fictícia. Ele inclui funcionalidades como admissão
de alunos, criação de cursos e atribuições de instrutor. Este é o primeiro de uma série de tutoriais que explica
como criar o aplicativo de exemplo Contoso University do zero.
Baixe ou exiba o aplicativo concluído.
O EF Core 2.0 é a última versão do EF, mas ainda não tem todos os recursos do EF 6.x. Para obter informações
sobre como escolher entre o EF 6.x e o EF Core, consulte EF Core vs. EF6.x. Se você escolher o EF 6.x, confira a
versão anterior desta série de tutoriais.
NOTE
Para obter a versão ASP.NET Core 1.1 deste tutorial, confira a versão VS 2017 Atualização 2 deste tutorial em formato
PDF.
Pré-requisitos
Caso tenha um problema que não consiga resolver, em geral, você poderá encontrar a solução comparando o
código com o projeto concluído. Para obter uma lista de erros comuns e como resolvê-los, consulte a seção
Solução de problemas do último tutorial da série. Caso não encontre o que precisa na seção, poste uma
pergunta no StackOverflow.com sobre o ASP.NET Core ou o EF Core.
TIP
Esta é uma série de dez tutoriais, cada um se baseando no que é feito nos tutoriais anteriores. Considere a possibilidade
de salvar uma cópia do projeto após a conclusão bem-sucedida de cada tutorial. Caso tenha problemas, comece
novamente no tutorial anterior em vez de voltar ao início de toda a série.
O aplicativo Web Contoso University

O aplicativo que você criará nestes tutoriais é um site simples de uma universidade.
Os usuários podem exibir e atualizar informações de alunos, cursos e instrutores. Estas são algumas das telas
que você criará.
O estilo de interface do usuário desse site foi mantido perto do que é gerado pelos modelos internos, de modo
que o tutorial possa se concentrar principalmente em como usar o Entity Framework.
Criar um aplicativo Web ASP.NET Core MVC

Abra o Visual Studio e crie um novo projeto Web ASP.NET Core C# chamado "ContosoUniversity".
No painel esquerdo, selecione Instalado > Visual C# > Web.
Selecione o modelo de projeto Aplicativo Web ASP.NET Core.
Insira ContosoUniversity como o nome e clique em OK.
Aguarde a caixa de diálogo Novo Aplicativo Web ASP.NET Core (.NET Core) ser exibida
Selecione ASP.NET Core 2.0 e o modelo Aplicativo Web (Model-View-Controller).
Observação: este tutorial exige o ASP.NET Core 2.0 e o EF Core 2.0 ou posterior — verifique se
ASP.NET Core 1.1 não está selecionado.
Verifique se a opção Autenticação está definida como Sem Autenticação.
Clique em OK
Configurar o estilo do site

Algumas alterações simples configurarão o menu do site, o layout e a home page.
Abra Views/Shared/_Layout.cshtml e faça as seguintes alterações:
Altere cada ocorrência de "ContosoUniversity" para "Contoso University". Há três ocorrências.
Adicione entradas de menu para Alunos, Cursos, Instrutores e Departamentos e exclua a entrada de
menu Contato.
As alterações são realçadas.
<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] - Contoso University</title>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
<a asp-area="" asp-controller="Home" asp-action="Index" class="navbar-brand">Contoso
University</a>
</div>
<li><a asp-area="" asp-controller="Students" asp-action="Index">Students</a></li>
<li><a asp-area="" asp-controller="Courses" asp-action="Index">Courses</a></li>
<li><a asp-area="" asp-controller="Instructors" asp-action="Index">Instructors</a></li>
<li><a asp-area="" asp-controller="Departments" asp-action="Index">Departments</a></li>
</ul>
</div>
</div>
</nav>
@RenderBody()
<hr />
<footer>
<p>© 2017 - Contoso University</p>
</footer>
</div>
</environment>
</script>
</script>
</environment>

</body>
</html>
Em Views/Home/Index.cshtml, substitua o conteúdo do arquivo pelo seguinte código para substituir o texto
sobre o ASP.NET e MVC pelo texto sobre este aplicativo:
@{
ViewData["Title"] = "Home Page";
}
<h1>Contoso University</h1>
</div>
<div class="row">
<h2>Welcome to Contoso University</h2>
<p>
Contoso University is a sample application that
demonstrates how to use Entity Framework Core in an
ASP.NET Core MVC web application.
</p>
</div>
<h2>Build it from scratch</h2>
<p>You can build the application by following the steps in a series of tutorials.</p>
<p><a class="btn btn-default" href="https://docs.asp.net/en/latest/data/ef-mvc/intro.html">See the
tutorial »</a></p>
</div>
<h2>Download it</h2>
<p>You can download the completed project from GitHub.</p>
<p><a class="btn btn-default" href="https://github.com/aspnet/Docs/tree/master/aspnetcore/data/ef-
mvc/intro/samples/cu-final">See project source code »</a></p>
</div>
</div>
Pressione CTRL+F5 para executar o projeto ou escolha Depurar > Iniciar sem Depuração no menu. Você
verá a home page com guias para as páginas que você criará nestes tutoriais.
Pacotes NuGet do Entity Framework Core
Para adicionar o suporte do EF Core a um projeto, instale o provedor de banco de dados que você deseja ter
como destino. Este tutorial usa o SQL Server e o pacote de provedor é
Microsoft.EntityFrameworkCore.SqlServer. Esse pacote está incluído no metapacote
Microsoft.AspNetCore.App, portanto você não precisa referenciar o pacote se o aplicativo tem uma referência
de pacote ao pacote Microsoft.AspNetCore.App .
Este pacote e suas dependências ( Microsoft.EntityFrameworkCore e Microsoft.EntityFrameworkCore.Relational )
fornecem suporte de tempo de execução para o EF. Você adicionará um pacote de ferramentas posteriormente,
no tutorial Migrações.
Para obter informações sobre outros provedores de banco de dados que estão disponíveis para o Entity
Framework Core, consulte Provedores de banco de dados.
Criar o modelo de dados

Em seguida, você criará as classes de entidade para o aplicativo Contoso University. Você começará com as três
entidades a seguir.
Há uma relação um-para-muitos entre as entidades Student e Enrollment , e uma relação um-para-muitos
entre as entidades Course e Enrollment . Em outras palavras, um aluno pode ser registrado em qualquer
quantidade de cursos e um curso pode ter qualquer quantidade de alunos registrados.
Nas seções a seguir, você criará uma classe para cada uma dessas entidades.
A entidade Student
Na pasta Models, crie um arquivo de classe chamado Student.cs e substitua o código de modelo pelo código a
seguir.
using System;
{
{

}
}
A propriedade ID se tornará a coluna de chave primária da tabela de banco de dados que corresponde a essa
classe. Por padrão, o Entity Framework interpreta uma propriedade nomeada ID ou classnameID como a
chave primária.
A propriedade Enrollments é uma propriedade de navegação. As propriedades de navegação armazenam
outras entidades que estão relacionadas a essa entidade. Nesse caso, a propriedade Enrollments de uma
Student entity armazenará todas as entidades Enrollment relacionadas a essa entidade Student . Em outras
palavras, se determinada linha Aluno no banco de dados tiver duas linhas Registro relacionadas (linhas que
contêm o valor de chave primária do aluno na coluna de chave estrangeira StudentID ), a propriedade de
navegação Enrollments dessa entidade Student conterá as duas entidades Enrollment .
Se uma propriedade de navegação pode armazenar várias entidades (como em relações muitos para muitos ou
um-para-muitos), o tipo precisa ser uma lista na qual entradas podem ser adicionadas, excluídas e atualizadas,
como ICollection<T> . Especifique ICollection<T> ou um tipo, como List<T> ou HashSet<T> . Se você
especificar ICollection<T> , o EF criará uma coleção HashSet<T> por padrão.
A entidade Enrollment
Na pasta Models, crie Enrollment.cs e substitua o código existente pelo seguinte código:
{
public enum Grade
{
A, B, C, D, F
}

{

}
}
A propriedade EnrollmentID será a chave primária; essa entidade usa o padrão classnameID em vez de ID por
si só, como você viu na entidade Student . Normalmente, você escolhe um padrão e usa-o em todo o modelo
de dados. Aqui, a variação ilustra que você pode usar qualquer um dos padrões. Em um tutorial posterior, você
verá como usar uma ID sem nome de classe facilita a implementação da herança no modelo de dados.
A propriedade Grade é um enum . O ponto de interrogação após a declaração de tipo Grade indica que a
propriedade Grade permite valor nulo. Uma nota nula é diferente de uma nota zero – nulo significa que uma
nota não é conhecida ou que ainda não foi atribuída.
A propriedade StudentID é uma chave estrangeira e a propriedade de navegação correspondente é Student .
Uma entidade Enrollment é associada a uma entidade Student , de modo que a propriedade possa armazenar
apenas uma única entidade Student (ao contrário da propriedade de navegação Student.Enrollments que você
viu anteriormente, que pode armazenar várias entidades Enrollment ).
A propriedade CourseID é uma chave estrangeira e a propriedade de navegação correspondente é Course .
Uma entidade Enrollment está associada a uma entidade Course .
O Entity Framework interpreta uma propriedade como uma propriedade de chave estrangeira se ela é
nomeada <navigation property name><primary key property name> (por exemplo, StudentID para a propriedade
de navegação Student , pois a chave primária da entidade Student é ID ). As propriedades de chave
estrangeira também podem ser nomeadas apenas <primary key property name> (por exemplo, CourseID , pois a
chave primária da entidade Course é CourseID ).
A entidade Course
Na pasta Models, crie Course.cs e substitua o código existente pelo seguinte código:
{
public class Course
{

}
}
A propriedade Enrollments é uma propriedade de navegação. Uma entidade Course pode estar relacionada a
qualquer quantidade de entidades Enrollment .
Falaremos mais sobre o atributo DatabaseGenerated em um tutorial posterior desta série. Basicamente, esse
atributo permite que você insira a chave primária do curso, em vez de fazer com que ela seja gerada pelo banco
de dados.

A classe principal que coordena a funcionalidade do Entity Framework para determinado modelo de dados é a
classe de contexto de banco de dados. Você cria essa classe derivando-a da classe
Microsoft.EntityFrameworkCore.DbContext . No código, especifique quais entidades são incluídas no modelo de
dados. Também personalize o comportamento específico do Entity Framework. Neste projeto, a classe é
chamada SchoolContext .
Na pasta do projeto, crie uma pasta chamada Dados.
Na pasta Dados, crie um novo arquivo de classe chamado SchoolContext.cs e substitua o código de modelo
pelo seguinte código:
{
{
{
}

public DbSet<Enrollment> Enrollments { get; set; }
public DbSet<Student> Students { get; set; }
}
}
Esse código cria uma propriedade DbSet para cada conjunto de entidades. Na terminologia do Entity
Você pode omitir as instruções DbSet<Enrollment> e DbSet<Course> e elas funcionarão da mesma maneira. O
Entity Framework inclui-os de forma implícita porque a entidade Student referencia a entidade Enrollment e a
entidade Enrollment referencia a entidade Course .
Quando o banco de dados é criado, o EF cria tabelas que têm nomes iguais aos nomes de propriedade DbSet .
Em geral, os nomes de propriedade de coleções são plurais (Alunos em vez de Aluno), mas os desenvolvedores
não concordam sobre se os nomes de tabela devem ser pluralizados ou não. Para esses tutoriais, você
substituirá o comportamento padrão especificando nomes singulares de tabela no DbContext. Para fazer isso,
adicione o código realçado a seguir após a última propriedade DbSet.
{
{
{
}


{
}
}
}
Registrar o contexto com a injeção de dependência

O ASP.NET Core implementa a injeção de dependência por padrão. Serviços (como o contexto de banco de
dados do EF ) são registrados com injeção de dependência durante a inicialização do aplicativo. Os
componentes que exigem esses serviços (como controladores MVC ) recebem esses serviços por meio de
parâmetros do construtor. Você verá o código de construtor do controlador que obtém uma instância de
contexto mais adiante neste tutorial.
Para registrar SchoolContext como um serviço, abra Startup.cs e adicione as linhas realçadas ao método
ConfigureServices .

{
services.AddDbContext<SchoolContext>(options =>
services.AddMvc();
}
DbContextOptionsBuilder . Para o desenvolvimento local, o sistema de configuração do ASP.NET Core lê a
cadeia de conexão do arquivo appsettings.json.
Adicione instruções using aos namespaces ContosoUniversity.Data e Microsoft.EntityFrameworkCore e, em
seguida, compile o projeto.
Abra o arquivo appsettings.json e adicione uma cadeia de conexão, conforme mostrado no exemplo a seguir.
{
"DefaultConnection": "Server=
(localdb)\\mssqllocaldb;Database=ContosoUniversity1;Trusted_Connection=True;MultipleActiveResultSets=true"
},
"Logging": {
"LogLevel": {
}
}
}

A cadeia de conexão especifica um banco de dados LocalDB do SQL Server. LocalDB é uma versão leve do
Mecanismo de Banco de Dados do SQL Server Express destinado ao desenvolvimento de aplicativos, e não ao
uso em produção. O LocalDB é iniciado sob demanda e executado no modo de usuário e, portanto, não há
nenhuma configuração complexa. Por padrão, o LocalDB cria arquivos de banco de dados .mdf no diretório
C:/Users/<user> .
Adicionar um código para inicializar o banco de dados com os dados

de teste
O Entity Framework criará um banco de dados vazio para você. Nesta seção, você escreve um método que é
chamado depois que o banco de dados é criado para populá-lo com os dados de teste.
Aqui, você usará o método EnsureCreated para criar o banco de dados automaticamente. Em um tutorial
posterior, você verá como manipular as alterações do modelo usando as Migrações do Code First para alterar o
esquema de banco de dados, em vez de remover e recriar o banco de dados.
Na pasta Data, crie um novo arquivo de classe chamado DbInitializer.cs e substitua o código de modelo pelo
código a seguir, que faz com que um banco de dados seja criado, quando necessário, e carrega dados de teste
no novo banco de dados.
using System;
using System.Linq;
{
{
{

if (context.Students.Any())
{
}

{
new Student{FirstMidName="Carson",LastName="Alexander",EnrollmentDate=DateTime.Parse("2005-09-
01")},
new Student{FirstMidName="Meredith",LastName="Alonso",EnrollmentDate=DateTime.Parse("2002-09-
01")},
new Student{FirstMidName="Arturo",LastName="Anand",EnrollmentDate=DateTime.Parse("2003-09-
01")},
new Student{FirstMidName="Gytis",LastName="Barzdukas",EnrollmentDate=DateTime.Parse("2002-09-
01")},
new Student{FirstMidName="Yan",LastName="Li",EnrollmentDate=DateTime.Parse("2002-09-01")},
new Student{FirstMidName="Peggy",LastName="Justice",EnrollmentDate=DateTime.Parse("2001-09-
01")},
new Student{FirstMidName="Laura",LastName="Norman",EnrollmentDate=DateTime.Parse("2003-09-
01")},
new Student{FirstMidName="Nino",LastName="Olivetto",EnrollmentDate=DateTime.Parse("2005-09-
01")}
};
{
context.Students.Add(s);
}

{
new Course{CourseID=1050,Title="Chemistry",Credits=3},
new Course{CourseID=4022,Title="Microeconomics",Credits=3},
new Course{CourseID=4041,Title="Macroeconomics",Credits=3},
new Course{CourseID=1045,Title="Calculus",Credits=4},
new Course{CourseID=3141,Title="Trigonometry",Credits=4},
new Course{CourseID=2021,Title="Composition",Credits=3},
new Course{CourseID=2042,Title="Literature",Credits=4}
};
{
}

{
};
{
context.Enrollments.Add(e);
}
}
}
}
O código verifica se há alunos no banco de dados e, se não há, ele pressupõe que o banco de dados é novo e
precisa ser propagado com os dados de teste. Ele carrega os dados de teste em matrizes em vez de em coleções
List<T> para otimizar o desempenho.
Em Program.cs, modifique o método Main para fazer o seguinte na inicialização do aplicativo:

Obtenha uma instância de contexto de banco de dados do contêiner de injeção de dependência.
Chame o método de semente passando a ele o contexto.
Descarte o contexto quando o método de semente for concluído.

{

{
try
{
DbInitializer.Initialize(context);
}
{
logger.LogError(ex, "An error occurred while seeding the database.");
}
}
host.Run();
}
Adicione instruções using :
Nos tutoriais mais antigos, você poderá ver um código semelhante no método Configure em Startup.cs.
Recomendamos que você use o método Configure apenas para configurar o pipeline de solicitação. O código
de inicialização do aplicativo pertence ao método Main .
Agora, na primeira vez que você executar o aplicativo, o banco de dados será criado e propagado com os dados
de teste. Sempre que você alterar o modelo de dados, exclua o banco de dados, atualize o método de semente e
comece novamente com um novo banco de dados da mesma maneira. Nos próximos tutoriais, você verá como
modificar o banco de dados quando o modelo de dados for alterado, sem excluí-lo e recriá-lo.
Criar um controlador e exibições

Em seguida, você usará o mecanismo de scaffolding no Visual Studio para adicionar um controlador MVC e
exibições que usam o EF para consultar e salvar dados.
A criação automática de métodos de ação CRUD e exibições é conhecida como scaffolding. O scaffolding difere
da geração de código, em que o código gerado por scaffolding é um ponto de partida que você pode modificar
de acordo com seus requisitos, enquanto que normalmente o código gerado não é modificado. Quando
precisar personalizar o código gerado, use classes parciais ou regenere o código quando as coisas mudarem.
Clique com o botão direito do mouse na pasta Controladores no Gerenciador de Soluções e selecione
Adicionar > Novo Item Gerado por Scaffolding.
Se a caixa de diálogo Adicionar Dependências do MVC for exibida:
Atualize o Visual Studio para a última versão. Versões do Visual Studio anteriores a 15.5 mostram essa
caixa de diálogo.
Se não puder atualizar, selecione ADICIONAR e, em seguida, siga as etapas de adição do controlador
novamente.
Na caixa de diálogo Adicionar Scaffolding:
Selecione Controlador MVC com exibições, usando o Entity Framework.
Clique em Adicionar.
Na caixa de diálogo Adicionar Controlador:
Na classe Model, selecione Aluno.
Na Classe de contexto de dados selecione SchoolContext.
Aceite o StudentsController padrão como o nome.
Clique em Adicionar.
Quando você clica em Adicionar, o mecanismo de scaffolding do Visual Studio cria um arquivo
StudentsController.cs e um conjunto de exibições (arquivos .cshtml) que funcionam com o controlador.
(O mecanismo de scaffolding também poderá criar o contexto de banco de dados para você se não criá-lo
manualmente primeiro como fez anteriormente para este tutorial. Especifique uma nova classe de contexto na
caixa Adicionar Controlador clicando no sinal de adição à direita de Classe de contexto de dados. Em
seguida, o Visual Studio criará a classe DbContext , bem como o controlador e as exibições.)
Você observará que o controlador usa um SchoolContext como parâmetro de construtor.
namespace ContosoUniversity.Controllers
{
public class StudentsController : Controller
{
public StudentsController(SchoolContext context)

{
_context = context;
}
A injeção de dependência do ASP.NET Core é responsável por passar uma instância de SchoolContext para o
controlador. Você configurou isso no arquivo Startup.cs anteriormente.
O controlador contém um método de ação Index , que exibe todos os alunos no banco de dados. O método
obtém uma lista de alunos do conjunto de entidades Students pela leitura da propriedade Students da
instância de contexto de banco de dados:

{
return View(await _context.Students.ToListAsync());
}
Você aprenderá sobre os elementos de programação assíncronos nesse código mais adiante no tutorial.
A exibição Views/Students/Index.cshtml mostra esta lista em uma tabela:
@model IEnumerable<ContosoUniversity.Models.Student>
@{
}
<h2>Index</h2>
<p>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.LastName)
</th>
<th>
@Html.DisplayNameFor(model => model.FirstMidName)
</th>
<th>
@Html.DisplayNameFor(model => model.EnrollmentDate)
</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
Pressione CTRL+F5 para executar o projeto ou escolha Depurar > Iniciar sem Depuração no menu.
Clique na guia Alunos para ver os dados de teste inserido pelo método DbInitializer.Initialize . Dependendo
da largura da janela do navegador, você verá o link da guia Student na parte superior da página ou precisará
clicar no ícone de navegação no canto superior direito para ver o link.
Exibir o banco de dados
Quando você iniciou o aplicativo, o método DbInitializer.Initialize chamou EnsureCreated . O EF observou
que não havia nenhum banco de dados e, portanto, ele criou um; em seguida, o restante do código do método
Initialize populou o banco de dados com os dados. Use o SSOX ( Pesquisador de Objetos do SQL Server )
para exibir o banco de dados no Visual Studio.
Feche o navegador.
Se a janela do SSOX ainda não estiver aberta, selecione-a no menu Exibir do Visual Studio.
No SSOX, clique em (localdb)\MSSQLLocalDB > Bancos de Dados e, em seguida, clique na entrada do
nome do banco de dados que está na cadeia de conexão no arquivo appsettings.json.
Expanda o nó Tabelas para ver as tabelas no banco de dados.
Clique com o botão direito do mouse na tabela Aluno e clique em Exibir Dados para ver as colunas criadas e
as linhas que foram inseridas na tabela.
Os arquivos de banco de dados .mdf e .ldf estão na pasta C:\Users\.

Como você está chamando EnsureCreated no método inicializador executado na inicialização do aplicativo,
agora você pode fazer uma alteração na classe Student , excluir o banco de dados, executar novamente o
aplicativo e o banco de dados será recriado automaticamente para que ele corresponda à alteração. Por
exemplo, se você adicionar uma propriedade EmailAddress à classe Student , verá uma nova coluna
EmailAddress na tabela recriada.
Convenções
A quantidade de código feita para que o Entity Framework possa criar um banco de dados completo para você
é mínima, devido ao uso de convenções ou de suposições feitas pelo Entity Framework.
Os nomes de propriedades DbSet são usadas como nomes de tabela. Para entidades não referenciadas
por uma propriedade DbSet , os nomes de classe de entidade são usados como nomes de tabela.
Os nomes de propriedade de entidade são usados para nomes de coluna.
As propriedades de entidade que são nomeadas ID ou classnameID são reconhecidas como
propriedades de chave primária.
Uma propriedade é interpretada como uma propriedade de chave estrangeira se ela é nomeada (por
exemplo, StudentID para a propriedade de navegação Student , pois a chave primária da entidade
Student é ID ). As propriedades de chave estrangeira também podem ser nomeadas apenas (por
exemplo, EnrollmentID , pois a chave primária da entidade Enrollment é EnrollmentID ).
O comportamento convencional pode ser substituído. Por exemplo, você pode especificar os nomes de tabela
de forma explícita, conforme visto anteriormente neste tutorial. Além disso, você pode definir nomes de coluna
e qualquer propriedade como a chave primária ou chave estrangeira, como você verá em um tutorial posterior
desta série.
Código assíncrono
A programação assíncrona é o modo padrão do ASP.NET Core e EF Core.
Um servidor Web tem um número limitado de threads disponíveis e, em situações de alta carga, todos os
threads disponíveis podem estar em uso. Quando isso acontece, o servidor não pode processar novas
solicitações até que os threads são liberados. Com um código síncrono, muitos threads podem ser vinculados
enquanto realmente não são fazendo nenhum trabalho porque estão aguardando a conclusão da E/S. Com um
código assíncrono, quando um processo está aguardando a conclusão da E/S, seu thread é liberado para o
servidor para ser usado para processar outras solicitações. Como resultado, o código assíncrono permite que
os recursos do servidor sejam usados com mais eficiência, e o servidor fica capacitado a manipular mais
tráfego sem atrasos.
O código assíncrono introduz uma pequena quantidade de sobrecarga em tempo de execução, mas para
situações de baixo tráfego, o impacto no desempenho é insignificante, ao passo que, em situações de alto
tráfego, a melhoria de desempenho potencial é significativa.
No código a seguir, a palavra-chave async , o valor retornado Task<T> , a palavra-chave await e o método
ToListAsync fazem o código ser executado de forma assíncrona.

{
return View(await _context.Students.ToListAsync());
}
A palavra-chave async instrui o compilador a gerar retornos de chamada para partes do corpo do
método e a criar automaticamente o objeto Task<IActionResult> que é retornado.
O tipo de retorno Task<IActionResult> representa um trabalho em andamento com um resultado do
tipo IActionResult .
A palavra-chave await faz com que o compilador divida o método em duas partes. A primeira parte
termina com a operação que é iniciada de forma assíncrona. A segunda parte é colocada em um método
de retorno de chamada que é chamado quando a operação é concluída.
ToListAsync é a versão assíncrona do método de extensão ToList .
Algumas coisas a serem consideradas quando você estiver escrevendo um código assíncrono que usa o Entity
Framework:
Somente instruções que fazem com que consultas ou comandos sejam enviados ao banco de dados são
executadas de forma assíncrona. Isso inclui, por exemplo, ToListAsync , SingleOrDefaultAsync e
SaveChangesAsync . Isso não inclui, por exemplo, instruções que apenas alteram um IQueryable , como
var students = context.Students.Where(s => s.LastName == "Davolio") .
Um contexto do EF não é thread-safe: não tente realizar várias operações em paralelo. Quando você
chamar qualquer método assíncrono do EF, sempre use a palavra-chave await .
Se desejar aproveitar os benefícios de desempenho do código assíncrono, verifique se os pacotes de
biblioteca que você está usando (por exemplo, para paginação) também usam o código assíncrono se
eles chamam métodos do Entity Framework que fazem com que consultas sejam enviadas ao banco de
dados.
Para obter mais informações sobre a programação assíncrona no .NET, consulte Visão geral da programação
assíncrona.
Resumo
Agora, você criou um aplicativo simples que usa o Entity Framework Core e o LocalDB do SQL Server Express
para armazenar e exibir dados. No tutorial a seguir, você aprenderá a executar operações CRUD (criar, ler,
atualizar e excluir) básicas.
A VA N ÇA R
ASP.NET Core MVC com EF Core – CRUD – 2 de 10
A versão deste tutorial do Razor Pages para o ASP.NET Core 2.1 conta com várias melhorias em relação à versão
2.0.
O tutorial do 2.0 ensina a usar o ASP.NET Core MVC e o Entity Framework Core com controladores e exibições.
O Razor Pages é um modelo de programação baseado em página que torna a criação da interface do usuário da
Web mais fácil e produtiva. É recomendável tentar o tutorial das Páginas Razor na versão do MVC. O tutorial
Páginas do Razor:
O aplicativo web de exemplo Contoso University demonstra como criar aplicativos web do ASP.NET Core MVC
usando o Entity Framework Core e o Visual Studio. Para obter informações sobre a série de tutoriais, consulte o
primeiro tutorial da série.
No tutorial anterior, você criou um aplicativo MVC que armazena e exibe dados usando o Entity Framework e o
LocalDB do SQL Server. Neste tutorial, você examinará e personalizará o código CRUD (criar, ler, atualizar e
excluir) que o scaffolding do MVC cria automaticamente para você em controladores e exibições.
NOTE
É uma prática comum implementar o padrão de repositório para criar uma camada de abstração entre o controlador e a
camada de acesso a dados. Para manter esses tutoriais simples e com foco no ensino de como usar o Entity Framework em
si, eles não usam repositórios. Para obter informações sobre repositórios com o EF, consulte o último tutorial desta série.
Neste tutorial, você trabalhará com as seguintes páginas da Web:

Personalizar a página Detalhes
O código gerado por scaffolding da página Índice de Alunos omitiu a propriedade Enrollments , porque essa
propriedade contém uma coleção. Na página Detalhes, você exibirá o conteúdo da coleção em uma tabela
HTML.
Em Controllers/StudentsController.cs, o método de ação para a exibição Detalhes usa o método
SingleOrDefaultAsync para recuperar uma única entidade Student . Adicione um código que chama Include . Os
métodos ThenInclude e AsNoTracking , conforme mostrado no código realçado a seguir.

{
if (id == null)
{
return NotFound();
}
var student = await _context.Students

.Include(s => s.Enrollments)
.ThenInclude(e => e.Course)
.AsNoTracking()
{
return NotFound();
}
return View(student);
}
Os métodos Include e ThenInclude fazem com que o contexto carregue a propriedade de navegação
Student.Enrollments e, dentro de cada registro, a propriedade de navegação Enrollment.Course . Você aprenderá
mais sobre esses métodos no tutorial Ler dados relacionados.
O método AsNoTracking melhora o desempenho em cenários em que as entidades retornadas não serão
atualizadas no tempo de vida do contexto atual. Você aprenderá mais sobre AsNoTracking ao final deste tutorial.
Dados de rota
O valor de chave que é passado para o método Details é obtido dos dados de rota. Dados de rota são dados
que o associador de modelos encontrou em um segmento da URL. Por exemplo, a rota padrão especifica os
segmentos de controlador, ação e ID:
{
routes.MapRoute(
name: "default",
});
Na URL a seguir, a rota padrão mapeia Instructor como o controlador, Index como a ação e 1 como a ID; esses
são valores de dados de rota.
http://localhost:1230/Instructor/Index/1?courseID=2021
A última parte da URL ("?courseID=2021") é um valor de cadeia de caracteres de consulta. O associador de

modelos passará o valor da ID para o parâmetro id do método Details se você passá-lo como um valor de
cadeia de caracteres de consulta:
http://localhost:1230/Instructor/Index?id=1&CourseID=2021
Na página Índice, as URLs de hiperlinks são criadas por instruções de auxiliar de marcação na exibição do Razor.
No código Razor a seguir, o parâmetro id corresponde à rota padrão e, portanto, id é adicionada aos dados de
rota.
<a asp-action="Edit" asp-route-id="@item.ID">Edit</a>
Isso gera o seguinte HTML quando item.ID é 6:
<a href="/Students/Edit/6">Edit</a>
No código a seguir Razor, studentID não corresponde a um parâmetro na rota padrão e, portanto, ela é
adicionada como uma cadeia de caracteres de consulta.
<a asp-action="Edit" asp-route-studentID="@item.ID">Edit</a>
Isso gera o seguinte HTML quando item.ID é 6:
<a href="/Students/Edit?studentID=6">Edit</a>
Para obter mais informações sobre os auxiliares de marca, confira Auxiliares de Marca no ASP.NET Core.
Adicionar registros à exibição Detalhes
Abra Views/Students/Details.cshtml. Cada campo é exibido usando auxiliares DisplayNameFor e DisplayFor ,
<dt>
@Html.DisplayNameFor(model => model.LastName)
</dt>
<dd>
@Html.DisplayFor(model => model.LastName)
</dd>
Após o último campo e imediatamente antes da marcação </dl> de fechamento, adicione o seguinte código
para exibir uma lista de registros:
<dt>
@Html.DisplayNameFor(model => model.Enrollments)
</dt>
<dd>
<tr>
<th>Course Title</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.Enrollments)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.Course.Title)
</td>
<td>
</td>
</tr>
}
</table>
</dd>
Se o recuo do código estiver incorreto depois de colar o código, pressione CTRL -K-D para corrigi-lo.
Esse código percorre as entidades na propriedade de navegação Enrollments . Para cada registro, ele exibe o
nome do curso e a nota. O título do curso é recuperado da entidade Course, que é armazenada na propriedade de
navegação Course da entidade Enrollments.
Execute o aplicativo, selecione a guia Alunos e clique no link Detalhes de um aluno. Você verá a lista de cursos e
notas do aluno selecionado:
Atualizar a página Criar

Em StudentsController.cs, modifique o método HttpPost Create adicionando um bloco try-catch e removendo a
ID do atributo Bind .
[HttpPost]
[Bind("EnrollmentDate,FirstMidName,LastName")] Student student)
{
try
{
{
_context.Add(student);
}
}
{
//Log the error (uncomment ex variable name and write a log.
ModelState.AddModelError("", "Unable to save changes. " +
"Try again, and if the problem persists " +
"see your system administrator.");
}
}
Esse código adiciona a entidade Student criada pelo associador de modelos do ASP.NET Core MVC ao conjunto
de entidades Student e, em seguida, salva as alterações no banco de dados. (Associador de modelos refere-se à
funcionalidade do ASP.NET Core MVC que facilita o trabalho com os dados enviados por um formulário. Um
associador de modelos converte os valores de formulário postados em tipos CLR e passa-os para o método de
ação em parâmetros. Nesse caso, o associador de modelos cria uma instância de uma entidade Student usando
valores de propriedade da coleção Form.)
Você removeu ID do atributo Bind porque a ID é o valor de chave primária que o SQL Server definirá
automaticamente quando a linha for inserida. A entrada do usuário não define o valor da ID.
Além do atributo Bind , o bloco try-catch é a única alteração que você fez no código gerado por scaffolding. Se
uma exceção que é derivada de DbUpdateException é capturada enquanto as alterações estão sendo salvas, uma
mensagem de erro genérica é exibida. Às vezes, as exceções DbUpdateException são causadas por algo externo ao
aplicativo, em vez de por um erro de programação e, portanto, o usuário é aconselhado a tentar novamente.
Embora não implementado nesta amostra, um aplicativo de qualidade de produção registrará a exceção em log.
Para obter mais informações, consulte a seção Log para informações em Monitoramento e telemetria (criando
aplicativos de nuvem do mundo real com o Azure).
O atributo ValidateAntiForgeryToken ajuda a impedir ataques CSRF (solicitação intersite forjada). O token é
injetado automaticamente na exibição pelo FormTagHelper e é incluído quando o formulário é enviado pelo
usuário. O token é validado pelo atributo ValidateAntiForgeryToken . Para obter mais informações sobre o CSRF,
consulte Falsificação antissolicitação.
Observação de segurança sobre o excesso de postagem
O atributo Bind que o código gerado por scaffolding inclui no método Create é uma maneira de proteger
contra o excesso de postagem em cenários de criação. Por exemplo, suponha que a entidade Student inclua uma
propriedade Secret que você não deseja que essa página da Web defina.
{
public string Secret { get; set; }
}
Mesmo se você não tiver um campo Secret na página da Web, um invasor poderá usar uma ferramenta como o
Fiddler ou escrever um JavaScript para postar um valor de formulário Secret . Sem o atributo Bind limitando
os campos que o associador de modelos usa quando ele cria uma instância de Student, o associador de modelos
seleciona esse valor de formulário Secret e usa-o para criar a instância da entidade Student. Em seguida, seja
qual for o valor que o invasor especificou para o campo de formulário Secret , ele é atualizado no banco de
dados. A imagem a seguir mostra a ferramenta Fiddler adicionando o campo Secret (com o valor "OverPost")
aos valores de formulário postados.
Em seguida, o valor "OverPost" é adicionado com êxito à propriedade Secret da linha inserida, embora você
nunca desejou que a página da Web pudesse definir essa propriedade.
Impeça o excesso de postagem em cenários de edição lendo a entidade do banco de dados primeiro e, em
seguida, chamando TryUpdateModel , passando uma lista explícita de propriedades permitidas. Esse é o método
usado nestes tutoriais.
Uma maneira alternativa de impedir o excesso de postagem preferida por muitos desenvolvedores é usar
modelos de exibição em vez de classes de entidade com o model binding. Inclua apenas as propriedades que
você deseja atualizar no modelo de exibição. Quando o associador de modelos MVC tiver concluído, copie as
propriedades do modelo de exibição para a instância da entidade, opcionalmente usando uma ferramenta como o
AutoMapper. Use _context.Entry na instância de entidade para definir seu estado como Unchanged e, em
seguida, defina Property("PropertyName").IsModified como verdadeiro em cada propriedade da entidade incluída
no modelo de exibição. Esse método funciona nos cenários de edição e criação.
Testar a página Criar
O código em Views/Students/Create.cshtml usa os auxiliares de marcação label , input e span (para
mensagens de validação) para cada campo.
Execute o aplicativo, selecione a guia Alunos e, em seguida, clique em Criar Novo.
Insira nomes e uma data. Tente inserir uma data inválida se o navegador permitir fazer isso. (Alguns navegadores
forçam o uso de um seletor de data.) Em seguida, clique em Criar para ver a mensagem de erro.
Essa é a validação do lado do servidor que você obtém por padrão; em um tutorial posterior, você verá como
adicionar atributos que gerarão o código para a validação do lado do cliente também. O código realçado a seguir
mostra a verificação de validação de modelo no método Create .
[HttpPost]
[Bind("EnrollmentDate,FirstMidName,LastName")] Student student)
{
try
{
{
_context.Add(student);
}
}
{
//Log the error (uncomment ex variable name and write a log.
"Try again, and if the problem persists " +
}
}
Altere a data para um valor válido e clique em Criar para ver o novo aluno ser exibido na página Índice.

Em StudentController.cs, o método HttpGet Edit (aquele sem o atributo HttpPost ) usa o método
SingleOrDefaultAsync para recuperar a entidade Student selecionada, como você viu no método Details . Não é
necessário alterar esse método.
Código HttpPost Edit recomendado: ler e atualizar
Substitua o método de ação HttpPost Edit pelo código a seguir.
[HttpPost, ActionName("Edit")]
public async Task<IActionResult> EditPost(int? id)
{
if (id == null)
{
return NotFound();
}
var studentToUpdate = await _context.Students.SingleOrDefaultAsync(s => s.ID == id);
studentToUpdate,
"",
{
try
{
}
{
"Try again, and if the problem persists, " +
}
}
return View(studentToUpdate);
}
Essas alterações implementam uma melhor prática de segurança para evitar o excesso de postagem. O scaffolder
gerou um atributo Bind e adicionou a entidade criada pelo associador de modelos ao conjunto de entidades com
um sinalizador Modified . Esse código não é recomendado para muitos cenários porque o atributo Bind limpa
os dados pré-existentes nos campos não listados no parâmetro Include .
O novo código lê a entidade existente e chama TryUpdateModel para atualizar os campos na entidade recuperada
com base na entrada do usuário nos dados de formulário postados. O controle automático de alterações do
Entity Framework define o sinalizador Modified nos campos alterados pela entrada de formulário. Quando o
método SaveChanges é chamado, o Entity Framework cria instruções SQL para atualizar a linha de banco de
dados. Os conflitos de simultaneidade são ignorados e somente as colunas de tabela que foram atualizadas pelo
usuário são atualizadas no banco de dados. (Um tutorial posterior mostra como lidar com conflitos de
simultaneidade.)
Como uma melhor prática para evitar o excesso de postagem, os campos que você deseja que sejam atualizáveis
pela página Editar estão na lista de permissões nos parâmetros TryUpdateModel . (A cadeia de caracteres vazia
antes da lista de campos na lista de parâmetros destina-se ao uso de um prefixo com os nomes de campos de
formulário.) Atualmente, não há nenhum campo extra que está sendo protegido, mas listar os campos que você
deseja que o associador de modelos associe garante que, se você adicionar campos ao modelo de dados no
futuro, eles serão automaticamente protegidos até que você adicione-os aqui de forma explícita.
Como resultado dessas alterações, a assinatura do método HttpPost Edit é a mesma do método HttpGet Edit ;
portanto, você já renomeou o método EditPost .
Código HttpPost Edit alternativo: criar e anexar
O código de edição HttpPost recomendado garante que apenas as colunas alteradas sejam atualizadas e preserva
os dados nas propriedades que você não deseja incluir para o model binding. No entanto, a abordagem de
primeira leitura exige uma leitura de banco de dados extra e pode resultar em um código mais complexo para
lidar com conflitos de simultaneidade. Uma alternativa é anexar uma entidade criada pelo associador de modelos
ao contexto do EF e marcá-la como modificada. (Não atualize o projeto com esse código; ele é mostrado somente
para ilustrar uma abordagem opcional.)
public async Task<IActionResult> Edit(int id, [Bind("ID,EnrollmentDate,FirstMidName,LastName")] Student

student)
{
if (id != student.ID)
{
return NotFound();
}
{
try
{
_context.Update(student);
}
{
}
}
}
Use essa abordagem quando a interface do usuário da página da Web incluir todos os campos na entidade e
puder atualizar qualquer um deles.
O código gerado por scaffolding usa a abordagem "criar e anexar", mas apenas captura exceções
DbUpdateConcurrencyException e retorna códigos de erro 404. O exemplo mostrado captura qualquer exceção de
atualização de banco de dados e exibe uma mensagem de erro.
Estados da entidade
O contexto de banco de dados controla se as entidades em memória estão em sincronia com suas linhas
correspondentes no banco de dados, e essas informações determinam o que acontece quando você chama o
método SaveChanges . Por exemplo, quando você passa uma nova entidade para o método Add , o estado dessa
entidade é definido como Added . Em seguida, quando você chama o método SaveChanges , o contexto de banco
de dados emite um comando SQL INSERT.
Uma entidade pode estar em um dos seguintes estados:
. A entidade ainda não existe no banco de dados. O método
Added SaveChanges emite uma instrução
INSERT.
Unchanged. Nada precisa ser feito com essa entidade pelo método SaveChanges . Ao ler uma entidade do
banco de dados, a entidade começa com esse status.
Modified . Alguns ou todos os valores de propriedade da entidade foram modificados. O método
SaveChanges emite uma instrução UPDATE.
Deleted . A entidade foi marcada para exclusão. O método SaveChanges emite uma instrução DELETE.
Detached . A entidade não está sendo controlada pelo contexto de banco de dados.
Em um aplicativo da área de trabalho, em geral, as alterações de estado são definidas automaticamente. Você lê
uma entidade e faz alterações em alguns de seus valores de propriedade. Isso faz com que seu estado da
entidade seja alterado automaticamente para Modified . Em seguida, quando você chama SaveChanges , o Entity
Framework gera uma instrução SQL UPDATE que atualiza apenas as propriedades reais que você alterou.
Em um aplicativo Web, o DbContext que inicialmente lê uma entidade e exibe seus dados a serem editados é
descartado depois que uma página é renderizada. Quando o método de ação HttpPost Edit é chamado, é feita
uma nova solicitação da Web e você tem uma nova instância do DbContext . Se você ler novamente a entidade
nesse novo contexto, simulará o processamento da área de trabalho.
Mas se você não desejar fazer a operação de leitura extra, precisará usar o objeto de entidade criado pelo
associador de modelos. A maneira mais simples de fazer isso é definir o estado da entidade como Modificado,
como é feito no código HttpPost Edit alternativo mostrado anteriormente. Em seguida, quando você chama
SaveChanges , o Entity Framework atualiza todas as colunas da linha de banco de dados, porque o contexto não
tem como saber quais propriedades foram alteradas.
Caso deseje evitar a abordagem de primeira leitura, mas também deseje que a instrução SQL UPDATE atualize
somente os campos que o usuário realmente alterar, o código será mais complexo. É necessário salvar os valores
originais de alguma forma (por exemplo, usando campos ocultos) para que eles estejam disponíveis quando o
método HttpPost Edit for chamado. Em seguida, você pode criar uma entidade Student usando os valores
originais, chamar o método Attach com a versão original da entidade, atualizar os valores da entidade para os
novos valores e, em seguida, chamar SaveChanges .
Testar a página Editar
Execute o aplicativo, selecione a guia Alunos e, em seguida, clique em um hiperlink Editar.
Altere alguns dos dados e clique em Salvar. A página Índice será aberta e você verá os dados alterados.

Em StudentController.cs, o código de modelo para o método HttpGet Delete usa o método
SingleOrDefaultAsync para recuperar a entidade Student selecionada, como você viu nos métodos Details e Edit.
No entanto, para implementar uma mensagem de erro personalizada quando a chamada a SaveChanges falhar,
você adicionará uma funcionalidade a esse método e à sua exibição correspondente.
Como você viu para operações de atualização e criação, as operações de exclusão exigem dois métodos de ação.
O método chamado em resposta a uma solicitação GET mostra uma exibição que dá ao usuário uma
oportunidade de aprovar ou cancelar a operação de exclusão. Se o usuário aprová-la, uma solicitação POST será
criada. Quando isso acontece, o método HttpPost Delete é chamado e, em seguida, esse método executa, de
fato, a operação de exclusão.
Você adicionará um bloco try-catch ao método HttpPost Delete para tratar os erros que podem ocorrer quando
o banco de dados é atualizado. Se ocorrer um erro, o método HttpPost Delete chamará o método HttpGet Delete,
passando a ele um parâmetro que indica que ocorreu um erro. Em seguida, o método HttpGet Delete exibe
novamente a página de confirmação, junto com a mensagem de erro, dando ao usuário a oportunidade de
cancelar ou tentar novamente.
Substitua o método de ação HttpGet Delete pelo código a seguir, que gerencia o relatório de erros.
public async Task<IActionResult> Delete(int? id, bool? saveChangesError = false)

{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
{
return NotFound();
}
if (saveChangesError.GetValueOrDefault())
{
ViewData["ErrorMessage"] =
"Delete failed. Try again, and if the problem persists " +
"see your system administrator.";
}
}
Este código aceita um parâmetro opcional que indica se o método foi chamado após uma falha ao salvar as
alterações. Esse parâmetro é falso quando o método HttpGet Delete é chamado sem uma falha anterior.
Quando ele é chamado pelo método HttpPost Delete em resposta a um erro de atualização de banco de dados,
o parâmetro é verdadeiro, e uma mensagem de erro é passada para a exibição.
A abordagem de primeira leitura para HttpPost Delete
Substitua o método de ação HttpPost Delete (chamado DeleteConfirmed ) pelo código a seguir, que executa a
operação de exclusão real e captura os erros de atualização de banco de dados.
{
.AsNoTracking()
{
}
try
{
_context.Students.Remove(student);
}
{
return RedirectToAction(nameof(Delete), new { id = id, saveChangesError = true });
}
}
Esse código recupera a entidade selecionada e, em seguida, chama o método Remove para definir o status da
entidade como Deleted . Quando SaveChanges é chamado, um comando SQL DELETE é gerado.
A abordagem "criar e anexar" para HttpPost Delete
Se a melhoria do desempenho de um aplicativo de alto volume for uma prioridade, você poderá evitar uma
consulta SQL desnecessária criando uma instância de uma entidade Student usando somente o valor de chave
primária e, em seguida, definindo o estado da entidade como Deleted . Isso é tudo o que o Entity Framework
precisa para excluir a entidade. (Não coloque esse código no projeto; ele está aqui apenas para ilustrar uma
alternativa.)
[HttpPost]
{
try
{
Student studentToDelete = new Student() { ID = id };
_context.Entry(studentToDelete).State = EntityState.Deleted;
}
{
return RedirectToAction(nameof(Delete), new { id = id, saveChangesError = true });
}
}
Se a entidade tiver dados relacionados, eles também deverão ser excluídos. Verifique se a exclusão em cascata
está configurada no banco de dados. Com essa abordagem para a exclusão de entidade, o EF talvez não perceba
que há entidades relacionadas a serem excluídas.
Atualizar a exibição Excluir
Em Views/Student/Delete.cshtml, adicione uma mensagem de erro entre o cabeçalho h2 e o cabeçalho h3,
<h2>Delete</h2>
<p class="text-danger">@ViewData["ErrorMessage"]</p>
Execute o aplicativo, selecione a guia Alunos e, em seguida, clique em um hiperlink Excluir:
Clique em Excluir. A página Índice será exibida sem o aluno excluído. (Você verá um exemplo de código de
tratamento de erro em ação no tutorial sobre simultaneidade.)
Fechando conexões de banco de dados

Para liberar os recursos contidos em uma conexão de banco de dados, a instância de contexto precisa ser
descartada assim que possível quando você tiver terminado. A injeção de dependência interna do ASP.NET Core
cuida dessa tarefa para você.
Em Startup.cs, chame o método de extensão AddDbContext para provisionar a classe DbContext no contêiner de
DI do ASP.NET Core. Esse método define o tempo de vida do serviço como Scoped por padrão. Scoped significa
que o tempo de vida do objeto de contexto coincide com o tempo de vida da solicitação da Web, e o método
Dispose será chamado automaticamente ao final da solicitação da Web.
Manipulando transações
Por padrão, o Entity Framework implementa transações de forma implícita. Em cenários em que são feitas
alterações em várias linhas ou tabelas e, em seguida, SaveChanges é chamado, o Entity Framework verifica
automaticamente se todas as alterações tiveram êxito ou se falharam. Se algumas alterações forem feitas pela
primeira vez e, em seguida, ocorrer um erro, essas alterações serão revertidas automaticamente. Para cenários
em que você precisa de mais controle – por exemplo, se desejar incluir operações feitas fora do Entity Framework
em uma transação –, consulte Transações.
Consultas sem controle

Quando um contexto de banco de dados recupera linhas de tabela e cria objetos de entidade que as representam,
por padrão, ele controla se as entidades em memória estão em sincronia com o que está no banco de dados. Os
dados em memória atuam como um cache e são usados quando uma entidade é atualizada. Esse cache costuma
ser desnecessário em um aplicativo Web porque as instâncias de contexto são normalmente de curta duração
(uma nova é criada e descartada para cada solicitação) e o contexto que lê uma entidade normalmente é
descartado antes que essa entidade seja usada novamente.
Desabilite o controle de objetos de entidade em memória chamando o método AsNoTracking . Os cenários típicos
em que talvez você deseje fazer isso incluem os seguintes:
Durante o tempo de vida do contexto, não é necessário atualizar entidades nem que o EF carregue
automaticamente as propriedades de navegação com entidades recuperadas por consultas separadas.
Com frequência, essas condições são atendidas nos métodos de ação HttpGet de um controlador.
Você está executando uma consulta que recupera um volume grande de dados e apenas uma pequena
parte dos dados retornados será atualizada. Pode ser mais eficiente desativar o controle para a consulta
grande e executar uma consulta posteriormente para as poucas entidades que precisam ser atualizadas.
Você deseja anexar uma entidade para atualizá-la, mas anteriormente, recuperou a mesma entidade para
uma finalidade diferente. Como a entidade já está sendo controlada pelo contexto de banco de dados, não
é possível anexar a entidade que você deseja alterar. Uma maneira de lidar com essa situação é chamar
AsNoTracking na consulta anterior.
Para obter mais informações, consulte Controle vs. Sem controle.
Resumo
Agora, você tem um conjunto completo de páginas que executam operações CRUD simples para entidades
Student. No próximo tutorial, você expandirá a funcionalidade da página Índice adicionando classificação,
filtragem e paginação.
ASP.NET Core MVC com EF Core – classificação,
filtro, paginação – 3 de 10
2.0.
Páginas do Razor:
No tutorial anterior, você implementou um conjunto de páginas da Web para operações CRUD básicas para
entidades Student. Neste tutorial você adicionará as funcionalidades de classificação, filtragem e paginação à
página Índice de Alunos. Você também criará uma página que faz um agrupamento simples.
A ilustração a seguir mostra a aparência da página quando você terminar. Os títulos de coluna são links que o
usuário pode clicar para classificar por essa coluna. Clicar em um título de coluna alterna repetidamente entre a
ordem de classificação ascendente e descendente.
Adicionar links de classificação de coluna à página Índice de Alunos
Para adicionar uma classificação à página Índice de Alunos, você alterará o método Index do controlador Alunos
e adicionará o código à exibição Índice de Alunos.
Adicionar a funcionalidade de classificação ao método Index
Em StudentsController.cs, substitua o método Index pelo seguinte código:
public async Task<IActionResult> Index(string sortOrder)

{
ViewData["NameSortParm"] = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
ViewData["DateSortParm"] = sortOrder == "Date" ? "date_desc" : "Date";
var students = from s in _context.Students
select s;
switch (sortOrder)
{
case "name_desc":
students = students.OrderByDescending(s => s.LastName);
break;
case "Date":
students = students.OrderBy(s => s.EnrollmentDate);
break;
case "date_desc":
students = students.OrderByDescending(s => s.EnrollmentDate);
break;
default:
students = students.OrderBy(s => s.LastName);
break;
}
return View(await students.AsNoTracking().ToListAsync());
}
Esse código recebe um parâmetro sortOrder da cadeia de caracteres de consulta na URL. O valor de cadeia de
caracteres de consulta é fornecido pelo ASP.NET Core MVC como um parâmetro para o método de ação. O
parâmetro será uma cadeia de caracteres "Name" ou "Date", opcionalmente, seguido de um sublinhado e a
cadeia de caracteres "desc" para especificar a ordem descendente. A ordem de classificação crescente é padrão.
Na primeira vez que a página Índice é solicitada, não há nenhuma cadeia de caracteres de consulta. Os alunos são
exibidos em ordem ascendente por sobrenome, que é o padrão, conforme estabelecido pelo caso fall-through na
instrução switch . Quando o usuário clica em um hiperlink de título de coluna, o valor sortOrder apropriado é
fornecido na cadeia de caracteres de consulta.
Os dois elementos ViewData (NameSortParm e DateSortParm) são usados pela exibição para configurar os
hiperlinks de título de coluna com os valores de cadeia de caracteres de consulta apropriados.
public async Task<IActionResult> Index(string sortOrder)

{
select s;
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}
}
Essas são instruções ternárias. A primeira delas especifica que o parâmetro sortOrder é nulo ou vazio,
NameSortParm deve ser definido como "name_desc"; caso contrário, ele deve ser definido como uma cadeia de
caracteres vazia. Essas duas instruções permitem que a exibição defina os hiperlinks de título de coluna da
seguinte maneira:
ORDEM DE CLASSIFICAÇÃO ATUAL HIPERLINK DO SOBRENOME HIPERLINK DE DATA
Sobrenome ascendente descending ascending
Sobrenome descendente ascending ascending
Data ascendente ascending descending
Data descendente ascending ascending
O método usa o LINQ to Entities para especificar a coluna pela qual classificar. O código cria uma variável
IQueryable antes da instrução switch, modifica-a na instrução switch e chama o método ToListAsync após a
instrução switch . Quando você cria e modifica variáveis IQueryable , nenhuma consulta é enviada para o banco
de dados. A consulta não é executada até que você converta o objeto IQueryable em uma coleção chamando um
método, como ToListAsync . Portanto, esse código resulta em uma única consulta que não é executada até a
instrução return View .
Este código pode ficar detalhado com um grande número de colunas. O último tutorial desta série mostra como
escrever um código que permite que você passe o nome da coluna OrderBy em uma variável de cadeia de
caracteres.
Adicionar hiperlinks de título de coluna à exibição Índice de Alunos
Substitua o código em Views/Students/Index.cshtml pelo código a seguir para adicionar hiperlinks de título de
coluna. As linhas alteradas são realçadas.
@model IEnumerable<ContosoUniversity.Models.Student>
@{
}
<h2>Index</h2>
<p>
</p>
<thead>
<tr>
<th>
<a asp-action="Index" asp-route-
sortOrder="@ViewData["NameSortParm"]">@Html.DisplayNameFor(model => model.LastName)</a>
</th>
<th>
@Html.DisplayNameFor(model => model.FirstMidName)
</th>
<th>
<a asp-action="Index" asp-route-
sortOrder="@ViewData["DateSortParm"]">@Html.DisplayNameFor(model => model.EnrollmentDate)</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
Esse código usa as informações nas propriedades ViewData para configurar hiperlinks com os valores de cadeia
de caracteres de consulta apropriados.
Execute o aplicativo, selecione a guia Alunos e, em seguida, clique nos títulos de coluna Sobrenome e Data de
Registro para verificar se a classificação funciona.
Adicionar uma Caixa de Pesquisa à página Índice de Alunos
Para adicionar a filtragem à página Índice de Alunos, você adicionará uma caixa de texto e um botão Enviar à
exibição e fará alterações correspondentes no método Index . A caixa de texto permitirá que você insira uma
cadeia de caracteres a ser pesquisada nos campos de nome e sobrenome.
Adicionar a funcionalidade de filtragem a método Index
Em StudentsController.cs, substitua o método Index pelo código a seguir (as alterações são realçadas).
public async Task<IActionResult> Index(string sortOrder, string searchString)

{
ViewData["CurrentFilter"] = searchString;

select s;
{
students = students.Where(s => s.LastName.Contains(searchString)
}
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}
}
Você adicionou um parâmetro searchString ao método Index . O valor de cadeia de caracteres de pesquisa é
recebido em uma caixa de texto que você adicionará à exibição Índice. Você também adicionou à instrução LINQ
uma cláusula Where, que seleciona somente os alunos cujo nome ou sobrenome contém a cadeia de caracteres
de pesquisa. A instrução que adiciona a cláusula Where é executada somente se há um valor a ser pesquisado.
NOTE
Aqui você está chamando o método Where em um objeto IQueryable , e o filtro será processado no servidor. Em alguns
cenários, você pode chamar o método Where como um método de extensão em uma coleção em memória. (Por exemplo,
suponha que você altere a referência a _context.Students , de modo que em vez de um DbSet do EF, ela referencie um
método de repositório que retorna uma coleção IEnumerable .) O resultado normalmente é o mesmo, mas em alguns
casos pode ser diferente.
Por exemplo, a implementação do .NET Framework do método Contains executa uma comparação que diferencia
maiúsculas de minúsculas por padrão, mas no SQL Server, isso é determinado pela configuração de agrupamento da
instância do SQL Server. Por padrão, essa configuração diferencia maiúsculas de minúsculas. Você pode chamar o método
ToUpper para fazer com que o teste diferencie maiúsculas de minúsculas de forma explícita: Where(s =>
s.LastName.ToUpper().Contains (searchString.ToUpper()). Isso garantirá que os resultados permaneçam os mesmos se você
alterar o código mais tarde para usar um repositório que retorna uma coleção IEnumerable em vez de um objeto
IQueryable . (Quando você chama o método Contains em uma coleção IEnumerable , obtém a implementação do
.NET Framework; quando chama-o em um objeto IQueryable , obtém a implementação do provedor de banco de dados.)
No entanto, há uma penalidade de desempenho para essa solução. O código ToUpper colocará uma função na cláusula
WHERE da instrução TSQL SELECT. Isso pode impedir que o otimizador use um índice. Considerando que o SQL geralmente
é instalado como não diferenciando maiúsculas e minúsculas, é melhor evitar o código ToUpper até você migrar para um
armazenamento de dados que diferencia maiúsculas de minúsculas.
Adicionar uma Caixa de Pesquisa à exibição Índice de Alunos

Em Views/Student/Index.cshtml, adicione o código realçado imediatamente antes da marcação de tabela de
abertura para criar uma legenda, uma caixa de texto e um botão Pesquisar.
<p>
</p>
<form asp-action="Index" method="get">

<p>
Find by name: <input type="text" name="SearchString" value="@ViewData["currentFilter"]" />
<a asp-action="Index">Back to Full List</a>
</p>
</div>
</form>
Esse código usa o auxiliar de marcação <form> para adicionar o botão e a caixa de texto de pesquisa. Por padrão,
o auxiliar de marcação <form> envia dados de formulário com um POST, o que significa que os parâmetros são
passados no corpo da mensagem HTTP e não na URL como cadeias de consulta. Quando você especifica HTTP
GET, os dados de formulário são passados na URL como cadeias de consulta, o que permite aos usuários marcar
a URL. As diretrizes do W3C recomendam o uso de GET quando a ação não resulta em uma atualização.
Execute o aplicativo, selecione a guia Alunos, insira uma cadeia de caracteres de pesquisa e clique em Pesquisar
para verificar se a filtragem está funcionando.
Observe que a URL contém a cadeia de caracteres de pesquisa.
http://localhost:5813/Students?SearchString=an
Se você marcar essa página, obterá a lista filtrada quando usar o indicador. A adição de method="get" à marcação
form é o que fez com que a cadeia de caracteres de consulta fosse gerada.
Neste estágio, se você clicar em um link de classificação de título de coluna perderá o valor de filtro inserido na
caixa Pesquisa. Você corrigirá isso na próxima seção.
Adicionar a funcionalidade de paginação à página Índice de Alunos

Para adicionar a paginação à página Índice de alunos, você criará uma classe PaginatedList que usa as
instruções Skip e Take para filtrar os dados no servidor, em vez de recuperar sempre todas as linhas da tabela.
Em seguida, você fará outras alterações no método Index e adicionará botões de paginação à exibição Index . A
ilustração a seguir mostra os botões de paginação.
Na pasta do projeto, crie PaginatedList.cs e, em seguida, substitua o código de modelo pelo código a seguir.
using System;
using System.Linq;
{
public class PaginatedList<T> : List<T>
{
public int PageIndex { get; private set; }
public int TotalPages { get; private set; }
public PaginatedList(List<T> items, int count, int pageIndex, int pageSize)

{
PageIndex = pageIndex;
TotalPages = (int)Math.Ceiling(count / (double)pageSize);
this.AddRange(items);
}
public bool HasPreviousPage

{
get
{
return (PageIndex > 1);
}
}
public bool HasNextPage

{
get
{
return (PageIndex < TotalPages);
}
}
public static async Task<PaginatedList<T>> CreateAsync(IQueryable<T> source, int pageIndex, int

pageSize)
{
var count = await source.CountAsync();
var items = await source.Skip((pageIndex - 1) * pageSize).Take(pageSize).ToListAsync();
return new PaginatedList<T>(items, count, pageIndex, pageSize);
}
}
}
O método CreateAsync nesse código usa o tamanho da página e o número da página e aplica as instruções
Skip e Take ao IQueryable . Quando ToListAsync for chamado no IQueryable , ele retornará uma Lista que
contém somente a página solicitada. As propriedades HasPreviousPage e HasNextPage podem ser usadas para
habilitar ou desabilitar os botões de paginação Anterior e Próximo.
Um método CreateAsync é usado em vez de um construtor para criar o objeto PaginatedList<T> , porque os
construtores não podem executar um código assíncrono.
Adicionar a funcionalidade de paginação ao método Index

Em StudentsController.cs, substitua o método Index pelo código a seguir.
public async Task<IActionResult> Index(
string sortOrder,
string currentFilter,
string searchString,
int? page)
{
ViewData["CurrentSort"] = sortOrder;
{
page = 1;
}
else
{
}

select s;
{
}
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}
int pageSize = 3;
return View(await PaginatedList<Student>.CreateAsync(students.AsNoTracking(), page ?? 1, pageSize));
}
Esse código adiciona um parâmetro de número de página, um parâmetro de ordem de classificação atual e um
parâmetro de filtro atual à assinatura do método.

string sortOrder,
int? page)
Na primeira vez que a página for exibida, ou se o usuário ainda não tiver clicado em um link de paginação ou
classificação, todos os parâmetros serão nulos. Se um link de paginação receber um clique, a variável de página
conterá o número da página a ser exibido.
O elemento ViewData chamado CurrentSort fornece à exibição a ordem de classificação atual, pois isso precisa
ser incluído nos links de paginação para manter a ordem de classificação igual durante a paginação.
O elemento ViewData chamado CurrentFilter fornece à exibição a cadeia de caracteres de filtro atual. Esse valor
precisa ser incluído nos links de paginação para manter as configurações de filtro durante a paginação e precisa
ser restaurado para a caixa de texto quando a página é exibida novamente.
Se a cadeia de caracteres de pesquisa for alterada durante a paginação, a página precisará ser redefinida como 1,
porque o novo filtro pode resultar na exibição de dados diferentes. A cadeia de caracteres de pesquisa é alterada
quando um valor é inserido na caixa de texto e o botão Enviar é pressionado. Nesse caso, o parâmetro
searchString não é nulo.
{
page = 1;
}
else
{
}
Ao final do método Index , o método PaginatedList.CreateAsync converte a consulta de alunos em uma única
página de alunos de um tipo de coleção compatível com paginação. A única página de alunos é então passada
para a exibição.
return View(await PaginatedList<Student>.CreateAsync(students.AsNoTracking(), page ?? 1, pageSize));
O método PaginatedList.CreateAsync usa um número de página. Os dois pontos de interrogação representam o

operador de união de nulo. O operador de união de nulo define um valor padrão para um tipo que permite valor
nulo; a expressão (page ?? 1) significa retornar o valor de page se ele tiver um valor ou retornar 1 se page for
nulo.
Adicionar links de paginação à exibição Índice de Alunos

Em Views/Students/Index.cshtml, substitua o código existente pelo código a seguir. As alterações são realçadas.
@model PaginatedList<ContosoUniversity.Models.Student>
@{
}
<h2>Index</h2>
<p>
</p>
<form asp-action="Index" method="get">

<p>
Find by name: <input type="text" name="SearchString" value="@ViewData["currentFilter"]" />
<a asp-action="Index">Back to Full List</a>
</p>
</div>
</form>
<thead>
<tr>
<th>
<a asp-action="Index" asp-route-sortOrder="@ViewData["NameSortParm"]" asp-route-
<a asp-action="Index" asp-route-sortOrder="@ViewData["NameSortParm"]" asp-route-
currentFilter="@ViewData["CurrentFilter"]">Last Name</a>
</th>
<th>
First Name
</th>
<th>
<a asp-action="Index" asp-route-sortOrder="@ViewData["DateSortParm"]" asp-route-
currentFilter="@ViewData["CurrentFilter"]">Enrollment Date</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
@{
var prevDisabled = !Model.HasPreviousPage ? "disabled" : "";
var nextDisabled = !Model.HasNextPage ? "disabled" : "";
}
<a asp-action="Index"
asp-route-sortOrder="@ViewData["CurrentSort"]"
asp-route-page="@(Model.PageIndex - 1)"
asp-route-currentFilter="@ViewData["CurrentFilter"]"
Previous
</a>
asp-route-page="@(Model.PageIndex + 1)"
Next
</a>
A instrução @modelna parte superior da página especifica que a exibição agora obtém um objeto
PaginatedList<T> , em vez de um objeto List<T> .
Os links de cabeçalho de coluna usam a cadeia de caracteres de consulta para passar a cadeia de caracteres de
pesquisa atual para o controlador, de modo que o usuário possa classificar nos resultados do filtro:
<a asp-action="Index" asp-route-sortOrder="@ViewData["DateSortParm"]" asp-route-currentFilter

="@ViewData["CurrentFilter"]">Enrollment Date</a>
Os botões de paginação são exibidos por auxiliares de marcação:

asp-route-page="@(Model.PageIndex - 1)"
Previous
</a>
Execute o aplicativo e acesse a página Alunos.
Clique nos links de paginação em ordens de classificação diferentes para verificar se a paginação funciona. Em
seguida, insira uma cadeia de caracteres de pesquisa e tente fazer a paginação novamente para verificar se ela
também funciona corretamente com a classificação e filtragem.
Criar uma página Sobre que mostra as estatísticas de Alunos

Para a página Sobre do site da Contoso University, você exibirá quantos alunos se registraram para cada data de
registro. Isso exige agrupamento e cálculos simples nos grupos. Para fazer isso, você fará o seguinte:
Criar uma classe de modelo de exibição para os dados que você precisa passar para a exibição.
Modificar o método About no controlador Home.
Modificar a exibição Sobre.
Criar o modelo de exibição
Crie uma pasta SchoolViewModels na pasta Models.
Na nova pasta, adicione um arquivo de classe EnrollmentDateGroup.cs e substitua o código de modelo pelo
seguinte código:
using System;
{
public class EnrollmentDateGroup
{
public DateTime? EnrollmentDate { get; set; }
public int StudentCount { get; set; }

}
}
Modificar o controlador Home

Em HomeController.cs, adicione o seguinte usando as instruções na parte superior do arquivo:
Adicione uma variável de classe ao contexto de banco de dados imediatamente após a chave de abertura da
classe e obtenha uma instância do contexto da DI do ASP.NET Core:

{
public HomeController(SchoolContext context)

{
_context = context;
}
Substitua o método About pelo seguinte código:
public async Task<ActionResult> About()

{
IQueryable<EnrollmentDateGroup> data =
from student in _context.Students
group student by student.EnrollmentDate into dateGroup
select new EnrollmentDateGroup()
{
EnrollmentDate = dateGroup.Key,
StudentCount = dateGroup.Count()
};
return View(await data.AsNoTracking().ToListAsync());
}
A instrução LINQ agrupa as entidades de alunos por data de registro, calcula o número de entidades em cada
grupo e armazena os resultados em uma coleção de objetos de modelo de exibição EnrollmentDateGroup .
NOTE
Na versão 1.0 do Entity Framework Core, todo o conjunto de resultados é retornado para o cliente e o agrupamento é feito
no cliente. Em alguns cenários, isso pode criar problemas de desempenho. Teste o desempenho com volumes de dados de
produção e, se necessário, use o SQL bruto para fazer o agrupamento no servidor. Para obter informações sobre como usar
o SQL bruto, veja o último tutorial desta série.
Modificar a exibição Sobre
Substitua o código no arquivo Views/Home/About.cshtml pelo seguinte código:
@model IEnumerable<ContosoUniversity.Models.SchoolViewModels.EnrollmentDateGroup>
@{
ViewData["Title"] = "Student Body Statistics";
}
<h2>Student Body Statistics</h2>
<table>
<tr>
<th>
Enrollment Date
</th>
<th>
Students
</th>
</tr>

{
<tr>
<td>
</td>
<td>
@item.StudentCount
</td>
</tr>
}
</table>
Execute o aplicativo e acesse a página Sobre. A contagem de alunos para cada data de registro é exibida em uma
tabela.
Resumo
Neste tutorial, você viu como realizar classificação, filtragem, paginação e agrupamento. No próximo tutorial,
você aprenderá a manipular as alterações do modelo de dados usando migrações.
ASP.NET Core MVC com EF Core – migrações – 4
de 10
versão 2.0.
O tutorial do 2.0 ensina a usar o ASP.NET Core MVC e o Entity Framework Core com controladores e
exibições. O Razor Pages é um modelo de programação baseado em página que torna a criação da interface do
usuário da Web mais fácil e produtiva. É recomendável tentar o tutorial das Páginas Razor na versão do MVC. O
Neste tutorial, você começa usando o recurso de migrações do EF Core para o gerenciamento de alterações do
modelo de dados. Em tutoriais seguintes, você adicionará mais migrações conforme você alterar o modelo de
dados.
Introdução às migrações
Quando você desenvolve um novo aplicativo, o modelo de dados é alterado com frequência e, sempre que o
modelo é alterado, ele fica fora de sincronia com o banco de dados. Você começou estes tutoriais configurando
o Entity Framework para criar o banco de dados, caso ele não exista. Em seguida, sempre que você alterar o
modelo de dados – adicionar, remover, alterar classes de entidade ou alterar a classe DbContext –, poderá excluir
o banco de dados e o EF criará um novo que corresponde ao modelo e o propagará com os dados de teste.
Esse método de manter o banco de dados em sincronia com o modelo de dados funciona bem até que você
implante o aplicativo em produção. Quando o aplicativo é executado em produção, ele normalmente armazena
os dados que você deseja manter, e você não quer perder tudo sempre que fizer uma alteração, como a adição
de uma nova coluna. O recurso Migrações do EF Core resolve esse problema, permitindo que o EF atualize o
esquema de banco de dados em vez de criar um novo banco de dados.

Para trabalhar com migrações, use o PMC (Console do Gerenciador de Pacotes) ou a CLI (interface de linha de
comando). Esses tutoriais mostram como usar comandos da CLI. Encontre informações sobre o PMC no final
deste tutorial.
Microsoft.EntityFrameworkCore.Tools.DotNet. Para instalar esse pacote, adicione-o à coleção
DotNetCliToolReference no arquivo .csproj, conforme mostrado. Observação: é necessário instalar este pacote
editando o arquivo .csproj; não é possível usar o comando install-package ou a GUI do Gerenciador de
Pacotes. Edite o arquivo .csproj clicando com o botão direito do mouse no nome do projeto no Gerenciador de
Soluções e selecionando Editar ContosoUniversity.csproj.
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0" />
</ItemGroup>
(Neste exemplo, os números de versão eram atuais no momento em que o tutorial foi escrito.)
Alterar a cadeia de conexão

No arquivo appsettings.json, altere o nome do banco de dados na cadeia de conexão para ContosoUniversity2
ou outro nome que você ainda não usou no computador que está sendo usado.
{
},
Essa alteração configura o projeto, de modo que a primeira migração crie um novo banco de dados. Isso não é
necessário para começar as migrações, mas você verá mais tarde o motivo pelo qual essa é uma boa ideia.
NOTE
Como alternativa à alteração do nome do banco de dados, você pode excluir o banco de dados. Use o SSOX (Pesquisador
de Objetos do SQL Server) ou o comando database drop da CLI:
A seção a seguir explica como executar comandos da CLI.
Criar uma migração inicial

Salve as alterações e compile o projeto. Em seguida, abra uma janela Comando e navegue para a pasta do
projeto. Esta é uma maneira rápida de fazer isso:
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e escolha Abrir no
Explorador de Arquivos no menu de contexto.
Insira "cmd" na barra de endereços e pressione Enter.
Insira o seguinte comando na janela de comando:
Você verá uma saída semelhante à seguinte na janela Comando:
info: Microsoft.AspNetCore.DataProtection.KeyManagement.XmlKeyManager[0]
User profile is available. Using 'C:\Users\username\AppData\Local\ASP.NET\DataProtection-Keys' as key
repository and Windows DPAPI to encrypt keys at rest.
info: Microsoft.EntityFrameworkCore.Infrastructure[100403]
Entity Framework Core 2.0.0-rtm-26452 initialized 'SchoolContext' using provider
'Microsoft.EntityFrameworkCore.SqlServer' with options: None
NOTE
Se você receber uma mensagem de erro Nenhum comando "dotnet-ef" executável correspondente encontrado, consulte
esta postagem no blog para ajudar a solucionar o problema.
Se você receber uma mensagem de erro "Não é possível acessar o arquivo... ContosoUniversity.dll porque ele
está sendo usado por outro processo", localize o ícone do IIS Express na Bandeja do Sistema do Windows,
clique com o botão direito do mouse nele e, em seguida, clique em ContosoUniversity > Parar Site.
Examinar os métodos Up e Down
Quando você executou o comando migrations add , o EF gerou o código que criará o banco de dados do zero.
Esse código está localizado na pasta Migrations, no arquivo chamado <timestamp>_InitialCreate.cs. O método
Up da classe InitialCreate cria as tabelas de banco de dados que correspondem aos conjuntos de entidades
do modelo de dados, e o método Down exclui-as, conforme mostrado no exemplo a seguir.
public partial class InitialCreate : Migration

{
{
name: "Course",
{
CourseID = table.Column<int>(nullable: false),
Credits = table.Column<int>(nullable: false),
Title = table.Column<string>(nullable: true)
},
{
table.PrimaryKey("PK_Course", x => x.CourseID);
});
// Additional code not shown

}
protected override void Down(MigrationBuilder migrationBuilder)

{
name: "Enrollment");
// Additional code not shown
}
}
As migrações chamam o método Up para implementar as alterações do modelo de dados para uma migração.
Quando você insere um comando para reverter a atualização, as Migrações chamam o método Down .
Esse código destina-se à migração inicial que foi criada quando você inseriu o comando
migrations add InitialCreate . O parâmetro de nome da migração ("InitialCreate" no exemplo) é usado para o
nome do arquivo e pode ser o que você desejar. É melhor escolher uma palavra ou frase que resume o que está
sendo feito na migração. Por exemplo, você pode nomear uma migração posterior "AddDepartmentTable".
Se você criou a migração inicial quando o banco de dados já existia, o código de criação de banco de dados é
gerado, mas ele não precisa ser executado porque o banco de dados já corresponde ao modelo de dados.
Quando você implantar o aplicativo em outro ambiente no qual o banco de dados ainda não existe, esse código
será executado para criar o banco de dados; portanto, é uma boa ideia testá-lo primeiro. É por isso que você
alterou o nome do banco de dados na cadeia de conexão anteriormente – para que as migrações possam criar
um novo do zero.
O instantâneo do modelo de dados

As migrações criam um instantâneo do esquema de banco de dados atual em
Migrations/SchoolContextModelSnapshot.cs. Quando você adiciona uma migração, o EF determina o que foi
alterado, comparando o modelo de dados com o arquivo de instantâneo.
Ao excluir uma migração, use o comando dotnet ef migrations remove. dotnet ef migrations remove exclui a
migração e garante que o instantâneo seja redefinido corretamente.
Confira Migrações do EF Core em ambientes de equipe para obter mais informações de como o arquivo de
instantâneo é usado.
Aplicar a migração ao banco de dados

Na janela Comando, insira o comando a seguir para criar o banco de dados e tabelas nele.
A saída do comando é semelhante ao comando migrations add , exceto que os logs para os comandos SQL que
configuram o banco de dados são exibidos. A maioria dos logs é omitida na seguinte saída de exemplo. Se você
preferir não ver esse nível de detalhe em mensagens de log, altere o nível de log no arquivo
appsettings.Development.json. Para obter mais informações, consulte Registro em log no ASP.NET Core.
info: Microsoft.AspNetCore.DataProtection.KeyManagement.XmlKeyManager[0]
User profile is available. Using 'C:\Users\username\AppData\Local\ASP.NET\DataProtection-Keys' as key
repository and Windows DPAPI to encrypt keys at rest.
info: Microsoft.EntityFrameworkCore.Infrastructure[100403]
Entity Framework Core 2.0.0-rtm-26452 initialized 'SchoolContext' using provider
'Microsoft.EntityFrameworkCore.SqlServer' with options: None
info: Microsoft.EntityFrameworkCore.Database.Command[200101]
Executed DbCommand (467ms) [Parameters=[], CommandType='Text', CommandTimeout='60']
CREATE DATABASE [ContosoUniversity2];
CREATE TABLE [__EFMigrationsHistory] (
[MigrationId] nvarchar(150) NOT NULL,
[ProductVersion] nvarchar(32) NOT NULL,
CONSTRAINT [PK___EFMigrationsHistory] PRIMARY KEY ([MigrationId])
);
<logs omitted for brevity>
INSERT INTO [__EFMigrationsHistory] ([MigrationId], [ProductVersion])
VALUES (N'20170816151242_InitialCreate', N'2.0.0-rtm-26452');
Done.
Use o Pesquisador de Objetos do SQL Server para inspecionar o banco de dados como você fez no primeiro
tutorial. Você observará a adição de uma tabela __EFMigrationsHistory que controla quais migrações foram
aplicadas ao banco de dados. Exiba os dados dessa tabela e você verá uma linha para a primeira migração. (O
último log no exemplo de saída da CLI anterior mostra a instrução INSERT que cria essa linha.)
Execute o aplicativo para verificar se tudo ainda funciona como antes.
CLI (interface de linha de comando) vs. PMC (Console do
Gerenciador de Pacotes)
As ferramentas do EF para gerenciamento de migrações estão disponíveis por meio dos comandos da CLI do
.NET Core ou de cmdlets do PowerShell na janela PMC (Console do Gerenciador de Pacotes) do Visual Studio.
Este tutorial mostra como usar a CLI, mas você poderá usar o PMC se preferir.
Os comandos do EF para os comandos do PMC estão no pacote Microsoft.EntityFrameworkCore.Tools. Esse
pacote está incluído no metapacote Microsoft.AspNetCore.App, portanto você não precisa adicionar uma
referência de pacote se o aplicativo tem uma referência de pacote ao Microsoft.AspNetCore.App .
Importante: esse não é o mesmo pacote que é instalado para a CLI com a edição do arquivo .csproj. O nome
deste termina com Tools , ao contrário do nome do pacote da CLI que termina com Tools.DotNet .
Para obter mais informações sobre os comandos da CLI, consulte CLI do .NET Core.
Para obter mais informações sobre os comandos do PMC, consulte Console do Gerenciador de Pacotes (Visual
Studio).
Resumo
Neste tutorial, você viu como criar e aplicar sua primeira migração. No próximo tutorial, você começará
examinando tópicos mais avançados com a expansão do modelo de dados. Ao longo do processo, você criará e
aplicará migrações adicionais.
ASP.NET Core MVC com EF Core – modelo de
dados – 5 de 10
versão 2.0.
Páginas do Razor:
Nos tutoriais anteriores, você trabalhou com um modelo de dados simples composto por três entidades. Neste
tutorial, você adicionará mais entidades e relações e personalizará o modelo de dados especificando formatação,
validação e regras de mapeamento de banco de dados.
Quando terminar, as classes de entidade formarão o modelo de dados concluído mostrado na seguinte
ilustração:
Personalizar o modelo de dados usando atributos
Nesta seção, você verá como personalizar o modelo de dados usando atributos que especificam formatação,
validação e regras de mapeamento de banco de dados. Em seguida, em várias seções a seguir, você criará o
modelo de dados Escola completo com a adição de atributos às classes já criadas e criação de novas classes para
os demais tipos de entidade no modelo.
O atributo DataType
Para datas de registro de alunos, todas as páginas da Web atualmente exibem a hora junto com a data, embora
tudo o que você deseje exibir nesse campo seja a data. Usando atributos de anotação de dados, você pode fazer
uma alteração de código que corrigirá o formato de exibição em cada exibição que mostra os dados. Para ver um
exemplo de como fazer isso, você adicionará um atributo à propriedade EnrollmentDate na classe Student .
Em Models/Student.cs, adicione uma instrução using ao namespace System.ComponentModel.DataAnnotations e
adicione os atributos DataType e DisplayFormat à EnrollmentDate propriedade, conforme mostrado no seguinte
exemplo:
using System;
{
{

}
}
O atributo DataType é usado para especificar um tipo de dados mais específico do que o tipo intrínseco de
banco de dados. Nesse caso, apenas desejamos acompanhar a data, não a data e a hora. A Enumeração
DataType fornece muitos tipos de dados, como Date, Time, PhoneNumber, Currency, EmailAddress e muito
mais. O atributo DataType também pode permitir que o aplicativo forneça automaticamente recursos
específicos a um tipo. Por exemplo, um link mailto: pode ser criado para DataType.EmailAddress e um seletor
de data pode ser fornecido para DataType.Date em navegadores que dão suporte a HTML5. O atributo
DataType emite atributos data- HTML 5 (pronunciados “data dash”) que são reconhecidos pelos navegadores
HTML 5. Os atributos DataType não fornecem nenhuma validação.
exibido em uma caixa de texto para edição. (Talvez você não deseje ter isso em alguns campos – por exemplo,
para valores de moeda, provavelmente, você não deseja exibir o símbolo de moeda na caixa de texto para
edição.)
Use Você pode usar o atributo DisplayFormat por si só, mas geralmente é uma boa ideia usar o atributo
DataType também. O atributo DataType transmite a semântica dos dados, ao invés de apresentar como
renderizá-lo em uma tela, e oferece os seguintes benefícios que você não obtém com DisplayFormat :
símbolo de moeda apropriado à localidade, links de email, uma validação de entrada do lado do cliente,
etc.).
Para obter mais informações, consulte a documentação do auxiliar de marcação <input>.
Execute o aplicativo, acesse a página Índice de Alunos e observe que as horas não são mais exibidas nas datas de
registro. O mesmo será verdadeiro para qualquer exibição que usa o modelo Aluno.
O atributo StringLength
Você também pode especificar regras de validação de dados e mensagens de erro de validação usando atributos.
O atributo StringLength define o tamanho máximo do banco de dados e fornece validação do lado do cliente e
do lado do servidor para o ASP.NET Core MVC. Você também pode especificar o tamanho mínimo da cadeia de
caracteres nesse atributo, mas o valor mínimo não tem nenhum impacto sobre o esquema de banco de dados.
Suponha que você deseje garantir que os usuários não insiram mais de 50 caracteres em um nome. Para
adicionar essa limitação, adicione atributos StringLength às propriedades LastName e FirstMidName , conforme
mostrado no seguinte exemplo:
using System;
{
{
[StringLength(50)]

}
}
O atributo StringLength não impedirá que um usuário insira um espaço em branco em um nome. Use o
atributo RegularExpression para aplicar restrições à entrada. Por exemplo, o seguinte código exige que o
primeiro caractere esteja em maiúscula e os caracteres restantes estejam em ordem alfabética:
O atributo MaxLength fornece uma funcionalidade semelhante ao atributo StringLength , mas não fornece a
validação do lado do cliente.
Agora, o modelo de banco de dados foi alterado de uma forma que exige uma alteração no esquema de banco
de dados. Você usará migrações para atualizar o esquema sem perda dos dados que podem ter sido adicionados
ao banco de dados usando a interface do usuário do aplicativo.
Salve as alterações e compile o projeto. Em seguida, abra a janela Comando na pasta do projeto e insira os
seguintes comandos:
dotnet ef migrations add MaxLengthOnNames
O comando migrations add alerta que pode ocorrer perda de dados, pois a alteração torna o tamanho máximo
mais curto para duas colunas. As migrações criam um arquivo chamado <timeStamp>_MaxLengthOnNames.cs.
Esse arquivo contém o código no método Up que atualizará o banco de dados para que ele corresponda ao
modelo de dados atual. O comando database update executou esse código.
O carimbo de data/hora prefixado ao nome do arquivo de migrações é usado pelo Entity Framework para
ordenar as migrações. Crie várias migrações antes de executar o comando de atualização de banco de dados e,
em seguida, todas as migrações são aplicadas na ordem em que foram criadas.
Execute o aplicativo, selecione a guia Alunos, clique em Criar Novo e insira um nome com mais de 50
caracteres. Quando você clica em Criar, a validação do lado do cliente mostra uma mensagem de erro.
O atributo Column
Você também pode usar atributos para controlar como as classes e propriedades são mapeadas para o banco de
dados. Suponha que você tenha usado o nome FirstMidName para o campo de nome porque o campo também
pode conter um sobrenome. Mas você deseja que a coluna do banco de dados seja nomeada FirstName , pois os
usuários que escreverão consultas ad hoc no banco de dados estão acostumados com esse nome. Para fazer
esse mapeamento, use o atributo Column .
O atributo Column especifica que quando o banco de dados for criado, a coluna da tabela Student que é
mapeada para a propriedade FirstMidName será nomeada FirstName . Em outras palavras, quando o código se
referir a Student.FirstMidName , os dados serão obtidos ou atualizados na coluna FirstName da tabela Student .
Se você não especificar nomes de coluna, elas receberão o mesmo nome da propriedade.
No arquivo Student.cs, adicione uma instrução using a System.ComponentModel.DataAnnotations.Schema e
adicione o atributo de nome de coluna à propriedade FirstMidName , conforme mostrado no seguinte código
realçado:
using System;
{
{
[StringLength(50)]

}
}
A adição do atributo Column altera o modelo que dá suporte ao SchoolContext e, portanto, ele não corresponde
ao banco de dados.
Salve as alterações e compile o projeto. Em seguida, abra a janela Comando na pasta do projeto e insira os
seguintes comandos para criar outra migração:
dotnet ef migrations add ColumnFirstName
No Pesquisador de Objetos do SQL Server, abra o designer de tabela Aluno clicando duas vezes na tabela
Aluno.
Antes de você aplicar as duas primeiras migrações, as colunas de nome eram do tipo nvarchar(MAX). Agora elas
são nvarchar(50) e o nome da coluna foi alterado de FirstMidName para FirstName.
NOTE
Se você tentar compilar antes de concluir a criação de todas as classes de entidade nas seções a seguir, poderá receber
erros do compilador.
Alterações finais na entidade Student
Em Models/Student.cs, substitua o código que você adicionou anteriormente pelo código a seguir. As alterações
são realçadas.
using System;
{
{
[Required]
[StringLength(50)]
[Required]
{
get
{
}
}

}
}
O atributo Required
O atributo Required torna as propriedades de nome campos obrigatórios. O atributo Required não é
necessário para tipos que permitem valor nulo como tipos de valor (DateTime, int, double, float, etc.). Tipos que
não podem ser nulos são tratados automaticamente como campos obrigatórios.
Remova o atributo Required e substitua-o por um parâmetro de tamanho mínimo para o atributo StringLength
:

[StringLength(50, MinimumLength=1)]
O atributo Display
O atributo Display especifica que a legenda para as caixas de texto deve ser "Nome", "Sobrenome", "Nome
Completo" e "Data de Registro", em vez do nome de a propriedade em cada instância (que não tem nenhum
espaço entre as palavras).
A propriedade calculada FullName
FullName é uma propriedade calculada que retorna um valor criado pela concatenação de duas outras
propriedades. Portanto, ela tem apenas um acessador get e nenhuma coluna FullName será gerada no banco de
dados.
Criar a entidade Instructor

Crie Models/Instructor.cs, substituindo o código de modelo com o seguinte código:
using System;
{
public class Instructor
{
[Required]
[StringLength(50)]
[Required]
[StringLength(50)]

{
get { return LastName + ", " + FirstMidName; }
}

}
}
Observe que várias propriedades são as mesmas nas entidades Student e Instructor. No tutorial Implementando
a herança mais adiante nesta série, você refatorará esse código para eliminar a redundância.
Coloque vários atributos em uma linha, de modo que você também possa escrever os atributos HireDate da
seguinte maneira:
[DataType(DataType.Date),Display(Name = "Hire Date"),DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}",

ApplyFormatInEditMode = true)]
As propriedades de navegação CourseAssignments e OfficeAssignment

As propriedades CourseAssignments e OfficeAssignment são propriedades de navegação.
Um instrutor pode ministrar qualquer quantidade de cursos e, portanto, CourseAssignments é definido como
uma coleção.
Se uma propriedade de navegação pode conter várias entidades, o tipo precisa ser uma lista na qual as entradas
podem ser adicionadas, excluídas e atualizadas. Especifique ICollection<T> ou um tipo, como List<T> ou
HashSet<T> . Se você especificar ICollection<T> , o EF criará uma coleção HashSet<T> por padrão.
O motivo pelo qual elas são entidades CourseAssignment é explicado abaixo na seção sobre relações muitos para
muitos.
As regras de negócio do Contoso Universidade indicam que um instrutor pode ter apenas, no máximo, um
escritório; portanto, a propriedade OfficeAssignment contém uma única entidade OfficeAssignment (que pode
ser nulo se o escritório não está atribuído).
Criar a entidade OfficeAssignment
Crie Models/OfficeAssignment.cs com o seguinte código:
{
public class OfficeAssignment
{
[Key]
[StringLength(50)]
[Display(Name = "Office Location")]
public string Location { get; set; }

}
}
O atributo Key
Há uma relação um para zero ou um entre as entidades Instructor e OfficeAssignment. Uma atribuição de
escritório existe apenas em relação ao instrutor ao qual ela é atribuída e, portanto, sua chave primária também é
a chave estrangeira da entidade Instructor. Mas o Entity Framework não pode reconhecer InstructorID
automaticamente como a chave primária dessa entidade porque o nome não segue a convenção de
nomenclatura ID ou classnameID. Portanto, o atributo Key é usado para identificá-la como a chave:
[Key]
Você também pode usar o atributo Key se a entidade tem sua própria chave primária, mas você deseja atribuir
um nome de propriedade que não seja classnameID ou ID.
Por padrão, o EF trata a chave como não gerada pelo banco de dados porque a coluna destina-se a uma relação
de identificação.
A propriedade de navegação Instructor
A entidade Instructor tem uma propriedade de navegação OfficeAssignment que permite valor nulo (porque um
instrutor pode não ter uma atribuição de escritório), e a entidade OfficeAssignment tem uma propriedade de
navegação Instructor que não permite valor nulo (porque uma atribuição de escritório não pode existir sem
um instrutor – InstructorID não permite valor nulo). Quando uma entidade Instructor tiver uma entidade
OfficeAssignment relacionada, cada entidade terá uma referência à outra em sua propriedade de navegação.
Você pode colocar um atributo [Required] na propriedade de navegação Instructor para especificar que deve
haver um instrutor relacionado, mas não precisa fazer isso porque a chave estrangeira InstructorID (que
também é a chave para esta tabela) não permite valor nulo.
Modificar a entidade Course
Em Models/Course.cs, substitua o código que você adicionou anteriormente pelo código a seguir. As alterações
são realçadas.
{
public class Course
{

[Range(0, 5)]

}
}
A entidade de curso tem uma propriedade de chave estrangeira DepartmentID que aponta para a entidade
Department relacionada e ela tem uma propriedade de navegação Department .
O Entity Framework não exige que você adicione uma propriedade de chave estrangeira ao modelo de dados
quando você tem uma propriedade de navegação para uma entidade relacionada. O EF cria chaves estrangeiras
no banco de dados sempre que elas são necessárias e cria automaticamente propriedades de sombra para elas.
No entanto, ter a chave estrangeira no modelo de dados pode tornar as atualizações mais simples e mais
eficientes. Por exemplo, quando você busca uma entidade de curso a ser editada, a entidade Department é nula
se você não carregá-la; portanto, quando você atualiza a entidade de curso, você precisa primeiro buscar a
entidade Department. Quando a propriedade de chave estrangeira DepartmentID está incluída no modelo de
dados, você não precisa buscar a entidade Department antes da atualização.
O atributo DatabaseGenerated
O atributo DatabaseGenerated com o parâmetro None na propriedade CourseID especifica que os valores de
chave primária são fornecidos pelo usuário, em vez de serem gerados pelo banco de dados.
Por padrão, o Entity Framework pressupõe que os valores de chave primária sejam gerados pelo banco de
dados. É isso que você quer na maioria dos cenários. No entanto, para entidades Course, você usará um número
de curso especificado pelo usuário como uma série 1000 de um departamento, uma série 2000 para outro
departamento e assim por diante.
O atributo DatabaseGenerated também pode ser usado para gerar valores padrão, como no caso de colunas de
banco de dados usadas para registrar a data em que uma linha foi criada ou atualizada. Para obter mais
informações, consulte Propriedades geradas.
As propriedades de navegação e de chave estrangeira na entidade Course refletem as seguintes relações:
Um curso é atribuído a um departamento e, portanto, há uma propriedade de chave estrangeira DepartmentID e
de navegação Department pelas razões mencionadas acima.

Um curso pode ter qualquer quantidade de estudantes inscritos; portanto, a propriedade de navegação
Enrollments é uma coleção:
Um curso pode ser ministrado por vários instrutores; portanto, a propriedade de navegação CourseAssignments
é uma coleção (o tipo CourseAssignment é explicado posteriormente):
Criar a entidade Department
Crie Models/Department.cs com o seguinte código:

using System;
{
{


}
}
O atributo Column
Anteriormente, você usou o atributo Column para alterar o mapeamento de nome de coluna. No código da
entidade Department, o atributo Column está sendo usado para alterar o mapeamento de tipo de dados SQL, do
modo que a coluna seja definida usando o tipo de dinheiro do SQL Server no banco de dados:
[Column(TypeName="money")]
O mapeamento de coluna geralmente não é necessário, pois o Entity Framework escolhe o tipo de dados do
SQL Server apropriado com base no tipo CLR definido para a propriedade. O tipo decimal CLR é mapeado
para um tipo decimal SQL Server. Mas, nesse caso, você sabe que a coluna armazenará os valores de moeda e
o tipo de dados dinheiro é mais apropriado para isso.
As propriedades de navegação e de chave estrangeira refletem as seguintes relações:
Um departamento pode ou não ter um administrador, e um administrador é sempre um instrutor. Portanto, a
propriedade InstructorID é incluída como a chave estrangeira na entidade Instructor e um ponto de
interrogação é adicionado após a designação de tipo int para marcar a propriedade como uma propriedade
que permite valor nulo. A propriedade de navegação é chamada Administrator , mas contém uma entidade
Instructor:

Um departamento pode ter vários cursos e, portanto, há uma propriedade de navegação Courses:
NOTE
Por convenção, o Entity Framework habilita a exclusão em cascata para chaves estrangeiras que não permitem valor nulo e
em relações muitos para muitos. Isso pode resultar em regras de exclusão em cascata circular, que causará uma exceção
quando você tentar adicionar uma migração. Por exemplo, se você não definiu a propriedade Department.InstructorID
como uma propriedade que permite valor nulo, o EF configura uma regra de exclusão em cascata para excluir o instrutor
quando você exclui o departamento, que não é o que você deseja que aconteça. Se as regras de negócio exigissem que a
propriedade InstructorID não permitisse valor nulo, você precisaria usar a seguinte instrução de API fluente para
desabilitar a exclusão em cascata na relação:
.HasOne(d => d.Administrator)
.WithMany()
.OnDelete(DeleteBehavior.Restrict)
Modificar a entidade Enrollment
Em Models/Enrollment.cs, substitua o código que você adicionou anteriormente pelo seguinte código:
{
public enum Grade
{
A, B, C, D, F
}

{
[DisplayFormat(NullDisplayText = "No grade")]

}
}

As propriedades de navegação e de chave estrangeira refletem as seguintes relações:
Um registro destina-se a um único curso e, portanto, há uma propriedade de chave estrangeira CourseID e uma
propriedade de navegação Course :

Um registro destina-se a um único aluno e, portanto, há uma propriedade de chave estrangeira StudentID e
uma propriedade de navegação Student :

Relações muitos para muitos

Há uma relação muitos para muitos entre as entidades Student e Course e a entidade Enrollment funciona como
uma tabela de junção muitos para muitos com conteúdo no banco de dados. "Com conteúdo" significa que a
tabela Registro contém dados adicionais além das chaves estrangeiras para as tabelas unidas (nesse caso, uma
chave primária e uma propriedade Grade).
A ilustração a seguir mostra a aparência dessas relações em um diagrama de entidades. (Esse diagrama foi
gerado usando o Entity Framework Power Tools para o EF 6.x; a criação do diagrama não faz parte do tutorial,
mas está apenas sendo usada aqui como uma ilustração.)
Cada linha de relação tem um 1 em uma extremidade e um asterisco (*) na outra, indicando uma relação um
para muitos.
Se a tabela Registro não incluir informações de nota, ela apenas precisará conter as duas chaves estrangeiras
CourseID e StudentID. Nesse caso, ela será uma tabela de junção de muitos para muitos sem conteúdo (ou uma
tabela de junção pura) no banco de dados. As entidades Instructor e Course têm esse tipo de relação muitos
para muitos e a próxima etapa é criar uma classe de entidade para funcionar como uma tabela de junção sem
conteúdo.
(O EF 6.x é compatível com tabelas de junção implícita para relações muitos para muitos, ao contrário do EF
Core. Para obter mais informações, confira a discussão no repositório GitHub do EF Core.)
A entidade CourseAssignment
Crie Models/CourseAssignment.cs com o seguinte código:
using System;
{
public class CourseAssignment
{
}
}
Unir nomes de entidade

Uma tabela de junção é necessária no banco de dados para a relação muitos para muitos de Instrutor para
Cursos, e ela precisa ser representada por um conjunto de entidades. É comum nomear uma entidade de junção
EntityName1EntityName2 , que, nesse caso, será CourseInstructor . No entanto, recomendamos que você escolha
um nome que descreve a relação. Modelos de dados começam simples e aumentam, com junções não referentes
a conteúdo obtendo com frequência o conteúdo mais tarde. Se você começar com um nome descritivo de
entidade, não precisará alterar o nome posteriormente. O ideal é que a entidade de junção tenha seu próprio
nome natural (possivelmente, uma única palavra) no domínio de negócios. Por exemplo, Manuais e Clientes
podem ser vinculados por meio de Classificações. Para essa relação, CourseAssignment é uma escolha melhor
que CourseInstructor .
Chave composta
Como as chaves estrangeiras não permitem valor nulo e, juntas, identificam exclusivamente cada linha da tabela,
não é necessário ter uma chave primária. As propriedades InstructorID e CourseID devem funcionar como uma
chave primária composta. A única maneira de identificar chaves primárias compostas no EF é usando a API
fluente (isso não pode ser feito por meio de atributos). Você verá como configurar a chave primária composta na
próxima seção.
A chave composta garante que, embora você possa ter várias linhas para um curso e várias linhas para um
instrutor, não poderá ter várias linhas para o mesmo instrutor e curso. A entidade de junção Enrollment define
sua própria chave primária e, portanto, duplicatas desse tipo são possíveis. Para evitar essas duplicatas, você
pode adicionar um índice exclusivo nos campos de chave estrangeira ou configurar Enrollment com uma chave
primária composta semelhante a CourseAssignment . Para obter mais informações, consulte Índices.
Atualizar o contexto de banco de dados
Adicione o seguinte código realçado ao arquivo Data/SchoolContext.cs:
{
{
{
}


{
}
}
}
Esse código adiciona novas entidades e configura a chave primária composta da entidade CourseAssignment.
Alternativa de API fluente para atributos

O código no método OnModelCreating da classe DbContext usa a API fluente para configurar o comportamento
do EF. A API é chamada "fluente" porque costuma ser usada pelo encadeamento de uma série de chamadas de
método em uma única instrução, como neste exemplo da documentação do EF Core:

{
modelBuilder.Entity<Blog>()
.Property(b => b.Url)
.IsRequired();
}
Neste tutorial, você usa a API fluente somente para o mapeamento de banco de dados que não é possível fazer
com atributos. No entanto, você também pode usar a API fluente para especificar a maioria das regras de
formatação, validação e mapeamento que pode ser feita por meio de atributos. Alguns atributos como
MinimumLength não podem ser aplicados com a API fluente. Conforme mencionado anteriormente,
MinimumLength não altera o esquema; apenas aplica uma regra de validação do lado do cliente e do servidor.
Alguns desenvolvedores preferem usar a API fluente exclusivamente para que possam manter suas classes de
entidade "limpas". Combine atributos e a API fluente se desejar. Além disso, há algumas personalizações que
podem ser feitas apenas com a API fluente, mas em geral, a prática recomendada é escolher uma dessas duas
abordagens e usar isso com o máximo de consistência possível. Se usar as duas, observe que sempre que
houver um conflito, a API fluente substituirá atributos.
Para obter mais informações sobre atributos vs. API fluente, consulte Métodos de configuração.
Diagrama de entidade mostrando relações

A ilustração a seguir mostra o diagrama criado pelo Entity Framework Power Tools para o modelo Escola
concluído.
Além das linhas de relação um-para-muitos (1 para *), você pode ver a linha de relação um para zero ou um (1
para 0..1) entre as entidades Instructor e OfficeAssignment e a linha de relação zero-ou-um-para-muitos (0..1
para *) entre as entidades Instructor e Department.
Propagar o banco de dados com os dados de teste

Substitua o código no arquivo Data/DbInitializer.cs pelo código a seguir para fornecer dados de semente para as
novas entidades criadas.
using System;
using System.Linq;
{
{
{
//context.Database.EnsureCreated();

if (context.Students.Any())
{
}

{
new Student { FirstMidName = "Carson", LastName = "Alexander",
new Student { FirstMidName = "Meredith", LastName = "Alonso",
new Student { FirstMidName = "Arturo", LastName = "Anand",
new Student { FirstMidName = "Gytis", LastName = "Barzdukas",
new Student { FirstMidName = "Yan", LastName = "Li",
new Student { FirstMidName = "Peggy", LastName = "Justice",
new Student { FirstMidName = "Laura", LastName = "Norman",
new Student { FirstMidName = "Nino", LastName = "Olivetto",
EnrollmentDate = DateTime.Parse("2005-09-01") }
};

{
context.Students.Add(s);
}
var instructors = new Instructor[]

{
new Instructor { FirstMidName = "Kim", LastName = "Abercrombie",
new Instructor { FirstMidName = "Fadi", LastName = "Fakhouri",
new Instructor { FirstMidName = "Roger", LastName = "Harui",
new Instructor { FirstMidName = "Candace", LastName = "Kapoor",
new Instructor { FirstMidName = "Roger", LastName = "Zheng",
HireDate = DateTime.Parse("2004-02-12") }
};
foreach (Instructor i in instructors)

{
context.Instructors.Add(i);
}
var departments = new Department[]

{
new Department { Name = "English", Budget = 350000,
InstructorID = instructors.Single( i => i.LastName == "Abercrombie").ID },
new Department { Name = "Mathematics", Budget = 100000,
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID },
new Department { Name = "Engineering", Budget = 350000,
InstructorID = instructors.Single( i => i.LastName == "Harui").ID },
new Department { Name = "Economics", Budget = 100000,
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID }
};

{
context.Departments.Add(d);
}

{
new Course {CourseID = 1050, Title = "Chemistry", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "Engineering").DepartmentID
},
new Course {CourseID = 4022, Title = "Microeconomics", Credits = 3,
},
new Course {CourseID = 4041, Title = "Macroeconomics", Credits = 3,
},
new Course {CourseID = 1045, Title = "Calculus", Credits = 4,
},
new Course {CourseID = 3141, Title = "Trigonometry", Credits = 4,
},
new Course {CourseID = 2021, Title = "Composition", Credits = 3,
},
new Course {CourseID = 2042, Title = "Literature", Credits = 4,
},
};

{
}
var officeAssignments = new OfficeAssignment[]

{
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID,
Location = "Smith 17" },
InstructorID = instructors.Single( i => i.LastName == "Harui").ID,
Location = "Gowan 27" },
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID,
Location = "Thompson 304" },
};
foreach (OfficeAssignment o in officeAssignments)

{
context.OfficeAssignments.Add(o);
}

{
InstructorID = instructors.Single(i => i.LastName == "Kapoor").ID
},
},
},
},
InstructorID = instructors.Single(i => i.LastName == "Fakhouri").ID
},
},
},
CourseID = courses.Single(c => c.Title == "Literature" ).CourseID,
},
};
foreach (CourseAssignment ci in courseInstructors)

{
context.CourseAssignments.Add(ci);
}

{
new Enrollment {
Grade = Grade.A
},
new Enrollment {
Grade = Grade.C
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
new Enrollment {
Grade = Grade.B
},
new Enrollment {
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID
},
new Enrollment {
CourseID = courses.Single(c => c.Title == "Microeconomics").CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Barzdukas").ID,
CourseID = courses.Single(c => c.Title == "Chemistry").CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Li").ID,
CourseID = courses.Single(c => c.Title == "Composition").CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Justice").ID,
CourseID = courses.Single(c => c.Title == "Literature").CourseID,
Grade = Grade.B
}
};

{
var enrollmentInDataBase = context.Enrollments.Where(
s =>
s.Student.ID == e.StudentID &&
s.Course.CourseID == e.CourseID).SingleOrDefault();
if (enrollmentInDataBase == null)
{
context.Enrollments.Add(e);
}
}
}
}
}
Como você viu no primeiro tutorial, a maioria do código apenas cria novos objetos de entidade e carrega dados
de exemplo em propriedades, conforme necessário, para teste. Observe como as relações muitos para muitos
são tratadas: o código cria relações com a criação de entidades nos conjuntos de entidades de junção
Enrollments e CourseAssignment .
Adicionar uma migração

Salve as alterações e compile o projeto. Em seguida, abra a janela Comando na pasta do projeto e insira o
comando migrations add (não execute ainda o comando de atualização de banco de dados):
dotnet ef migrations add ComplexDataModel
Você receberá um aviso sobre a possível perda de dados.

An operation was scaffolded that may result in the loss of data. Please review the migration for accuracy.
Se você tiver tentado executar o comando database update neste ponto (não faça isso ainda), receberá o
seguinte erro:
A instrução ALTER TABLE entrou em conflito com a restrição FOREIGN KEY

"FK_dbo.Course_dbo.Department_DepartmentID". O conflito ocorreu no banco de dados
"ContosoUniversity", tabela "dbo.Departamento", coluna 'DepartmentID'.
Às vezes, quando você executa migrações com os dados existentes, precisa inserir dados de stub no banco de
dados para atender às restrições de chave estrangeira. O código gerado no método Up adiciona uma chave
estrangeira DepartmentID que não permite valor nulo para a tabela Curso. Se já houver linhas na tabela Curso
quando o código for executado, a operação AddColumn falhará, porque o SQL Server não saberá qual valor deve
ser colocado na coluna que não pode ser nulo. Para este tutorial, você executará a migração em um novo banco
de dados, mas em um aplicativo de produção, você precisará fazer com que a migração manipule os dados
existentes. Portanto, as instruções a seguir mostram um exemplo de como fazer isso.
Para fazer a migração funcionar com os dados existentes, você precisa alterar o código para fornecer à nova
coluna um valor padrão e criar um departamento de stub chamado "Temp" para atuar como o departamento
padrão. Como resultado, as linhas Curso existentes serão todas relacionadas ao departamento "Temp" após a
execução do método Up .
Abra o arquivo {timestamp }_ComplexDataModel.cs.
Comente a linha de código que adiciona a coluna DepartmentID à tabela Curso.
migrationBuilder.AlterColumn<string>(
name: "Title",
table: "Course",
maxLength: 50,
nullable: true,
oldClrType: typeof(string),
oldNullable: true);
//migrationBuilder.AddColumn<int>(
// name: "DepartmentID",
// table: "Course",
// nullable: false,
// defaultValue: 0);
Adicione o seguinte código realçado após o código que cria a tabela Departamento:
name: "Department",
{
DepartmentID = table.Column<int>(nullable: false)
.Annotation("SqlServer:ValueGenerationStrategy",
SqlServerValueGenerationStrategy.IdentityColumn),
Budget = table.Column<decimal>(type: "money", nullable: false),
InstructorID = table.Column<int>(nullable: true),
Name = table.Column<string>(maxLength: 50, nullable: true),
StartDate = table.Column<DateTime>(nullable: false)
},
{
table.PrimaryKey("PK_Department", x => x.DepartmentID);
table.ForeignKey(
name: "FK_Department_Instructor_InstructorID",
column: x => x.InstructorID,
principalTable: "Instructor",
principalColumn: "ID",
onDelete: ReferentialAction.Restrict);
});
migrationBuilder.Sql("INSERT INTO dbo.Department (Name, Budget, StartDate) VALUES ('Temp', 0.00,

GETDATE())");
// Default value for FK points to department created above, with
// defaultValue changed to 1 in following AddColumn statement.
migrationBuilder.AddColumn<int>(
name: "DepartmentID",
table: "Course",
nullable: false,
defaultValue: 1);
Em um aplicativo de produção, você escreverá código ou scripts para adicionar linhas Departamento e relacionar
linhas Curso às novas linhas Departamento. Em seguida, você não precisará mais do departamento "Temp" ou
do valor padrão na coluna Course.DepartmentID.
Salve as alterações e compile o projeto.
Alterar a cadeia de conexão e atualizar o banco de dados

Agora, você tem novo código na classe DbInitializer que adiciona dados de semente para as novas entidades a
um banco de dados vazio. Para fazer com que o EF crie um novo banco de dados vazio, altere o nome do banco
de dados na cadeia de conexão em appsettings.json para ContosoUniversity3 ou para outro nome que você
ainda não usou no computador que está sendo usado.
{
},
Salve as alterações em appsettings.json.

NOTE
Como alternativa à alteração do nome do banco de dados, você pode excluir o banco de dados. Use o SSOX (Pesquisador
de Objetos do SQL Server) ou o comando database drop da CLI:
Depois que você tiver alterado o nome do banco de dados ou excluído o banco de dados, execute o comando
database update na janela Comando para executar as migrações.
Execute o aplicativo para fazer com que o método DbInitializer.Initialize execute e popule o novo banco de
dados.
Abra o banco de dados no SSOX, como você fez anteriormente, e expanda o nó Tabelas para ver se todas as
tabelas foram criadas. (Se você ainda tem o SSOX aberto do momento anterior, clique no botão Atualizar.)
Execute o aplicativo para disparar o código inicializador que propaga o banco de dados.
Clique com o botão direito do mouse na tabela CourseAssignment e selecione Exibir Dados para verificar se
existem dados nela.
Resumo
Agora você tem um modelo de dados mais complexo e um banco de dados correspondente. No tutorial a seguir,
você aprenderá mais sobre como acessar dados relacionados.
ASP.NET Core MVC com o EF Core – ler dados
relacionados – 6 de 10
versão 2.0.
Páginas do Razor:
No tutorial anterior, você concluiu o modelo de dados Escola. Neste tutorial, você lerá e exibirá dados
relacionados – ou seja, os dados que o Entity Framework carrega nas propriedades de navegação.
As ilustrações a seguir mostram as páginas com as quais você trabalhará.
Carregamento adiantado, explícito e lento de dados relacionados
Há várias maneiras pelas quais um software ORM (Object-Relational Mapping), como o Entity Framework, pode
carregar dados relacionados nas propriedades de navegação de uma entidade:
Carregamento adiantado. Quando a entidade é lida, os dados relacionados são recuperados com ela.
Normalmente, isso resulta em uma única consulta de junção que recupera todos os dados necessários.
Especifique o carregamento adiantado no Entity Framework Core usando os métodos Include e
ThenInclude .
Recupere alguns dos dados em consultas separadas e o EF "corrigirá" as propriedades de navegação. Ou

seja, o EF adiciona de forma automática as entidades recuperadas separadamente no local em que
pertencem nas propriedades de navegação de entidades recuperadas anteriormente. Para a consulta que
recupera dados relacionados, você pode usar o método Load em vez de um método que retorna uma
lista ou um objeto, como ToList ou Single .
Carregamento explícito. Quando a entidade é lida pela primeira vez, os dados relacionados não são
recuperados. Você escreve o código que recupera os dados relacionados se eles são necessários. Como
no caso do carregamento adiantado com consultas separadas, o carregamento explícito resulta no envio
de várias consultas ao banco de dados. A diferença é que, com o carregamento explícito, o código
especifica as propriedades de navegação a serem carregadas. No Entity Framework Core 1.1, você pode
usar o método Load para fazer o carregamento explícito. Por exemplo:
Carregamento lento. Quando a entidade é lida pela primeira vez, os dados relacionados não são
recuperados. No entanto, na primeira vez que você tenta acessar uma propriedade de navegação, os
dados necessários para essa propriedade de navegação são recuperados automaticamente. Uma consulta
é enviada ao banco de dados sempre que você tenta obter dados de uma propriedade de navegação pela
primeira vez. O Entity Framework Core 1.0 não dá suporte ao carregamento lento.
Considerações sobre desempenho
Se você sabe que precisa de dados relacionados para cada entidade recuperada, o carregamento adiantado
costuma oferecer o melhor desempenho, porque uma única consulta enviada para o banco de dados é
geralmente mais eficiente do que consultas separadas para cada entidade recuperada. Por exemplo, suponha
que cada departamento tenha dez cursos relacionados. O carregamento adiantado de todos os dados
relacionados resultará em apenas uma única consulta (junção) e uma única viagem de ida e volta para o banco
de dados. Uma consulta separada para cursos de cada departamento resultará em onze viagens de ida e volta
para o banco de dados. As viagens de ida e volta extras para o banco de dados são especialmente prejudiciais ao
desempenho quando a latência é alta.
Por outro lado, em alguns cenários, consultas separadas são mais eficientes. O carregamento adiantado de todos
os dados relacionados em uma consulta pode fazer com que uma junção muito complexa seja gerada, que o
SQL Server não consegue processar com eficiência. Ou se precisar acessar as propriedades de navegação de
uma entidade somente para um subconjunto de um conjunto de entidades que está sendo processado, consultas
separadas poderão ter um melhor desempenho, pois o carregamento adiantado de tudo desde o início recupera
mais dados do que você precisa. Se o desempenho for crítico, será melhor testar o desempenho das duas
maneiras para fazer a melhor escolha.
Criar uma página Courses que exibe o nome do Departamento

A entidade Course inclui uma propriedade de navegação que contém a entidade Department do departamento
ao qual o curso é atribuído. Para exibir o nome do departamento atribuído em uma lista de cursos, você precisa
obter a propriedade Name da entidade Department que está na propriedade de navegação Course.Department .
Crie um controlador chamado CoursesController para o tipo de entidade Course, usando as mesmas opções
para o scaffolder Controlador MVC com exibições, usando o Entity Framework que você usou
anteriormente para o controlador Alunos, conforme mostrado na seguinte ilustração:
Abra CoursesController.cs e examine o método Index . O scaffolding automático especificou o carregamento

adiantado para a propriedade de navegação Department usando o método Include .
Substitua o método Index pelo seguinte código, que usa um nome mais apropriado para o IQueryable que
retorna as entidades Course ( courses em vez de schoolContext ):

{
var courses = _context.Courses
.AsNoTracking();
return View(await courses.ToListAsync());
}
Abra Views/Courses/Index.cshtml e substitua o código de modelo pelo código a seguir. As alterações são
realçadas:
@model IEnumerable<ContosoUniversity.Models.Course>
@{
ViewData["Title"] = "Courses";
}
<h2>Courses</h2>
<p>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.CourseID)
</th>
<th>
</th>
<th>
@Html.DisplayNameFor(model => model.Credits)
</th>
<th>
@Html.DisplayNameFor(model => model.Department)
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.CourseID)
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.Credits)
</td>
<td>
</td>
<td>
<a asp-action="Edit" asp-route-id="@item.CourseID">Edit</a> |
<a asp-action="Details" asp-route-id="@item.CourseID">Details</a> |
<a asp-action="Delete" asp-route-id="@item.CourseID">Delete</a>
</td>
</tr>
}
</tbody>
</table>
Você fez as seguintes alterações no código gerado por scaffolding:

Alterou o cabeçalho de Índice para Cursos.
Adicionou uma coluna Número que mostra o valor da propriedade CourseID . Por padrão, as chaves
primárias não são geradas por scaffolding porque normalmente não têm sentido para os usuários finais.
No entanto, nesse caso, a chave primária é significativa e você deseja mostrá-la.
Alterou a coluna Departamento para que ela exiba o nome de departamento. O código exibe a
propriedade Name da entidade Department que é carregada na propriedade de navegação Department :
Execute o aplicativo e selecione a guia Cursos para ver a lista com nomes de departamentos.
Criar uma página Instrutores que mostra Cursos e Registros

Nesta seção, você criará um controlador e uma exibição para a entidade Instructor para exibir a página
Instrutores:
Essa página lê e exibe dados relacionados das seguintes maneiras:
A lista de instrutores exibe dados relacionados da entidade OfficeAssignment. As entidades Instructor e
OfficeAssignment estão em uma relação um para zero ou um. Você usará o carregamento adiantado para
as entidades OfficeAssignment. Conforme explicado anteriormente, o carregamento adiantado é
geralmente mais eficiente quando você precisa dos dados relacionados para todas as linhas recuperadas
da tabela primária. Nesse caso, você deseja exibir atribuições de escritório para todos os instrutores
exibidos.
Quando o usuário seleciona um instrutor, as entidades Course relacionadas são exibidas. As entidades
Instructor e Course estão em uma relação muitos para muitos. Você usará o carregamento adiantado
para as entidades Course e suas entidades Department relacionadas. Nesse caso, consultas separadas
podem ser mais eficientes porque você precisa de cursos somente para o instrutor selecionado. No
entanto, este exemplo mostra como usar o carregamento adiantado para propriedades de navegação em
entidades que estão nas propriedades de navegação.
Quando o usuário seleciona um curso, dados relacionados do conjunto de entidades Enrollments são
exibidos. As entidades Course e Enrollment estão em uma relação um para muitos. Você usará consultas
separadas para entidades Enrollment e suas entidades Student relacionadas.
Criar um modelo de exibição para a exibição Índice de Instrutor
A página Instrutores mostra dados de três tabelas diferentes. Portanto, você criará um modelo de exibição que
inclui três propriedades, cada uma contendo os dados de uma das tabelas.
Na pasta SchoolViewModels, crie InstructorIndexData.cs e substitua o código existente pelo seguinte código:
using System;
using System.Linq;
{
public class InstructorIndexData
{
public IEnumerable<Instructor> Instructors { get; set; }
public IEnumerable<Course> Courses { get; set; }
public IEnumerable<Enrollment> Enrollments { get; set; }
}
}
Criar exibições e o controlador Instrutor

Crie um controlador Instrutores com ações de leitura/gravação do EF, conforme mostrado na seguinte
ilustração:
Abra InstructorsController.cs e adicione um usando a instrução para o namespace ViewModels:
Substitua o método Index pelo código a seguir para fazer o carregamento adiantado de dados relacionados e
colocá-los no modelo de exibição.
public async Task<IActionResult> Index(int? id, int? courseID)
{
var viewModel = new InstructorIndexData();
viewModel.Instructors = await _context.Instructors
.AsNoTracking()
.ToListAsync();
if (id != null)
{
ViewData["InstructorID"] = id.Value;
Instructor instructor = viewModel.Instructors.Where(
viewModel.Courses = instructor.CourseAssignments.Select(s => s.Course);
}
{
ViewData["CourseID"] = courseID.Value;
viewModel.Enrollments = viewModel.Courses.Where(
}
}
O método aceita dados de rota opcionais ( id ) e um parâmetro de cadeia de caracteres de consulta ( courseID )
que fornece os valores de ID do curso e do instrutor selecionados. Os parâmetros são fornecidos pelos
hiperlinks Selecionar na página.
O código começa com a criação de uma instância do modelo de exibição e colocando-a na lista de instrutores. O
código especifica o carregamento adiantado para as propriedades de navegação Instructor.OfficeAssignment e
Instructor.CourseAssignments . Dentro da propriedade CourseAssignments , a propriedade Course é carregada e,
dentro dela, as propriedades Enrollments e Department são carregadas e, dentro de cada entidade Enrollment ,
a propriedade Student é carregada.

.AsNoTracking()
.ToListAsync();
Como a exibição sempre exige a entidade OfficeAssignment, é mais eficiente buscar isso na mesma consulta. As
entidades Course são necessárias quando um instrutor é selecionado na página da Web; portanto, uma única
consulta é melhor do que várias consultas apenas se a página é exibida com mais frequência com um curso
selecionado do que sem ele.
O código repete CourseAssignments e Course porque você precisa de duas propriedades de Course . A primeira
cadeia de caracteres de chamadas ThenInclude obtém CourseAssignment.Course , Course.Enrollments e
Enrollment.Student .

.AsNoTracking()
.ToListAsync();
Nesse ponto do código, outro ThenInclude se refere às propriedades de navegação de Student , que não é
necessário. Mas a chamada a Include é reiniciada com propriedades Instructor e, portanto, você precisa
passar pela cadeia novamente, dessa vez, especificando Course.Department em vez de Course.Enrollments .

.AsNoTracking()
.ToListAsync();
O código a seguir é executado quando o instrutor é selecionado. O instrutor selecionado é recuperado da lista de
instrutores no modelo de exibição. Em seguida, a propriedade Courses do modelo de exibição é carregada com
as entidades Course da propriedade de navegação CourseAssignments desse instrutor.
if (id != null)
{
}
O método Where retorna uma coleção, mas nesse caso, os critérios passado para esse método resultam no
retorno de apenas uma única entidade Instructor. O método Single converte a coleção em uma única entidade
Instructor, que fornece acesso à propriedade CourseAssignments dessa entidade. A propriedade
CourseAssignments contém entidades CourseAssignment , das quais você deseja apenas entidades Course
relacionadas.
Use o método Single em uma coleção quando souber que a coleção terá apenas um item. O método Single
gera uma exceção se a coleção passada para ele está vazia ou se há mais de um item. Uma alternativa é
SingleOrDefault , que retorna um valor padrão (nulo, nesse caso) se a coleção está vazia. No entanto, nesse caso,
isso ainda resultará em uma exceção (da tentativa de encontrar uma propriedade Courses em uma referência
nula), e a mensagem de exceção menos claramente indicará a causa do problema. Quando você chama o
método Single , também pode passar a condição Where, em vez de chamar o método Where separadamente:
.Single(i => i.ID == id.Value)
Em vez de:
.Where(i => i.ID == id.Value).Single()
Em seguida, se um curso foi selecionado, o curso selecionado é recuperado na lista de cursos no modelo de
exibição. Em seguida, a propriedade Enrollments do modelo de exibição é carregada com as entidades
Enrollment da propriedade de navegação Enrollments desse curso.
{
viewModel.Enrollments = viewModel.Courses.Where(
}
Modificar a exibição Índice de Instrutor

Em Views/Instructors/Index.cshtml, substitua o código de modelo pelo código a seguir. As alterações são
realçadas.
@model ContosoUniversity.Models.SchoolViewModels.InstructorIndexData
@{
ViewData["Title"] = "Instructors";
}
<h2>Instructors</h2>
<p>
</p>
<thead>
<tr>
<th>Last Name</th>
<th>First Name</th>
<th>Hire Date</th>
<th>Office</th>
<th>Courses</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Instructors)
{
if (item.ID == (int?)ViewData["InstructorID"])
{
}
<td>
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.HireDate)
</td>
<td>
{
}
</td>
<td>
@{
foreach (var course in item.CourseAssignments)
{
@course.Course.CourseID @: @course.Course.Title <br />
}
}
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
Você fez as seguintes alterações no código existente:

Alterou a classe de modelo para InstructorIndexData .
Alterou o título de página de Índice para Instrutores.
Adicionou uma coluna Office que exibe item.OfficeAssignment.Location somente se
item.OfficeAssignment não é nulo. ( Como essa é uma relação um para zero ou um, pode não haver uma
entidade OfficeAssignment relacionada.)

{
}
Adicionou uma coluna Courses que exibe os cursos ministrados por cada instrutor. Consulte Transição de
linha explícita com @: para obter mais informações sobre essa sintaxe Razor.
Adicionou um código que adiciona class="success" dinamicamente ao elemento tr do instrutor
selecionado. Isso define uma cor da tela de fundo para a linha selecionada usando uma classe Bootstrap.

if (item.ID == (int?)ViewData["InstructorID"])
{
}
Adicionou um novo hiperlink rotulado Selecionar imediatamente antes dos outros links em cada linha, o
que faz com que a ID do instrutor selecionado seja enviada para o método Index .
Execute o aplicativo e selecione a guia Instrutores. A página exibe a propriedade Location das entidades
OfficeAssignment relacionadas e uma célula de tabela vazia quando não há nenhuma entidade
OfficeAssignment relacionada.
No arquivo Views/Instructors/Index.cshtml, após o elemento de tabela de fechamento (ao final do arquivo),

adicione o código a seguir. Esse código exibe uma lista de cursos relacionados a um instrutor quando um
instrutor é selecionado.
@if (Model.Courses != null)

{
<h3>Courses Taught by Selected Instructor</h3>
<tr>
<th></th>
<th>Number</th>
<th>Title</th>
<th>Department</th>
</tr>
@foreach (var item in Model.Courses)

{
if (item.CourseID == (int?)ViewData["CourseID"])
{
}
<td>
@Html.ActionLink("Select", "Index", new { courseID = item.CourseID })
</td>
<td>
@item.CourseID
</td>
<td>
@item.Title
</td>
<td>
@item.Department.Name
</td>
</tr>
}
</table>
}
Esse código lê a propriedade Courses do modelo de exibição para exibir uma lista de cursos. Também fornece
um hiperlink Selecionar que envia a ID do curso selecionado para o método de ação Index .
Atualize a página e selecione um instrutor. Agora, você verá uma grade que exibe os cursos atribuídos ao
instrutor selecionado, e para cada curso, verá o nome do departamento atribuído.
Após o bloco de código que você acabou de adicionar, adicione o código a seguir.Isso exibe uma lista dos alunos
que estão registrados em um curso quando esse curso é selecionado.
@if (Model.Enrollments != null)

{
<h3>
Students Enrolled in Selected Course
</h3>
<tr>
<th>Name</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.Enrollments)
{
<tr>
<td>
@item.Student.FullName
</td>
<td>
</td>
</tr>
}
</table>
}
Esse código lê a propriedade Enrollments do modelo de exibição para exibir uma lista dos alunos registrados no
curso.
Atualize a página novamente e selecione um instrutor. Em seguida, selecione um curso para ver a lista de alunos
registrados e suas notas.
Carregamento explícito
Quando você recuperou a lista de instrutores em InstructorsController.cs, você especificou o carregamento
adiantado para a propriedade de navegação CourseAssignments .
Suponha que os usuários esperados raramente desejem ver registros em um curso e um instrutor selecionados.
Nesse caso, talvez você deseje carregar os dados de registro somente se eles forem solicitados. Para ver um
exemplo de como fazer carregamento explícito, substitua o método Index pelo código a seguir, que remove o
carregamento adiantado para Enrollments e carrega essa propriedade de forma explícita. As alterações de
código são realçadas.
public async Task<IActionResult> Index(int? id, int? courseID)
{
var viewModel = new InstructorIndexData();
.ToListAsync();
if (id != null)
{
}
{
var selectedCourse = viewModel.Courses.Where(x => x.CourseID == courseID).Single();
await _context.Entry(selectedCourse).Collection(x => x.Enrollments).LoadAsync();
foreach (Enrollment enrollment in selectedCourse.Enrollments)
{
await _context.Entry(enrollment).Reference(x => x.Student).LoadAsync();
}
viewModel.Enrollments = selectedCourse.Enrollments;
}
}
O novo código remove as chamadas do método ThenInclude para dados de registro do código que recupera as
entidades do instrutor. Se um curso e um instrutor são selecionados, o código realçado recupera entidades
Enrollment para o curso selecionado e as entidades Student para cada Enrollment.
Execute que o aplicativo, acesse a página Índice de Instrutores agora e você não verá nenhuma diferença no que
é exibido na página, embora você tenha alterado a maneira como os dados são recuperados.
Resumo
Agora, você usou o carregamento adiantado com uma consulta e com várias consultas para ler dados
relacionados nas propriedades de navegação. No próximo tutorial, você aprenderá a atualizar dados
relacionados.
ASP.NET Core MVC com o EF Core – atualizar dados
relacionados – 7 de 10
2.0.
Páginas do Razor:
No tutorial anterior, você exibiu dados relacionados; neste tutorial, você atualizará dados relacionados pela
atualização dos campos de chave estrangeira e das propriedades de navegação.
As ilustrações a seguir mostram algumas das páginas com as quais você trabalhará.
Personalizar as páginas Criar e Editar dos cursos
Quando uma nova entidade de curso é criada, ela precisa ter uma relação com um departamento existente. Para
facilitar isso, o código gerado por scaffolding inclui métodos do controlador e exibições Criar e Editar que incluem
uma lista suspensa para seleção do departamento. A lista suspensa define a propriedade de chave estrangeira
Course.DepartmentID , e isso é tudo o que o Entity Framework precisa para carregar a propriedade de navegação
Department com a entidade Department apropriada. Você usará o código gerado por scaffolding, mas o alterará
ligeiramente para adicionar tratamento de erro e classificação à lista suspensa.
Em CoursesController.cs, exclua os quatro métodos Create e Edit e substitua-os pelo seguinte código:

{
PopulateDepartmentsDropDownList();
return View();
}
[HttpPost]
public async Task<IActionResult> Create([Bind("CourseID,Credits,DepartmentID,Title")] Course course)
{
{
_context.Add(course);
}
PopulateDepartmentsDropDownList(course.DepartmentID);
return View(course);
}

{
if (id == null)
{
return NotFound();
}
var course = await _context.Courses

.AsNoTracking()
.SingleOrDefaultAsync(m => m.CourseID == id);
if (course == null)
{
return NotFound();
}
}
{
if (id == null)
{
return NotFound();
}
var courseToUpdate = await _context.Courses

.SingleOrDefaultAsync(c => c.CourseID == id);
if (await TryUpdateModelAsync<Course>(courseToUpdate,
"",
c => c.Credits, c => c.DepartmentID, c => c.Title))
{
try
{
}
{
}
}
PopulateDepartmentsDropDownList(courseToUpdate.DepartmentID);
return View(courseToUpdate);
}
Após o método HttpPost Edit , crie um novo método que carrega informações de departamento para a lista
suspensa.
private void PopulateDepartmentsDropDownList(object selectedDepartment = null)

{
var departmentsQuery = from d in _context.Departments
orderby d.Name
select d;
ViewBag.DepartmentID = new SelectList(departmentsQuery.AsNoTracking(), "DepartmentID", "Name",
selectedDepartment);
}
O método PopulateDepartmentsDropDownList obtém uma lista de todos os departamentos classificados por nome,
cria uma coleção SelectList para uma lista suspensa e passa a coleção para a exibição em ViewBag . O método
aceita o parâmetro selectedDepartment opcional que permite que o código de chamada especifique o item que
será selecionado quando a lista suspensa for renderizada. A exibição passará o nome "DepartmentID" para o
auxiliar de marcação <select> e o auxiliar então saberá que deve examinar o objeto ViewBag em busca de uma
SelectList chamada "DepartmentID".
O método HttpGet Create chama o método PopulateDepartmentsDropDownList sem definir o item selecionado,
porque um novo curso do departamento ainda não foi estabelecido:

{
PopulateDepartmentsDropDownList();
return View();
}
O método HttpGet Edit define o item selecionado, com base na ID do departamento já atribuído ao curso que
está sendo editado:

{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
if (course == null)
{
return NotFound();
}
}
Os métodos HttpPost para Create e Edit também incluem o código que define o item selecionado quando eles
exibem novamente a página após um erro. Isso garante que quando a página for exibida novamente para mostrar
a mensagem de erro, qualquer que tenha sido o departamento selecionado permaneça selecionado.
Adicionar .AsNoTracking aos métodos Details e Delete
Para otimizar o desempenho das páginas Detalhes do Curso e Excluir, adicione chamadas AsNoTracking aos
métodos HttpGet Details e Delete .

{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
if (course == null)
{
return NotFound();
}
}
{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
if (course == null)
{
return NotFound();
}
}
Modificar as exibições Curso

Em Views/Courses/Create.cshtml, adicione uma opção "Selecionar Departamento" à lista suspensa
Departamento, altere a legenda de DepartmentID para Departamento e adicione uma mensagem de
validação.
<label asp-for="Department" class="control-label"></label>
<select asp-for="DepartmentID" class="form-control" asp-items="ViewBag.DepartmentID">
</select>
<span asp-validation-for="DepartmentID" class="text-danger" />
Em Views/Courses/Edit.cshtml, faça a mesma alteração no campo Departamento que você acabou de fazer em
Create.cshtml.
Também em Views/Courses/Edit.cshtml, adicione um campo de número de curso antes do campo Título. Como o
número de curso é a chave primária, ele é exibido, mas não pode ser alterado.
<label asp-for="CourseID" class="control-label"></label>
<div>@Html.DisplayFor(model => model.CourseID)</div>
</div>
Já existe um campo oculto ( <input type="hidden"> ) para o número de curso na exibição Editar. A adição de um
auxiliar de marcação <label> não elimina a necessidade do campo oculto, porque ele não faz com que o número
de curso seja incluído nos dados postados quando o usuário clica em Salvar na página Editar.
Em Views/Courses/Delete.cshtml, adicione um campo de número de curso na parte superior e altere a ID do
departamento para o nome do departamento.
@model ContosoUniversity.Models.Course
@{
}
<h2>Delete</h2>

<div>
<h4>Course</h4>
<hr />
<dt>
@Html.DisplayNameFor(model => model.CourseID)
</dt>
<dd>
@Html.DisplayFor(model => model.CourseID)
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.Title)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Credits)
</dt>
<dd>
@Html.DisplayFor(model => model.Credits)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Department)
</dt>
<dd>
@Html.DisplayFor(model => model.Department.Name)
</dd>
</dl>
<form asp-action="Delete">
</div>
</form>
</div>
Em Views/Courses/Details.cshtml, faça a mesma alteração que você acabou de fazer para Delete.cshtml.
Testar as páginas Curso
Execute o aplicativo, selecione a guia Cursos, clique em Criar Novo e insira dados para um novo curso:
Clique em Criar. A página Índice de Cursos é exibida com o novo curso adicionado à lista. O nome do
departamento na lista de páginas de Índice é obtido da propriedade de navegação, mostrando que a relação foi
estabelecida corretamente.
Clique em Editar em um curso na página Índice de Cursos.
Altere dados na página e clique em Salvar. A página Índice de Cursos é exibida com os dados de cursos
atualizados.
Adicionar uma página Editar para instrutores

Quando você edita um registro de instrutor, deseja poder atualizar a atribuição de escritório do instrutor.A
entidade Instructor tem uma relação um para zero ou um com a entidade OfficeAssignment, o que significa que o
código deve manipular as seguintes situações:
Se o usuário apagar a atribuição de escritório e ela originalmente tinha um valor, exclua a entidade
OfficeAssignment.
Se o usuário inserir um valor de atribuição de escritório e ele originalmente estava vazio, crie uma nova
entidade OfficeAssignment.
Se o usuário alterar o valor de uma atribuição de escritório, altere o valor em uma entidade
OfficeAssignment existente.
Atualizar o controlador Instrutores
Em InstructorsController.cs, altere o código no método HttpGet Edit para que ele carregue a propriedade de
navegação OfficeAssignment da entidade Instructor e chame AsNoTracking :
{
if (id == null)
{
return NotFound();
}
var instructor = await _context.Instructors

.AsNoTracking()
if (instructor == null)
{
return NotFound();
}
return View(instructor);
}
Substitua o método HttpPost Edit pelo seguinte código para manipular atualizações de atribuição de escritório:
{
if (id == null)
{
return NotFound();
}

.SingleOrDefaultAsync(s => s.ID == id);
instructorToUpdate,
"",
i => i.FirstMidName, i => i.LastName, i => i.HireDate, i => i.OfficeAssignment))
{
if (String.IsNullOrWhiteSpace(instructorToUpdate.OfficeAssignment?.Location))
{
}
try
{
}
{
}
}
return View(instructorToUpdate);
}
O código faz o seguinte:

Altera o nome do método para EditPost porque a assinatura agora é a mesma do método HttpGet Edit
(o atributo ActionName especifica que a URL /Edit/ ainda é usada).
Obtém a entidade Instructor atual do banco de dados usando o carregamento adiantado para a
propriedade de navegação OfficeAssignment . Isso é o mesmo que você fez no método HttpGet Edit .
Atualiza a entidade Instructor recuperada com valores do associador de modelos. A sobrecarga
TryUpdateModel permite que você adicione à lista de permissões as propriedades que você deseja incluir.
Isso impede o excesso de postagem, conforme explicado no segundo tutorial.
instructorToUpdate,
"",
Se o local do escritório estiver em branco, a propriedade Instructor.OfficeAssignment será definida como

nula para que a linha relacionada na tabela OfficeAssignment seja excluída.
{
}
Salva as alterações no banco de dados.

Atualizar a exibição Editar Instrutor
Em Views/Instructors/Edit.cshtml, adicione um novo campo para editar o local do escritório, ao final, antes do
botão Salvar:
<label asp-for="OfficeAssignment.Location" class="control-label"></label>
<input asp-for="OfficeAssignment.Location" class="form-control" />
<span asp-validation-for="OfficeAssignment.Location" class="text-danger" />
</div>
Execute o aplicativo, selecione a guia Instrutores e, em seguida, clique em Editar em um instrutor. Altere o Local
do Escritório e clique em Salvar.
Adicionar atribuições de Curso à página Editar Instrutor
Os instrutores podem ministrar a quantidade de cursos que desejarem. Agora, você aprimorará a página Editar
Instrutor adicionando a capacidade de alterar as atribuições de curso usando um grupo de caixas de seleção,
conforme mostrado na seguinte captura de tela:
A relação entre as entidades Course e Instructor é muitos para muitos. Para adicionar e remover relações,
adicione e remova entidades bidirecionalmente no conjunto de entidades de junção CourseAssignments.
A interface do usuário que permite alterar a quais cursos um instrutor é atribuído é um grupo de caixas de
seleção. Uma caixa de seleção é exibida para cada curso no banco de dados, e aqueles aos quais o instrutor está
atribuído no momento são marcados. O usuário pode marcar ou desmarcar as caixas de seleção para alterar as
atribuições de curso. Se a quantidade de cursos for muito maior, provavelmente, você desejará usar outro método
de apresentação dos dados na exibição, mas usará o mesmo método de manipulação de uma entidade de junção
para criar ou excluir relações.
Atualizar o controlador Instrutores
Para fornecer dados à exibição para a lista de caixas de seleção, você usará uma classe de modelo de exibição.
Crie AssignedCourseData.cs na pasta SchoolViewModels e substitua o código existente pelo seguinte código:
using System;
using System.Linq;
{
public class AssignedCourseData
{
public bool Assigned { get; set; }
}
}
Em InstructorsController.cs, substitua o método HttpGet Edit pelo código a seguir. As alterações são realçadas.

{
if (id == null)
{
return NotFound();
}
var instructor = await _context.Instructors

.Include(i => i.CourseAssignments).ThenInclude(i => i.Course)
.AsNoTracking()
if (instructor == null)
{
return NotFound();
}
PopulateAssignedCourseData(instructor);
}
private void PopulateAssignedCourseData(Instructor instructor)

{
var allCourses = _context.Courses;
var instructorCourses = new HashSet<int>(instructor.CourseAssignments.Select(c => c.CourseID));
var viewModel = new List<AssignedCourseData>();
foreach (var course in allCourses)
{
viewModel.Add(new AssignedCourseData
{
CourseID = course.CourseID,
Title = course.Title,
Assigned = instructorCourses.Contains(course.CourseID)
});
}
ViewData["Courses"] = viewModel;
}
O código adiciona o carregamento adiantado à propriedade de navegação Courses e chama o novo método
PopulateAssignedCourseData para fornecer informações para a matriz de caixa de seleção usando a classe de
modelo de exibição AssignedCourseData .
O código no método PopulateAssignedCourseData lê todas as entidades Course para carregar uma lista de cursos
usando a classe de modelo de exibição. Para cada curso, o código verifica se o curso existe na propriedade de
navegação Courses do instrutor. Para criar uma pesquisa eficiente ao verificar se um curso é atribuído ao
instrutor, os cursos atribuídos ao instrutor são colocados em uma coleção HashSet . A propriedade Assigned está
definida como verdadeiro para os cursos aos quais instrutor é atribuído. A exibição usará essa propriedade para
determinar quais caixas de seleção precisam ser exibidas como selecionadas. Por fim, a lista é passada para a
exibição em ViewData .
Em seguida, adicione o código que é executado quando o usuário clica em Salvar. Substitua o método EditPost
pelo código a seguir e adicione um novo método que atualiza a propriedade de navegação Courses da entidade
Instructor.
[HttpPost]
public async Task<IActionResult> Edit(int? id, string[] selectedCourses)
{
if (id == null)
{
return NotFound();
}

instructorToUpdate,
"",
{
{
}
UpdateInstructorCourses(selectedCourses, instructorToUpdate);
try
{
}
{
}
}
UpdateInstructorCourses(selectedCourses, instructorToUpdate);
PopulateAssignedCourseData(instructorToUpdate);
return View(instructorToUpdate);
}
private void UpdateInstructorCourses(string[] selectedCourses, Instructor instructorToUpdate)
{
{
return;
}

foreach (var course in _context.Courses)
{
{
{
instructorToUpdate.CourseAssignments.Add(new CourseAssignment { InstructorID =
instructorToUpdate.ID, CourseID = course.CourseID });
}
}
else
{
{
CourseAssignment courseToRemove = instructorToUpdate.CourseAssignments.SingleOrDefault(i =>
i.CourseID == course.CourseID);
_context.Remove(courseToRemove);
}
}
}
}
A assinatura do método agora é diferente do método HttpGet Edit e, portanto, o nome do método é alterado de
EditPost para Edit novamente.
Como a exibição não tem uma coleção de entidades Course, o associador de modelos não pode atualizar
automaticamente a propriedade de navegação CourseAssignments . Em vez de usar o associador de modelos para
atualizar a propriedade de navegação CourseAssignments , faça isso no novo método UpdateInstructorCourses .
Portanto, você precisa excluir a propriedade CourseAssignments do model binding. Isso não exige nenhuma
alteração no código que chama TryUpdateModel , porque você está usando a sobrecarga da lista de permissões e
CourseAssignments não está na lista de inclusões.
Se nenhuma caixa de seleção foi marcada, o código em UpdateInstructorCourses inicializa a propriedade de

navegação CourseAssignments com uma coleção vazia e retorna:
{
{
return;
}

{
{
{
}
}
else
{
{
}
}
}
}
Em seguida, o código executa um loop em todos os cursos no banco de dados e verifica cada curso em relação
àqueles atribuídos no momento ao instrutor e em relação àqueles que foram selecionados na exibição. Para
facilitar pesquisas eficientes, as últimas duas coleções são armazenadas em objetos HashSet .
Se a caixa de seleção para um curso foi marcada, mas o curso não está na propriedade de navegação
Instructor.CourseAssignments , o curso é adicionado à coleção na propriedade de navegação.
{
{
return;
}

{
{
{
}
}
else
{
{
}
}
}
}
Se a caixa de seleção para um curso não foi marcada, mas o curso está na propriedade de navegação
Instructor.CourseAssignments , o curso é removido da propriedade de navegação.
{
{
return;
}

{
{
{
}
}
else
{
{
}
}
}
}
Atualizar as exibições Instrutor

Em Views/Instructors/Edit.cshtml, adicione um campo Cursos com uma matriz de caixas de seleção, adicionando
o código a seguir imediatamente após os elementos div para o campo Escritório e antes do elemento div
para o botão Salvar.
NOTE
Quando você colar o código no Visual Studio, as quebras de linha serão alteradas de uma forma que divide o código.
Pressione Ctrl+Z uma vez para desfazer a formatação automática. Isso corrigirá as quebras de linha para que elas se
pareçam com o que você vê aqui. O recuo não precisa ser perfeito, mas cada uma das linhas @</tr><tr> , @:<td> ,
@:</td> e @:</tr> precisa estar em uma única linha, conforme mostrado, ou você receberá um erro de tempo de
execução. Com o bloco de novo código selecionado, pressione Tab três vezes para alinhar o novo código com o código
existente. Verifique o status deste problema aqui.
<table>
<tr>
@{
int cnt = 0;
List<ContosoUniversity.Models.SchoolViewModels.AssignedCourseData> courses =
ViewBag.Courses;
foreach (var course in courses)

{
if (cnt++ % 3 == 0)
{
@:</tr><tr>
}
@:<td>
@:</td>
}
@:</tr>
}
</table>
</div>
</div>
Esse código cria uma tabela HTML que contém três colunas. Em cada coluna há uma caixa de seleção, seguida de
uma legenda que consiste no número e título do curso. Todas as caixas de seleção têm o mesmo nome
("selectedCourses"), o que informa ao associador de modelos de que elas devem ser tratadas como um grupo. O
atributo de valor de cada caixa de seleção é definido com o valor de CourseID . Quando a página é postada, o
associador de modelos passa uma matriz para o controlador que consiste nos valores CourseID para apenas as
caixas de seleção marcadas.
Quando as caixas de seleção são inicialmente renderizadas, aquelas que se destinam aos cursos atribuídos ao
instrutor têm atributos marcados, que os seleciona (exibe-os como marcados).
Execute o aplicativo, selecione a guia Instrutores e clique em Editar em um instrutor para ver a página Editar.
Altere algumas atribuições de curso e clique em Salvar. As alterações feitas são refletidas na página Índice.
NOTE
A abordagem usada aqui para editar os dados de curso do instrutor funciona bem quando há uma quantidade limitada de
cursos. Para coleções muito maiores, uma interface do usuário e um método de atualização diferentes são necessários.

Em InstructorsController.cs, exclua o método DeleteConfirmed e insira o código a seguir em seu lugar.
{
Instructor instructor = await _context.Instructors
.SingleAsync(i => i.ID == id);
var departments = await _context.Departments

.Where(d => d.InstructorID == id)
.ToListAsync();
departments.ForEach(d => d.InstructorID = null);
_context.Instructors.Remove(instructor);
}
Este código faz as seguintes alterações:

Executa o carregamento adiantado para a propriedade de navegação CourseAssignments . Você precisa
incluir isso ou o EF não reconhecerá as entidades CourseAssignment relacionadas e não as excluirá. Para
evitar a necessidade de lê-las aqui, você pode configurar a exclusão em cascata no banco de dados.
Se o instrutor a ser excluído é atribuído como administrador de qualquer departamento, remove a
atribuição de instrutor desse departamento.
Adicionar local de escritório e cursos para a página Criar

Em InstructorsController.cs, exclua os métodos HttpGet e HttpPost Create e, em seguida, adicione o seguinte
código em seu lugar:
{
var instructor = new Instructor();
return View();
}
// POST: Instructors/Create
[HttpPost]
public async Task<IActionResult> Create([Bind("FirstMidName,HireDate,LastName,OfficeAssignment")] Instructor
instructor, string[] selectedCourses)
{
if (selectedCourses != null)
{
foreach (var course in selectedCourses)
{
var courseToAdd = new CourseAssignment { InstructorID = instructor.ID, CourseID =
int.Parse(course) };
instructor.CourseAssignments.Add(courseToAdd);
}
}
{
_context.Add(instructor);
}
}
Esse código é semelhante ao que você viu nos métodos Edit , exceto que inicialmente nenhum curso está
selecionado. O método HttpGet Create chama o método PopulateAssignedCourseData , não porque pode haver
cursos selecionados, mas para fornecer uma coleção vazia para o loop foreach na exibição (caso contrário, o
código de exibição gera uma exceção de referência nula).
O método HttpPost Create adiciona cada curso selecionado à propriedade de navegação CourseAssignments
antes que ele verifica se há erros de validação e adiciona o novo instrutor ao banco de dados. Os cursos são
adicionados, mesmo se há erros de modelo, de modo que quando houver erros de modelo (por exemplo, o
usuário inseriu uma data inválida) e a página for exibida novamente com uma mensagem de erro, as seleções de
cursos que foram feitas sejam restauradas automaticamente.
Observe que para poder adicionar cursos à propriedade de navegação CourseAssignments , é necessário inicializar
a propriedade como uma coleção vazia:
Como alternativa a fazer isso no código do controlador, faça isso no modelo Instrutor alterando o getter de
propriedade para criar automaticamente a coleção se ela não existir, conforme mostrado no seguinte exemplo:
private ICollection<CourseAssignment> _courseAssignments;
public ICollection<CourseAssignment> CourseAssignments
{
get
{
return _courseAssignments ?? (_courseAssignments = new List<CourseAssignment>());
}
set
{
_courseAssignments = value;
}
}
Se você modificar a propriedade CourseAssignments dessa forma, poderá remover o código de inicialização de
propriedade explícita no controlador.
Em Views/Instructor/Create.cshtml, adicione uma caixa de texto de local do escritório e caixas de seleção para
cursos antes do botão Enviar. Como no caso da página Editar, corrija a formatação se o Visual Studio reformatar
o código quando você o colar.
<label asp-for="OfficeAssignment.Location" class="control-label"></label>
<input asp-for="OfficeAssignment.Location" class="form-control" />
<span asp-validation-for="OfficeAssignment.Location" class="text-danger" />
</div>
<table>
<tr>
@{
int cnt = 0;
List<ContosoUniversity.Models.SchoolViewModels.AssignedCourseData> courses =
ViewBag.Courses;
foreach (var course in courses)

{
if (cnt++ % 3 == 0)
{
@:</tr><tr>
}
@:<td>
@:</td>
}
@:</tr>
}
</table>
</div>
</div>
Faça o teste executando o aplicativo e criando um instrutor.
Manipulando transações
Conforme explicado no tutorial do CRUD, o Entity Framework implementa transações de forma implícita. Para
cenários em que você precisa de mais controle – por exemplo, se desejar incluir operações feitas fora do Entity
Framework em uma transação –, consulte Transações.
Resumo
Agora você concluiu a introdução ao trabalho com os dados relacionados. No próximo tutorial, você verá como
lidar com conflitos de simultaneidade.
ASP.NET Core MVC com EF Core – simultaneidade –
8 de 10
2.0.
Páginas do Razor:
Nos tutoriais anteriores, você aprendeu a atualizar dados. Este tutorial mostra como lidar com conflitos quando
os mesmos usuários atualizam a mesma entidade simultaneamente.
Você criará páginas da Web que funcionam com a entidade Department e tratará erros de simultaneidade. As
ilustrações a seguir mostram as páginas Editar e Excluir, incluindo algumas mensagens exibidas se ocorre um
conflito de simultaneidade.
Conflitos de simultaneidade
Um conflito de simultaneidade ocorre quando um usuário exibe dados de uma entidade para editá-los e, em
seguida, outro usuário atualiza os mesmos dados da entidade antes que a primeira alteração do usuário seja
gravada no banco de dados. Se você não habilitar a detecção desses conflitos, a última pessoa que atualizar o
banco de dados substituirá as outras alterações do usuário. Em muitos aplicativos, esse risco é aceitável: se
houver poucos usuários ou poucas atualizações ou se não for realmente crítico se algumas alterações forem
substituídas, o custo de programação para simultaneidade poderá superar o benefício. Nesse caso, você não
precisa configurar o aplicativo para lidar com conflitos de simultaneidade.
Simultaneidade pessimista (bloqueio )
Se o aplicativo precisar evitar a perda acidental de dados em cenários de simultaneidade, uma maneira de fazer
isso será usar bloqueios de banco de dados. Isso é chamado de simultaneidade pessimista. Por exemplo, antes de
ler uma linha de um banco de dados, você solicita um bloqueio para o acesso somente leitura ou de atualização.
Se você bloquear uma linha para o acesso de atualização, nenhum outro usuário terá permissão para bloquear a
linha para o acesso somente leitura ou de atualização, porque ele obterá uma cópia dos dados que estão sendo
alterados. Se você bloquear uma linha para o acesso somente leitura, outros também poderão bloqueá-la para o
acesso somente leitura, mas não para atualização.
O gerenciamento de bloqueios traz desvantagens. Ele pode ser complexo de ser programado. Exige recursos de
gerenciamento de banco de dados significativos e pode causar problemas de desempenho, conforme o número
de usuários de um aplicativo aumenta. Por esses motivos, nem todos os sistemas de gerenciamento de banco de
dados dão suporte à simultaneidade pessimista. O Entity Framework Core não fornece nenhum suporte interno
para ele, e este tutorial não mostra como implementá-lo.
Simultaneidade otimista
A alternativa à simultaneidade pessimista é a simultaneidade otimista. Simultaneidade otimista significa permitir
que conflitos de simultaneidade ocorram e responder adequadamente se eles ocorrerem. Por exemplo, Alice visita
a página Editar Departamento e altera o valor do Orçamento para o departamento de inglês de US$ 350.000,00
para US$ 0,00.
Antes que Alice clique em Salvar, Julio visita a mesma página e altera o campo Data de Início de 1/9/2007 para
1/9/2013.
Alice clica em Salvar primeiro e vê a alteração quando o navegador retorna à página Índice.
Em seguida, Julio clica em Salvar em uma página Editar que ainda mostra um orçamento de US$ 350.000,00. O
que acontece em seguida é determinado pela forma como você lida com conflitos de simultaneidade.
Algumas das opções incluem o seguinte:
Controle qual propriedade um usuário modificou e atualize apenas as colunas correspondentes no banco
de dados.
No cenário de exemplo, nenhum dado é perdido, porque propriedades diferentes foram atualizadas pelos
dois usuários. Na próxima vez que alguém navegar pelo departamento de inglês, verá as alterações de
Alice e de Julio – a data de início de 1/9/2013 e um orçamento de zero dólar. Esse método de atualização
pode reduzir a quantidade de conflitos que podem resultar em perda de dados, mas ele não poderá evitar a
perda de dados se forem feitas alterações concorrentes à mesma propriedade de uma entidade. Se o Entity
Framework funciona dessa maneira depende de como o código de atualização é implementado.
Geralmente, isso não é prático em um aplicativo Web, porque pode exigir que você mantenha grandes
quantidades de estado para manter o controle de todos os valores de propriedade originais de uma
entidade, bem como novos valores. A manutenção de grandes quantidades de estado pode afetar o
desempenho do aplicativo, pois exige recursos do servidor ou deve ser incluída na própria página da Web
(por exemplo, em campos ocultos) ou em um cookie.
Você não pode deixar a alteração de Julio substituir a alteração de Alice.
Na próxima vez que alguém navegar pelo departamento de inglês, verá 1/9/2013 e o valor de US$
350.000,00 restaurado. Isso é chamado de um cenário O cliente vence ou O último vence. (Todos os
valores do cliente têm precedência sobre o conteúdo do armazenamento de dados.) Conforme observado
na introdução a esta seção, se você não fizer nenhuma codificação para a manipulação de simultaneidade,
isso ocorrerá automaticamente.
Você pode impedir que as alterações de Julio sejam atualizadas no banco de dados.
Normalmente, você exibirá uma mensagem de erro, mostrará a ele o estado atual dos dados e permitirá a
ele aplicar as alterações novamente se ele ainda desejar fazê-las. Isso é chamado de um cenário O
armazenamento vence. (Os valores do armazenamento de dados têm precedência sobre os valores
enviados pelo cliente.) Você implementará o cenário O armazenamento vence neste tutorial. Esse método
garante que nenhuma alteração é substituída sem que um usuário seja alertado sobre o que está
acontecendo.
Detectando conflitos de simultaneidade
Resolva conflitos manipulando exceções DbConcurrencyException geradas pelo Entity Framework. Para saber
quando gerar essas exceções, o Entity Framework precisa poder detectar conflitos. Portanto, é necessário
configurar o banco de dados e o modelo de dados de forma adequada. Algumas opções para habilitar a detecção
de conflitos incluem as seguintes:
Na tabela de banco de dados, inclua uma coluna de acompanhamento que pode ser usada para determinar
quando uma linha é alterada. Em seguida, configure o Entity Framework para incluir essa coluna na
cláusula Where de comandos SQL Update ou Delete.
O tipo de dados da coluna de acompanhamento é normalmente rowversion . O valor rowversion é um
número sequencial que é incrementado sempre que a linha é atualizada. Em um comando Update ou
Delete, a cláusula Where inclui o valor original da coluna de acompanhamento (a versão de linha original).
Se a linha que está sendo atualizada tiver sido alterada por outro usuário, o valor da coluna rowversion
será diferente do valor original; portanto, a instrução Update ou Delete não poderá encontrar a linha a ser
atualizada devido à cláusula Where. Quando o Entity Framework descobre que nenhuma linha foi
atualizada pelo comando Update ou Delete (ou seja, quando o número de linhas afetadas é zero), ele
interpreta isso como um conflito de simultaneidade.
Configure o Entity Framework para incluir os valores originais de cada coluna na tabela na cláusula Where
de comandos Update e Delete.
Como a primeira opção, se nada na linha for alterado desde que a linha tiver sido lida pela primeira vez, a
cláusula Where não retornará uma linha a ser atualizada, o que o Entity Framework interpretará como um
conflito de simultaneidade. Para tabelas de banco de dados que têm muitas colunas, essa abordagem pode
resultar em cláusulas Where muito grandes e pode exigir que você mantenha grandes quantidades de
estado. Conforme observado anteriormente, manter grandes quantidades de estado pode afetar o
desempenho do aplicativo. Portanto, essa abordagem geralmente não é recomendada e não é o método
usado neste tutorial.
Caso deseje implementar essa abordagem, precisará marcar todas as propriedades de chave não primária
na entidade para as quais você deseja controlar a simultaneidade adicionando o atributo ConcurrencyCheck
a elas. Essa alteração permite que o Entity Framework inclua todas as colunas na cláusula Where do SQL
de instruções Update e Delete.
No restante deste tutorial, você adicionará uma propriedade de acompanhamento rowversion à entidade
Department, criará um controlador e exibições e testará para verificar se tudo está funcionando corretamente.
Adicionar uma propriedade de controle à entidade Department

Em Models/Department.cs, adicione uma propriedade de controle chamada RowVersion:
using System;
{
{

[Timestamp]
public byte[] RowVersion { get; set; }

}
}
O atributo Timestamp especifica que essa coluna será incluída na cláusula Where de comandos Update e Delete
enviados ao banco de dados. O atributo é chamado Timestamp porque as versões anteriores do SQL Server
usavam um tipo de dados timestamp do SQL antes de o rowversion do SQL substituí-lo. O tipo do .NET para
rowversion é uma matriz de bytes.
Se preferir usar a API fluente, use o método IsConcurrencyToken (em Data/SchoolContext.cs) para especificar a
propriedade de acompanhamento, conforme mostrado no seguinte exemplo:
.Property(p => p.RowVersion).IsConcurrencyToken();
Adicionando uma propriedade, você alterou o modelo de banco de dados e, portanto, precisa fazer outra
migração.
Salve as alterações e compile o projeto e, em seguida, insira os seguintes comandos na janela Comando:
dotnet ef migrations add RowVersion
Criar um controlador e exibições Departamentos

Gere por scaffolding um controlador e exibições Departamentos, como você fez anteriormente para Alunos,
Cursos e Instrutores.
No arquivo DepartmentsController.cs, altere todas as quatro ocorrências de "FirstMidName" para "FullName", de

modo que as listas suspensas do administrador do departamento contenham o nome completo do instrutor em
vez de apenas o sobrenome.
ViewData["InstructorID"] = new SelectList(_context.Instructors, "ID", "FullName", department.InstructorID);
Atualizar a exibição Índice de Departamentos

O mecanismo de scaffolding criou uma coluna RowVersion na exibição Índice, mas esse campo não deve ser
exibido.
Substitua o código em Views/Departments/Index.cshtml pelo código a seguir.
@model IEnumerable<ContosoUniversity.Models.Department>
@{
ViewData["Title"] = "Departments";
}
<h2>Departments</h2>
<p>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Name)
</th>
<th>
@Html.DisplayNameFor(model => model.Budget)
</th>
<th>
@Html.DisplayNameFor(model => model.StartDate)
</th>
<th>
@Html.DisplayNameFor(model => model.Administrator)
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.Budget)
</td>
<td>
@Html.DisplayFor(modelItem => item.StartDate)
</td>
<td>
@Html.DisplayFor(modelItem => item.Administrator.FullName)
</td>
<td>
<a asp-action="Edit" asp-route-id="@item.DepartmentID">Edit</a> |
<a asp-action="Details" asp-route-id="@item.DepartmentID">Details</a> |
<a asp-action="Delete" asp-route-id="@item.DepartmentID">Delete</a>
</td>
</tr>
}
</tbody>
</table>
Isso altera o título "Departamentos", exclui a coluna RowVersion e mostra o nome completo em vez de o nome do
administrador.
Atualizar os métodos Edit no controlador Departamentos

Nos métodos HttpGet Edit e Details , adicione AsNoTracking . No método HttpGet Edit , adicione o
carregamento adiantado ao Administrador.
var department = await _context.Departments
.AsNoTracking()
.SingleOrDefaultAsync(m => m.DepartmentID == id);
Substitua o código existente do método HttpPost Edit pelo seguinte código:
[HttpPost]
public async Task<IActionResult> Edit(int? id, byte[] rowVersion)
{
if (id == null)
{
return NotFound();
}
var departmentToUpdate = await _context.Departments.Include(i => i.Administrator).SingleOrDefaultAsync(m

=> m.DepartmentID == id);
{
Department deletedDepartment = new Department();
await TryUpdateModelAsync(deletedDepartment);
"Unable to save changes. The department was deleted by another user.");
ViewData["InstructorID"] = new SelectList(_context.Instructors, "ID", "FullName",
deletedDepartment.InstructorID);
return View(deletedDepartment);
}
_context.Entry(departmentToUpdate).Property("RowVersion").OriginalValue = rowVersion;
departmentToUpdate,
"",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
}
{
{
"Unable to save changes. The department was deleted by another user.");
}
else
{
var databaseValues = (Department)databaseEntry.ToObject();
if (databaseValues.Name != clientValues.Name)
{
ModelState.AddModelError("Name", $"Current value: {databaseValues.Name}");
}
if (databaseValues.Budget != clientValues.Budget)
{
ModelState.AddModelError("Budget", $"Current value: {databaseValues.Budget:c}");
}
if (databaseValues.StartDate != clientValues.StartDate)
{
ModelState.AddModelError("StartDate", $"Current value: {databaseValues.StartDate:d}");
}
if (databaseValues.InstructorID != clientValues.InstructorID)
{
Instructor databaseInstructor = await _context.Instructors.SingleOrDefaultAsync(i => i.ID
== databaseValues.InstructorID);
ModelState.AddModelError("InstructorID", $"Current value:
{databaseInstructor?.FullName}");
}
ModelState.AddModelError(string.Empty, "The record you attempted to edit "

+ "was modified by another user after you got the original value. The "
+ "the Save button again. Otherwise click the Back to List hyperlink.");
departmentToUpdate.RowVersion = (byte[])databaseValues.RowVersion;
ModelState.Remove("RowVersion");
}
}
}
ViewData["InstructorID"] = new SelectList(_context.Instructors, "ID", "FullName",
departmentToUpdate.InstructorID);
return View(departmentToUpdate);
}
O código começa com a tentativa de ler o departamento a ser atualizado. Se o método SingleOrDefaultAsync
retornar nulo, isso indicará que o departamento foi excluído por outro usuário. Nesse caso, o código usa os
valores de formulário postados para criar uma entidade de departamento, de modo que a página Editar possa ser
exibida novamente com uma mensagem de erro. Como alternativa, você não precisará recriar a entidade de
departamento se exibir apenas uma mensagem de erro sem exibir novamente os campos de departamento.
A exibição armazena o valor RowVersion original em um campo oculto e esse método recebe esse valor no
parâmetro rowVersion . Antes de chamar SaveChanges , você precisa colocar isso no valor da propriedade
RowVersion original na coleção OriginalValues da entidade.
_context.Entry(departmentToUpdate).Property("RowVersion").OriginalValue = rowVersion;
Em seguida, quando o Entity Framework criar um comando SQL UPDATE, esse comando incluirá uma cláusula
WHERE que procura uma linha que tem o valor RowVersion original. Se nenhuma linha for afetada pelo
comando UPDATE (nenhuma linha tem o valor RowVersion original), o Entity Framework gerará uma exceção
DbUpdateConcurrencyException .
O código no bloco catch dessa exceção obtém a entidade Department afetada que tem os valores atualizados da
propriedade Entries no objeto de exceção.
A coleção Entries terá apenas um objeto EntityEntry . Use esse objeto para obter os novos valores inseridos
pelo usuário e os valores de banco de dados atuais.

O código adiciona uma mensagem de erro personalizada a cada coluna que tem valores de banco de dados
diferentes do que o usuário inseriu na página Editar (apenas um campo é mostrado aqui para fins de brevidade).
var databaseValues = (Department)databaseEntry.ToObject();
if (databaseValues.Name != clientValues.Name)
{
ModelState.AddModelError("Name", $"Current value: {databaseValues.Name}");
Por fim, o código define o valor RowVersion do departmentToUpdate com o novo valor recuperado do banco de
dados. Esse novo valor RowVersion será armazenado no campo oculto quando a página Editar for exibida
novamente, e na próxima vez que o usuário clicar em Salvar, somente os erros de simultaneidade que ocorrem
desde a nova exibição da página Editar serão capturados.
departmentToUpdate.RowVersion = (byte[])databaseValues.RowVersion;
ModelState.Remove("RowVersion");
A instrução ModelState.Remove é obrigatória porque ModelState tem o valor RowVersion antigo. Na exibição, o
valor ModelState de um campo tem precedência sobre os valores de propriedade do modelo, quando ambos
estão presentes.
Atualizar a exibição Editar Departamento

Em Views/Departments/Edit.cshtml, faça as seguintes alterações:
Adicione um campo oculto para salvar o valor da propriedade RowVersion , imediatamente após o campo
oculto da propriedade DepartmentID .
Adicione uma opção "Selecionar Administrador" à lista suspensa.
@model ContosoUniversity.Models.Department
@{
}
<h2>Edit</h2>
<h4>Department</h4>
<hr />
<div class="row">
<input type="hidden" asp-for="DepartmentID" />
<input type="hidden" asp-for="RowVersion" />
<label asp-for="Name" class="control-label"></label>
<input asp-for="Name" class="form-control" />
<span asp-validation-for="Name" class="text-danger"></span>
</div>
<label asp-for="Budget" class="control-label"></label>
<input asp-for="Budget" class="form-control" />
<span asp-validation-for="Budget" class="text-danger"></span>
</div>
<label asp-for="StartDate" class="control-label"></label>
<input asp-for="StartDate" class="form-control" />
<span asp-validation-for="StartDate" class="text-danger"></span>
</div>
<label asp-for="InstructorID" class="control-label"></label>
<select asp-for="InstructorID" class="form-control" asp-items="ViewBag.InstructorID">
<option value="">-- Select Administrator --</option>
</select>
<span asp-validation-for="InstructorID" class="text-danger"></span>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
Testar conflitos de simultaneidade na página Editar

Execute o aplicativo e acesse a página Índice de Departamentos. Clique com o botão direito do mouse na
hiperlink Editar do departamento de inglês e selecione Abrir em uma nova guia e, em seguida, clique no
hiperlink Editar no departamento de inglês. As duas guias do navegador agora exibem as mesmas informações.
Altere um campo na primeira guia do navegador e clique em Salvar.
O navegador mostra a página Índice com o valor alterado.
Altere um campo na segunda guia do navegador.
Clique em Salvar. Você verá uma mensagem de erro:
Clique em Salvar novamente. O valor inserido na segunda guia do navegador foi salvo. Você verá os valores
salvos quando a página Índice for exibida.

Para a página Excluir, o Entity Framework detecta conflitos de simultaneidade causados pela edição por outra
pessoa do departamento de maneira semelhante. Quando o método HttpGet Delete exibe a exibição de
confirmação, a exibição inclui o valor RowVersion original em um campo oculto. Em seguida, esse valor estará
disponível para o método HttpPost Delete chamado quando o usuário confirmar a exclusão. Quando o Entity
Framework cria o comando SQL DELETE, ele inclui uma cláusula WHERE com o valor RowVersion original. Se o
comando não resultar em nenhuma linha afetada (o que significa que a linha foi alterada após a exibição da
página Confirmação de exclusão), uma exceção de simultaneidade será gerada e o método HttpGet Delete será
chamado com um sinalizador de erro definido como verdadeiro para exibir novamente a página de confirmação
com uma mensagem de erro. Também é possível que nenhuma linha tenha sido afetada porque a linha foi
excluída por outro usuário; portanto, nesse caso, nenhuma mensagem de erro é exibida.
Atualizar os métodos Excluir no controlador Departamentos
Em DepartmentsController.cs, substitua o método HttpGet Delete pelo seguinte código:
public async Task<IActionResult> Delete(int? id, bool? concurrencyError)
{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
.SingleOrDefaultAsync(m => m.DepartmentID == id);
if (department == null)
{
{
}
return NotFound();
}
{
ViewData["ConcurrencyErrorMessage"] = "The record you attempted to delete "
+ "was modified by another user after you got the original values. "
+ "The delete operation was canceled and the current values in the "
+ "database have been displayed. If you still want to delete this "
+ "record, click the Delete button again. Otherwise "
+ "click the Back to List hyperlink.";
}
return View(department);
}
O método aceita um parâmetro opcional que indica se a página está sendo exibida novamente após um erro de
simultaneidade. Se esse sinalizador é verdadeiro e o departamento especificado não existe mais, isso indica que
ele foi excluído por outro usuário. Nesse caso, o código redireciona para a página Índice. Se esse sinalizador é
verdadeiro e o departamento existe, isso indica que ele foi alterado por outro usuário. Nesse caso, o código envia
uma mensagem de erro para a exibição usando ViewData .
Substitua o código no método HttpPost Delete (chamado DeleteConfirmed ) pelo seguinte código:
[HttpPost]
public async Task<IActionResult> Delete(Department department)
{
try
{
if (await _context.Departments.AnyAsync(m => m.DepartmentID == department.DepartmentID))
{
_context.Departments.Remove(department);
}
}
catch (DbUpdateConcurrencyException /* ex */)
{
return RedirectToAction(nameof(Delete), new { concurrencyError = true, id = department.DepartmentID
});
}
}
No código gerado por scaffolding que acabou de ser substituído, esse método aceitou apenas uma ID de registro:
Você alterou esse parâmetro para uma instância da entidade Departamento criada pelo associador de modelos.
Isso concede o acesso ao EF ao valor da propriedade RowVersion, além da chave de registro.
public async Task<IActionResult> Delete(Department department)
Você também alterou o nome do método de ação de DeleteConfirmed para Delete . O código gerado por
scaffolding usou o nome DeleteConfirmed para fornecer ao método HttpPost uma assinatura exclusiva. (O CLR
exige que métodos sobrecarregados tenham diferentes parâmetros de método.) Agora que as assinaturas são
exclusivas, você pode continuar com a convenção MVC e usar o mesmo nome para os métodos de exclusão
HttpPost e HttpGet.
Se o departamento já foi excluído, o método AnyAsync retorna falso e o aplicativo apenas volta para o método de
Índice.
Se um erro de simultaneidade é capturado, o código exibe novamente a página Confirmação de exclusão e
fornece um sinalizador que indica que ela deve exibir uma mensagem de erro de simultaneidade.
Atualizar a exibição Excluir
Em Views/Departments/Delete.cshtml, substitua o código gerado por scaffolding pelo seguinte código que
adiciona um campo de mensagem de erro e campos ocultos às propriedades DepartmentID e RowVersion. As
alterações são realçadas.
@{
}
<h2>Delete</h2>
<p class="text-danger">@ViewData["ConcurrencyErrorMessage"]</p>

<div>
<h4>Department</h4>
<hr />
<dt>
</dt>
<dd>
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.Budget)
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.StartDate)
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.Administrator.FullName)
</dd>
</dl>
<form asp-action="Delete">
<input type="hidden" asp-for="DepartmentID" />
<input type="hidden" asp-for="RowVersion" />
</div>
</form>
</div>
Isso faz as seguintes alterações:

Adiciona uma mensagem de erro entre os cabeçalhos h2 e h3 .
Substitua FirstMidName por FullName no campo Administrador.
Remove o campo RowVersion.
Adiciona um campo oculto à propriedade RowVersion .
Execute o aplicativo e acesse a página Índice de Departamentos. Clique com o botão direito do mouse na
hiperlink Excluir do departamento de inglês e selecione Abrir em uma nova guia e, em seguida, na primeira
guia, clique no hiperlink Editar no departamento de inglês.
Na primeira janela, altere um dos valores e clique em Salvar:
Na segunda guia, clique em Excluir. Você verá a mensagem de erro de simultaneidade e os valores de
Departamento serão atualizados com o que está atualmente no banco de dados.
Se você clicar em Excluir novamente, será redirecionado para a página Índice, que mostra que o departamento
foi excluído.
Exibições Atualizar Detalhes e Criar

Opcionalmente, você pode limpar o código gerado por scaffolding nas exibições Detalhes e Criar.
Substitua o código em Views/Departments/Details.cshtml para excluir a coluna RowVersion e mostrar o nome
completo do Administrador.
@{
}
<h2>Details</h2>
<div>
<h4>Department</h4>
<hr />
<dt>
</dt>
<dd>
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.Budget)
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.StartDate)
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.Administrator.FullName)
</dd>
</dl>
</div>
<div>
<a asp-action="Edit" asp-route-id="@Model.DepartmentID">Edit</a> |
</div>
Substitua o código em Views/Departments/Create.cshtml para adicionar uma opção Selecionar à lista suspensa.
@{
}
<h2>Create</h2>
<h4>Department</h4>
<hr />
<div class="row">
<label asp-for="Name" class="control-label"></label>
<input asp-for="Name" class="form-control" />
<span asp-validation-for="Name" class="text-danger"></span>
</div>
<label asp-for="Budget" class="control-label"></label>
<input asp-for="Budget" class="form-control" />
<span asp-validation-for="Budget" class="text-danger"></span>
</div>
<label asp-for="StartDate" class="control-label"></label>
<input asp-for="StartDate" class="form-control" />
<span asp-validation-for="StartDate" class="text-danger"></span>
</div>
<label asp-for="InstructorID" class="control-label"></label>
<select asp-for="InstructorID" class="form-control" asp-items="ViewBag.InstructorID">
<option value="">-- Select Administrator --</option>
</select>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
Resumo
Isso conclui a introdução à manipulação de conflitos de simultaneidade. Para obter mais informações sobre como
lidar com a simultaneidade no EF Core, consulte Conflitos de simultaneidade. O próximo tutorial mostra como
implementar a herança de tabela por hierarquia para as entidades Instructor e Student.
ASP.NET Core MVC com EF Core – herança – 9 de
10
versão 2.0.
Páginas do Razor:
usando o Entity Framework Core e o Visual Studio. Para obter informações sobre a série de tutoriais, consulte
primeiro tutorial na série.
No tutorial anterior, você tratou exceções de simultaneidade. Este tutorial mostrará como implementar a herança
no modelo de dados.
Na programação orientada a objeto, você pode usar a herança para facilitar a reutilização de código. Neste
tutorial, você alterará as classes Instructor e Student , de modo que elas derivem de uma classe base Person
que contém propriedades, como LastName , comuns a instrutores e alunos. Você não adicionará nem alterará as
páginas da Web, mas alterará uma parte do código, e essas alterações serão refletidas automaticamente no
banco de dados.
Opções para o mapeamento de herança para as tabelas de banco de

dados
As classes Instructor e Student no modelo de dados Escola têm várias propriedades idênticas:
Suponha que você deseje eliminar o código redundante para as propriedades compartilhadas pelas entidades
Instructor e Student . Ou você deseja escrever um serviço que pode formatar nomes sem se preocupar se o
nome foi obtido de um instrutor ou um aluno. Você pode criar uma classe base Person que contém apenas
essas propriedades compartilhadas e, em seguida, fazer com que as classes Instructor e Student herdem
dessa classe base, conforme mostrado na seguinte ilustração:
Há várias maneiras pelas quais essa estrutura de herança pode ser representada no banco de dados. Você pode
ter uma tabela Person que inclui informações sobre alunos e instrutores em uma única tabela. Algumas das
colunas podem se aplicar somente a instrutores (HireDate), algumas somente a alunos (EnrollmentDate) e
outras a ambos (LastName, FirstName). Normalmente, você terá uma coluna discriminatória para indicar qual
tipo cada linha representa. Por exemplo, a coluna discriminatória pode ter "Instrutor" para instrutores e "Aluno"
para alunos.
Esse padrão de geração de uma estrutura de herança de entidade com base em uma tabela de banco de dados
individual é chamado de herança TPH (tabela por hierarquia).
Uma alternativa é fazer com que o banco de dados se pareça mais com a estrutura de herança. Por exemplo,
você pode ter apenas os campos de nome na tabela Pessoa e as tabelas separadas Instrutor e Aluno com os
campos de data.
Esse padrão de criação de uma tabela de banco de dados para cada classe de entidade é chamado de herança
TPT (tabela por tipo).
Outra opção é mapear todos os tipos não abstratos para tabelas individuais. Todas as propriedades de uma
classe, incluindo propriedades herdadas, são mapeadas para colunas da tabela correspondente. Esse padrão é
chamado de herança TPC (Tabela por Classe Concreta). Se você tiver implementado a herança TPC para as
classes Person, Student e Instructor, conforme mostrado anteriormente, as tabelas Aluno e Instrutor não
parecerão diferentes após a implementação da herança do que antes.
Em geral, os padrões de herança TPC e TPH oferecem melhor desempenho do que os padrões de herança TPT,
porque os padrões TPT podem resultar em consultas de junção complexas.
Este tutorial demonstra como implementar a herança TPH. TPH é o único padrão de herança compatível com o
Entity Framework Core. O que você fará é criar uma classe Person , alterar as classes Instructor e Student
para que elas derivem de Person , adicionar a nova classe ao DbContext e criar uma migração.
TIP
Considere a possibilidade de salvar uma cópia do projeto antes de fazer as alterações a seguir. Em seguida, se você tiver
problemas e precisar recomeçar, será mais fácil começar do projeto salvo, em vez de reverter as etapas executadas para
este tutorial ou voltar ao início da série inteira.
Criar a classe Person

Na pasta Models, crie Person.cs e substitua o código de modelo pelo seguinte código:
{
public abstract class Person
{
[Required]
[StringLength(50)]
[Required]

{
get
{
}
}
}
}
Fazer com que as classes Student e Instructor herdem de Person

Em Instructor.cs, derive a classe Instructor da classe Person e remova os campos de nome e chave. O código será
semelhante ao seguinte exemplo:
using System;
{
public class Instructor : Person
{

}
}
Faça as mesmas alterações em Student.cs.

using System;
{
public class Student : Person
{

}
}
Adicionar o tipo de entidade Person ao modelo de dados

Adicione o tipo de entidade Person a SchoolContext.cs. As novas linhas são realçadas.
{
{
{
}

public DbSet<Person> People { get; set; }

{
modelBuilder.Entity<Person>().ToTable("Person");
}
}
}
Isso é tudo o que o Entity Framework precisa para configurar a herança de tabela por hierarquia. Como você
verá, quando o banco de dados for atualizado, ele terá uma tabela Pessoa no lugar das tabelas Aluno e Instrutor.
Criar e personalizar o código de migração
Salve as alterações e compile o projeto. Em seguida, abra a janela Comando na pasta do projeto e insira o
seguinte comando:
dotnet ef migrations add Inheritance
Não execute o comando database update ainda. Esse comando resultará em perda de dados porque ele
removerá a tabela Instrutor e renomeará a tabela Aluno como Pessoa. Você precisa fornecer o código
personalizado para preservar os dados existentes.
Abra Migrations/<timestamp>_Inheritance.cs e substitua o método Up pelo seguinte código:

{
migrationBuilder.DropForeignKey(
name: "FK_Enrollment_Student_StudentID",
table: "Enrollment");
migrationBuilder.DropIndex(name: "IX_Enrollment_StudentID", table: "Enrollment");
migrationBuilder.RenameTable(name: "Instructor", newName: "Person");

migrationBuilder.AddColumn<DateTime>(name: "EnrollmentDate", table: "Person", nullable: true);
migrationBuilder.AddColumn<string>(name: "Discriminator", table: "Person", nullable: false, maxLength:
128, defaultValue: "Instructor");
migrationBuilder.AlterColumn<DateTime>(name: "HireDate", table: "Person", nullable: true);
migrationBuilder.AddColumn<int>(name: "OldId", table: "Person", nullable: true);
// Copy existing Student data into new Person table.

migrationBuilder.Sql("INSERT INTO dbo.Person (LastName, FirstName, HireDate, EnrollmentDate,
Discriminator, OldId) SELECT LastName, FirstName, null AS HireDate, EnrollmentDate, 'Student' AS
Discriminator, ID AS OldId FROM dbo.Student");
// Fix up existing relationships to match new PK's.
migrationBuilder.Sql("UPDATE dbo.Enrollment SET StudentId = (SELECT ID FROM dbo.Person WHERE OldId =
Enrollment.StudentId AND Discriminator = 'Student')");
// Remove temporary key

migrationBuilder.DropColumn(name: "OldID", table: "Person");
name: "Student");
migrationBuilder.CreateIndex(
name: "IX_Enrollment_StudentID",
table: "Enrollment",
column: "StudentID");
migrationBuilder.AddForeignKey(
name: "FK_Enrollment_Person_StudentID",
table: "Enrollment",
column: "StudentID",
principalTable: "Person",
principalColumn: "ID",
onDelete: ReferentialAction.Cascade);
}
Este código é responsável pelas seguintes tarefas de atualização de banco de dados:

Remove as restrições de chave estrangeira e índices que apontam para a tabela Aluno.
Renomeia a tabela Instrutor como Pessoa e faz as alterações necessárias para que ela armazene dados de
Aluno:
Adiciona EnrollmentDate que permite valo nulo para os alunos.
Adiciona a coluna Discriminatória para indicar se uma linha refere-se a um aluno ou um instrutor.
Faz com que HireDate permita valor nulo, pois linhas de alunos não terão datas de contratação.
Adiciona um campo temporário que será usado para atualizar chaves estrangeiras que apontam para
alunos. Quando você copiar os alunos para a tabela Person, eles receberão novos valores de chave
primária.
Copia os dados da tabela Aluno para a tabela Pessoa. Isso faz com que os alunos recebam novos valores
de chave primária.
Corrige valores de chave estrangeira que apontam para alunos.
Recria restrições de chave estrangeira e índices, agora apontando-os para a tabela Person.
(Se você tiver usado o GUID, em vez de inteiro como o tipo de chave primária, os valores de chave primária dos
alunos não precisarão ser alterados e várias dessas etapas poderão ser omitidas.)
Execute o comando database update :
(Em um sistema de produção, você fará as alterações correspondentes no método Down , caso já tenha usado
isso para voltar à versão anterior do banco de dados. Para este tutorial, você não usará o método Down .)
NOTE
É possível receber outros erros ao fazer alterações de esquema em um banco de dados que contém dados existentes. Se
você receber erros de migração que não consegue resolver, altere o nome do banco de dados na cadeia de conexão ou
exclua o banco de dados. Com um novo banco de dados, não há nenhum dado a ser migrado e o comando de atualização
de banco de dados terá uma probabilidade maior de ser concluído sem erros. Para excluir o banco de dados, use o SSOX
ou execute o comando database drop da CLI.
Testar com a herança implementada

Execute o aplicativo e teste várias páginas. Tudo funciona da mesma maneira que antes.
No Pesquisador de Objetos do SQL Server, expanda Data Connections/SchoolContext e, em seguida,
Tabelas e você verá que as tabelas Aluno e Instrutor foram substituídas por uma tabela Pessoa. Abra o designer
de tabela Pessoa e você verá que ela contém todas as colunas que costumavam estar nas tabelas Aluno e
Instrutor.
Clique com o botão direito do mouse na tabela Person e, em seguida, clique em Mostrar Dados da Tabela
para ver a coluna discriminatória.
Resumo
Você implementou a herança de tabela por hierarquia para as classes Person , Student e Instructor . Para
obter mais informações sobre a herança no Entity Framework Core, consulte Herança. No próximo tutorial, você
verá como lidar com uma variedade de cenários relativamente avançados do Entity Framework.
ASP.NET Core MVC com EF Core – avançado – 10
de 10
versão 2.0.
Páginas do Razor:
No tutorial anterior, você implementou a herança de tabela por hierarquia. Este tutorial apresenta vários tópicos
que são úteis para consideração quando você vai além dos conceitos básicos de desenvolvimento de aplicativos
Web ASP.NET Core que usam o Entity Framework Core.
Consultas SQL brutas

Uma das vantagens de usar o Entity Framework é que ele evita vincular o código de forma muito próxima a um
método específico de armazenamento de dados. Ele faz isso pela geração de consultas SQL e comandos para
você, que também libera você da necessidade de escrevê-los. Mas há casos excepcionais em que você precisa
executar consultas SQL específicas criadas manualmente. Para esses cenários, a API do Code First do Entity
Framework inclui métodos que permitem passar comandos SQL diretamente para o banco de dados. Você tem
as seguintes opções no EF Core 1.0:
Use o método DbSet.FromSql para consultas que retornam tipos de entidade. Os objetos retornados
precisam ser do tipo esperado pelo objeto DbSet e são controlados automaticamente pelo contexto de
banco de dados, a menos que você desative o controle.
Use o Database.ExecuteSqlCommand para comandos que não sejam de consulta.
Caso precise executar uma consulta que retorna tipos que não são entidades, use o ADO.NET com a conexão de
banco de dados fornecida pelo EF. Os dados retornados não são controlados pelo contexto de banco de dados,
mesmo se esse método é usado para recuperar tipos de entidade.
Como é sempre verdadeiro quando você executa comandos SQL em um aplicativo Web, é necessário tomar
precauções para proteger o site contra ataques de injeção de SQL. Uma maneira de fazer isso é usar consultas
parametrizadas para garantir que as cadeias de caracteres enviadas por uma página da Web não possam ser
interpretadas como comandos SQL. Neste tutorial, você usará consultas parametrizadas ao integrar a entrada do
usuário a uma consulta.
Chamar uma consulta que retorna entidades

A classe DbSet<TEntity> fornece um método que você pode usar para executar uma consulta que retorna uma
entidade do tipo TEntity . Para ver como isso funciona, você alterará o código no método Details do
controlador Departamento.
Em DepartmentsController.cs, no método Details , substitua o código que recupera um departamento com uma
chamada de método FromSql , conforme mostrado no seguinte código realçado:

{
if (id == null)
{
return NotFound();
}
string query = "SELECT * FROM Department WHERE DepartmentID = {0}";

.FromSql(query, id)
.AsNoTracking()
.SingleOrDefaultAsync();
if (department == null)
{
return NotFound();
}
return View(department);
}
Para verificar se o novo código funciona corretamente, selecione a guia Departamentos e, em seguida,
Detalhes de um dos departamentos.
Chamar uma consulta que retorna outros tipos
Anteriormente, você criou uma grade de estatísticas de alunos para a página Sobre que mostrava o número de
alunos para cada data de registro. Você obteve os dados do conjunto de entidades Students ( _context.Students )
e usou o LINQ para projetar os resultados em uma lista de objetos de modelo de exibição EnrollmentDateGroup .
Suponha que você deseje gravar o próprio SQL em vez de usar LINQ. Para fazer isso, você precisa executar uma
consulta SQL que retorna algo diferente de objetos de entidade. No EF Core 1.0, uma maneira de fazer isso é
escrever um código ADO.NET e obter a conexão de banco de dados do EF.
Em HomeController.cs, substitua o método About pelo seguinte código:
public async Task<ActionResult> About()
{
List<EnrollmentDateGroup> groups = new List<EnrollmentDateGroup>();
var conn = _context.Database.GetDbConnection();
try
{
await conn.OpenAsync();
using (var command = conn.CreateCommand())
{
string query = "SELECT EnrollmentDate, COUNT(*) AS StudentCount "
+ "FROM Person "
+ "WHERE Discriminator = 'Student' "
+ "GROUP BY EnrollmentDate";
command.CommandText = query;
DbDataReader reader = await command.ExecuteReaderAsync();
if (reader.HasRows)
{
while (await reader.ReadAsync())
{
var row = new EnrollmentDateGroup { EnrollmentDate = reader.GetDateTime(0), StudentCount
= reader.GetInt32(1) };
groups.Add(row);
}
}
reader.Dispose();
}
}
finally
{
conn.Close();
}
return View(groups);
}
Adicionar uma instrução using:
using System.Data.Common;
Execute o aplicativo e acesse a página Sobre. Ela exibe os mesmos dados que antes.
Chamar uma consulta de atualização

Suponha que os administradores do Contoso University desejem executar alterações globais no banco de dados,
como alterar o número de créditos para cada curso. Se a universidade tiver uma grande quantidade de cursos,
poderá ser ineficiente recuperá-los como entidades e alterá-los individualmente. Nesta seção, você implementará
uma página da Web que permite ao usuário especificar um fator pelo qual alterar o número de créditos para
todos os cursos e você fará a alteração executando uma instrução SQL UPDATE. A página da Web será
semelhante à seguinte ilustração:
Em CoursesController.cs, adicione métodos UpdateCourseCredits para HttpGet e HttpPost:
public IActionResult UpdateCourseCredits()

{
return View();
}
[HttpPost]
public async Task<IActionResult> UpdateCourseCredits(int? multiplier)
{
if (multiplier != null)
{
ViewData["RowsAffected"] =
await _context.Database.ExecuteSqlCommandAsync(
"UPDATE Course SET Credits = Credits * {0}",
parameters: multiplier);
}
return View();
}
Quando o controlador processa uma solicitação HttpGet, nada é retornado em ViewData["RowsAffected"] , e a

exibição mostra uma caixa de texto vazia e um botão Enviar, conforme mostrado na ilustração anterior.
Quando o botão Atualizar recebe um clique, o método HttpPost é chamado e multiplicador tem o valor inserido
na caixa de texto. Em seguida, o código executa o SQL que atualiza os cursos e retorna o número de linhas
afetadas para a exibição em ViewData . Quando a exibição obtém um valor RowsAffected , ela mostra o número
de linhas atualizadas.
No Gerenciador de Soluções, clique com o botão direito do mouse na pasta Views/Courses e, em seguida,
clique em Adicionar > Novo Item.
Na caixa de diálogo Adicionar Novo Item, clique em ASP.NET em Instalado no painel esquerdo, clique em
Página de Exibição MVC e nomeie a nova exibição UpdateCourseCredits.cshtml.
Em Views/Courses/UpdateCourseCredits.cshtml, substitua o código de modelo pelo seguinte código:
@{
ViewBag.Title = "UpdateCourseCredits";
}
<h2>Update Course Credits</h2>
@if (ViewData["RowsAffected"] == null)

{
<form asp-action="UpdateCourseCredits">
<p>
Enter a number to multiply every course's credits by: @Html.TextBox("multiplier")
</p>
<p>
<input type="submit" value="Update" class="btn btn-default" />
</p>
</div>
</form>
}
@if (ViewData["RowsAffected"] != null)
{
<p>
Number of rows updated: @ViewData["RowsAffected"]
</p>
}
<div>
@Html.ActionLink("Back to List", "Index")
</div>
Execute o método UpdateCourseCredits selecionando a guia Cursos, adicionando, em seguida,

"/UpdateCourseCredits" ao final da URL na barra de endereços do navegador (por exemplo:
http://localhost:5813/Courses/UpdateCourseCredits ). Insira um número na caixa de texto:
Clique em Atualizar. O número de linhas afetadas é exibido:

Clique em Voltar para a Lista para ver a lista de cursos com o número revisado de créditos.
Observe que o código de produção deve garantir que as atualizações sempre resultem em dados válidos. O
código simplificado mostrado aqui pode multiplicar o número de créditos o suficiente para resultar em números
maiores que 5. (A propriedade Credits tem um atributo [Range(0, 5)] .) A consulta de atualização funciona,
mas os dados inválidos podem causar resultados inesperados em outras partes do sistema que supõem que o
número de créditos seja 5 ou inferior.
Para obter mais informações sobre consultas SQL brutas, consulte Consultas SQL brutas.
Examinar o SQL enviado ao banco de dados

Às vezes, é útil poder ver as consultas SQL reais que são enviadas ao banco de dados. A funcionalidade de log
interno do ASP.NET Core é usada automaticamente pelo EF Core para gravar logs que contêm o SQL de
consultas e atualizações. Nesta seção, você verá alguns exemplos de log do SQL.
Abra StudentsController.cs e, no método Details , defina um ponto de interrupção na instrução
if (student == null) .
Execute o aplicativo no modo de depuração e acesse a página Detalhes de um aluno.

Acesse a janela de Saída mostrando a saída de depuração e você verá a consulta:
Microsoft.EntityFrameworkCore.Database.Command:Information: Executed DbCommand (56ms) [Parameters=

[@__id_0='?'], CommandType='Text', CommandTimeout='30']
SELECT TOP(2) [s].[ID], [s].[Discriminator], [s].[FirstName], [s].[LastName], [s].[EnrollmentDate]
FROM [Person] AS [s]
WHERE ([s].[Discriminator] = N'Student') AND ([s].[ID] = @__id_0)
ORDER BY [s].[ID]
Microsoft.EntityFrameworkCore.Database.Command:Information: Executed DbCommand (122ms) [Parameters=
[@__id_0='?'], CommandType='Text', CommandTimeout='30']
SELECT [s.Enrollments].[EnrollmentID], [s.Enrollments].[CourseID], [s.Enrollments].[Grade], [s.Enrollments].
[StudentID], [e.Course].[CourseID], [e.Course].[Credits], [e.Course].[DepartmentID], [e.Course].[Title]
FROM [Enrollment] AS [s.Enrollments]
INNER JOIN [Course] AS [e.Course] ON [s.Enrollments].[CourseID] = [e.Course].[CourseID]
INNER JOIN (
SELECT TOP(1) [s0].[ID]
FROM [Person] AS [s0]
WHERE ([s0].[Discriminator] = N'Student') AND ([s0].[ID] = @__id_0)
ORDER BY [s0].[ID]
) AS [t] ON [s.Enrollments].[StudentID] = [t].[ID]
ORDER BY [t].[ID]
Você observará algo aqui que pode ser surpreendente: o SQL seleciona até 2 linhas ( TOP(2) ) da tabela Person.
O método SingleOrDefaultAsync não é resolvido para uma 1 linha no servidor. Eis o porquê:
Se a consulta retorna várias linhas, o método retorna nulo.
Para determinar se a consulta retorna várias linhas, o EF precisa verificar se ela retorna pelo menos 2.
Observe que você não precisa usar o modo de depuração e parar em um ponto de interrupção para obter a saída
de log na janela de Saída. É apenas um modo conveniente de parar o log no ponto em que você deseja examinar
a saída. Se você não fizer isso, o log continuará e você precisará rolar para baixo para localizar as partes de seu
interesse.
Padrões de repositório e unidade de trabalho

Muitos desenvolvedores escrevem um código para implementar padrões de repositório e unidade de trabalho
como um wrapper em torno do código que funciona com o Entity Framework. Esses padrões destinam-se a criar
uma camada de abstração entre a camada de acesso a dados e a camada da lógica de negócios de um aplicativo.
A implementação desses padrões pode ajudar a isolar o aplicativo de alterações no armazenamento de dados e
pode facilitar o teste de unidade automatizado ou TDD (desenvolvimento orientado por testes). No entanto,
escrever um código adicional para implementar esses padrões nem sempre é a melhor escolha para aplicativos
que usam o EF, por vários motivos:
A própria classe de contexto do EF isola o código de código específico a um armazenamento de dados.
A classe de contexto do EF pode atuar como uma classe de unidade de trabalho para as atualizações de
banco de dados feitas com o EF.
O EF inclui recursos para implementar o TDD sem escrever um código de repositório.
Para obter informações sobre como implementar os padrões de repositório e unidade de trabalho, consulte a
versão do Entity Framework 5 desta série de tutoriais.
O Entity Framework Core implementa um provedor de banco de dados em memória que pode ser usado para
teste. Para obter mais informações, confira Testar com InMemory.
Detecção automática de alterações

O Entity Framework determina como uma entidade foi alterada (e, portanto, quais atualizações precisam ser
enviadas ao banco de dados), comparando os valores atuais de uma entidade com os valores originais. Os
valores originais são armazenados quando a entidade é consultada ou anexada. Alguns dos métodos que
causam a detecção automática de alterações são os seguintes:
DbContext.SaveChanges
DbContext.Entry
ChangeTracker.Entries
Se você estiver controlando um grande número de entidades e chamar um desses métodos muitas vezes em um
loop, poderá obter melhorias significativas de desempenho desativando temporariamente a detecção automática
de alterações usando a propriedade ChangeTracker.AutoDetectChangesEnabled . Por exemplo:
_context.ChangeTracker.AutoDetectChangesEnabled = false;
Código-fonte e planos de desenvolvimento do Entity Framework Core

O código-fonte do Entity Framework Core está em https://github.com/aspnet/EntityFrameworkCore. O
repositório do EF Core contém builds noturnos, acompanhamento de questões, especificações de recurso, notas
de reuniões de design e o roteiro para desenvolvimento futuro. Arquive ou encontre bugs e contribua.
Embora o código-fonte seja aberto, há suporte completo para o Entity Framework Core como um produto
Microsoft. A equipe do Microsoft Entity Framework mantém controle sobre quais contribuições são aceitas e
testa todas as alterações de código para garantir a qualidade de cada versão.
Fazer engenharia reversa do banco de dados existente

Para fazer engenharia reversa de um modelo de dados, incluindo classes de entidade de um banco de dados
existente, use o comando scaffold-dbcontext. Consulte o tutorial de introdução.
Usar o LINQ dinâmico para simplificar o código de seleção de

classificação
O terceiro tutorial desta série mostra como escrever um código LINQ embutindo nomes de colunas em código
em uma instrução switch . Com duas colunas para escolha, isso funciona bem, mas se você tiver muitas colunas,
o código poderá ficar detalhado. Para resolver esse problema, use o método EF.Property para especificar o
nome da propriedade como uma cadeia de caracteres. Para usar essa abordagem, substitua o método Index no
StudentsController pelo código a seguir.

string sortOrder,
int? page)
{
ViewData["CurrentSort"] = sortOrder;
ViewData["NameSortParm"] =
String.IsNullOrEmpty(sortOrder) ? "LastName_desc" : "";
ViewData["DateSortParm"] =
sortOrder == "EnrollmentDate" ? "EnrollmentDate_desc" : "EnrollmentDate";
{
page = 1;
}
else
{
}

select s;
{
}
if (string.IsNullOrEmpty(sortOrder))
{
sortOrder = "LastName";
}
bool descending = false;

if (sortOrder.EndsWith("_desc"))
{
sortOrder = sortOrder.Substring(0, sortOrder.Length - 5);
descending = true;
}
if (descending)
{
students = students.OrderByDescending(e => EF.Property<object>(e, sortOrder));
}
else
{
students = students.OrderBy(e => EF.Property<object>(e, sortOrder));
}
int pageSize = 3;
return View(await PaginatedList<Student>.CreateAsync(students.AsNoTracking(),
page ?? 1, pageSize));
}
Próximas etapas
Isso conclui esta série de tutoriais sobre como usar o Entity Framework Core em um aplicativo ASP.NET Core
MVC.
Para obter mais informações sobre o EF Core, consulte a documentação do Entity Framework Core. Um manual
também está disponível: Entity Framework Core in Action (Entity Framework Core em ação).
Para obter informações sobre como implantar um aplicativo Web, consulte Hospedar e implantar.
Para obter informações sobre outros tópicos relacionados ao ASP.NET Core MVC, como autenticação e
autorização, consulte a documentação do ASP.NET Core.
Agradecimentos
Tom Dykstra e Rick Anderson (twitter @RickAndMSFT) escreveram este tutorial. Rowan Miller, Diego Vega e
outros membros da equipe do Entity Framework auxiliaram com revisões de código e ajudaram com problemas
de depuração que surgiram durante a codificação para os tutoriais.
Erros comuns
ContosoUniversity.dll usada por outro processo
Mensagem de erro:
Não é possível abrir '...bin\Debug\netcoreapp1.0\ContosoUniversity.dll' para gravação – 'O processo não

pode acessar o arquivo '...\bin\Debug\netcoreapp1.0\ContosoUniversity.dll' porque ele está sendo usado por
outro processo.
Solução:
Pare o site no IIS Express. Acesse a Bandeja do Sistema do Windows, localize o IIS Express e clique com o botão
direito do mouse em seu ícone, selecione o site da Contoso University e, em seguida, clique em Parar Site.
Migração gerada por scaffolding sem nenhum código nos métodos Up e Down
Possível causa:
Os comandos da CLI do EF não fecham e salvam arquivos de código automaticamente. Se você tiver alterações
não salvas ao executar o comando migrations add , o EF não encontrará as alterações.
Solução:
Execute o comando migrations remove , salve as alterações de código e execute o comando migrations add
novamente.
Erros durante a execução da atualização de banco de dados
É possível receber outros erros ao fazer alterações de esquema em um banco de dados que contém dados
existentes. Se você receber erros de migração que não consegue resolver, altere o nome do banco de dados na
cadeia de conexão ou exclua o banco de dados. Com um novo banco de dados, não há nenhum dado a ser
migrado e o comando de atualização de banco de dados terá uma probabilidade muito maior de ser concluído
sem erros.
A abordagem mais simples é renomear o banco de dados em appsettings.json. Na próxima vez que você
executar database update , um novo banco de dados será criado.
Para excluir um banco de dados no SSOX, clique com o botão direito do mouse no banco de dados, clique
Excluir e, em seguida, na caixa de diálogo Excluir Banco de Dados, selecione Fechar conexões existentes e
clique em OK.
Para excluir um banco de dados usando a CLI, execute o comando database drop da CLI:
Erro ao localizar a instância do SQL Server

Mensagem de erro:
Ocorreu um erro relacionado à rede ou específico a uma instância ao estabelecer uma conexão com o SQL
Server. O servidor não foi encontrado ou não estava acessível. Verifique se o nome da instância está correto
e se o SQL Server está configurado para permitir conexões remotas. (provedor: Adaptadores de Rede do
SQL, erro: 26 – Erro ao Localizar Servidor/Instância Especificada)
Solução:
Verifique a cadeia de conexão. Se você excluiu o arquivo de banco de dados manualmente, altere o nome do
banco de dados na cadeia de caracteres de construção para começar novamente com um novo banco de dados.
A N T E R IO R
Introdução ao ASP.NET Core e ao Entity Framework 6
Por Paweł Grudzień, Damien Pontifex e Tom Dykstra

Este artigo mostra como usar o Entity Framework 6 em um aplicativo ASP.NET Core.
Visão geral
Para usar o Entity Framework 6, o projeto precisa ser compilado no .NET Framework, pois o Entity Framework 6
não dá suporte ao .NET Core. Caso precise de recursos de multiplataforma, faça upgrade para o Entity Framework
Core.
A maneira recomendada de usar o Entity Framework 6 em um aplicativo ASP.NET Core é colocar o contexto e as
classes de modelo do EF6 em um projeto de biblioteca de classes direcionado à estrutura completa. Adicione uma
referência à biblioteca de classes do projeto ASP.NET Core. Consulte a solução de exemplo do Visual Studio com
projetos EF6 e ASP.NET Core.
Não é possível colocar um contexto do EF6 em um projeto ASP.NET Core, pois projetos .NET Core não dão
suporte a todas as funcionalidades exigidas pelo EF6, como Enable-Migrations, que é obrigatória.
Seja qual for o tipo de projeto em que você localize o contexto do EF6, somente ferramentas de linha de comando
do EF6 funcionam com um contexto do EF6. Por exemplo, Scaffold-DbContext está disponível apenas no Entity
Framework Core. Caso precise fazer engenharia reversa de um banco de dados para um modelo do EF6, consulte
Usar o Code First para um banco de dados existente.
Referenciar a estrutura completa e o EF6 no projeto ASP.NET Core

O projeto ASP.NET Core precisa referenciar a estrutura .NET e o EF6. Por exemplo, o arquivo .csproj do projeto
ASP.NET Core será semelhante ao exemplo a seguir (somente as partes relevantes do arquivo são mostradas).
<PropertyGroup>
<TargetFramework>net452</TargetFramework>
<PreserveCompilationContext>true</PreserveCompilationContext>
<AssemblyName>MVCCore</AssemblyName>
<OutputType>Exe</OutputType>
<PackageId>MVCCore</PackageId>
</PropertyGroup>
Ao criar um novo projeto, use o modelo Aplicativo Web ASP.NET Core (.NET Framework).
Manipular as cadeias de conexão

As ferramentas de linha de comando do EF6 que você usará no projeto de biblioteca de classes do EF6 exigem um
construtor padrão para que possam criar uma instância do contexto. No entanto, provavelmente, você desejará
especificar a cadeia de conexão a ser usada no projeto ASP.NET Core, caso em que o construtor de contexto deve
ter um parâmetro que permita passar a cadeia de conexão. Veja um exemplo.
{
public SchoolContext(string connString) : base(connString)
{
}
Como o contexto do EF6 não tem um construtor sem parâmetros, o projeto do EF6 precisa fornecer uma
implementação de IDbContextFactory. As ferramentas de linha de comando do EF6 encontrarão e usarão essa
implementação para que possam criar uma instância do contexto. Veja um exemplo.
public class SchoolContextFactory : IDbContextFactory<SchoolContext>

{
public SchoolContext Create()
{
return new EF6.SchoolContext("Server=
(localdb)\\mssqllocaldb;Database=EF6MVCCore;Trusted_Connection=True;MultipleActiveResultSets=true");
}
}
Nesse código de exemplo, a implementação IDbContextFactory passa uma cadeia de conexão embutida em código.
Essa é a cadeia de conexão que será usada pelas ferramentas de linha de comando. Recomendamos implementar
uma estratégia para garantir que a biblioteca de classes use a mesma cadeia de conexão usada pelo aplicativo de
chamada. Por exemplo, você pode obter o valor de uma variável de ambiente em ambos os projetos.
Configurar a injeção de dependência no projeto ASP.NET Core

No arquivo Startup.cs do projeto Core, configure o contexto do EF6 para DI (injeção de dependência) em
ConfigureServices . Os objetos de contexto do EF devem ser delimitados em escopo a um tempo de vida por
solicitação.

{
services.AddMvc();
services.AddScoped<SchoolContext>(_ => new
SchoolContext(Configuration.GetConnectionString("DefaultConnection")));
}
Em seguida, você pode obter uma instância do contexto nos controladores usando a DI. O código é semelhante ao
que você escreverá para um contexto do EF Core:
public class StudentsController : Controller

{
public StudentsController(SchoolContext context)

{
_context = context;
}
Aplicativo de exemplo
Para obter um aplicativo de exemplo funcional, consulte a solução de exemplo do Visual Studio que acompanha
este artigo.
Esta amostra pode ser criada do zero pelas seguintes etapas no Visual Studio:
Crie uma solução.
Adicionar > Novo Projeto > Web > Aplicativo Web ASP.NET Core
Na caixa de diálogo de seleção de modelo do projeto, selecione API e .NET Framework na lista suspensa
Adicionar > Novo Projeto > Windows Desktop > Biblioteca de Classes (.NET Framework)
No PMC (Console do Gerenciador de Pacotes) dos dois projetos, execute o comando
Install-Package Entityframework .
No projeto de biblioteca de classes, crie classes de modelo de dados e uma classe de contexto, bem como
uma implementação de IDbContextFactory .
No PMC do projeto de biblioteca de classes, execute os comandos Enable-Migrations e
Add-Migration Initial . Caso tenha definido o projeto ASP.NET Core como o projeto de inicialização,
adicione -StartupProjectName EF6 a esses comandos.
No projeto Core, adicione uma referência de projeto ao projeto de biblioteca de classes.
No projeto Core, em Startup.cs, registre o contexto para DI.
No projeto Core, em appsettings.json, adicione a cadeia de conexão.
No projeto Core, adicione um controlador e exibições para verificar se é possível ler e gravar dados.
(Observe que o scaffolding do ASP.NET Core MVC não funcionará com o contexto do EF6 referenciado da
biblioteca de classes.)
Resumo
Este artigo forneceu diretrizes básicas para usar o Entity Framework 6 em um aplicativo ASP.NET Core.
Recursos adicionais
Entity Framework – configuração baseada em código
Desenvolvimento do lado do cliente no ASP.NET
Core
Usar o Gulp
Usar o Grunt
Usar o LibMan
LibMan CLI
LibMan no Visual Studio
Gerenciar pacotes do lado do cliente com o Bower
Criando estilos em aplicativos com o LESS, Sass e Font Awesome
Agrupar e minificar
TypeScript
Usar Link do Navegador
Usar JavaScriptServices para SPAs
Usar os modelos de projeto do SPA
Modelo de projeto Angular
Modelo de projeto React
Modelo de projeto React with Redux
Use o Gulp no ASP.NET Core
Por Scott Addie, Shayne Boyer, e Alcatrão de David

Em um aplicativo web moderno típico, o processo de compilação pode:
Agrupar e minificar arquivos JavaScript e CSS.
Execute ferramentas para chamar as tarefas de empacotamento e minimização antes de cada compilação.
Arquivos de compilar menos ou SASS para CSS.
Compile arquivos CoffeeScript ou TypeScript para JavaScript.
Um executor de tarefas é uma ferramenta que automatiza a essas tarefas de rotina de desenvolvimento e muito
mais. Visual Studio fornece suporte interno para dois executores de tarefas de baseados em JavaScript populares:
Gulp e Grunt.
Gulp
O gulp é baseado em JavaScript streaming build Kit de ferramentas para o código do lado do cliente.
Normalmente, ele é usado para transmitir arquivos do lado do cliente por meio de uma série de processos
quando um evento específico é disparado em um ambiente de compilação. Por exemplo, o Gulp pode ser usado
para automatizar agrupamento e minificação ou a limpeza de um ambiente de desenvolvimento antes de uma
nova compilação.
Um conjunto de tarefas do Gulp é definido em gulpfile. js. O seguinte JavaScript inclui módulos de Gulp e
especifica os caminhos de arquivo a ser referenciado de tarefas disponível em breve:
/// <binding Clean='clean' />

"use strict";
var gulp = require("gulp"),

rimraf = require("rimraf"),
concat = require("gulp-concat"),
cssmin = require("gulp-cssmin"),
uglify = require("gulp-uglify");
var paths = {
webroot: "./wwwroot/"
};
paths.js = paths.webroot + "js/**/*.js";

paths.minJs = paths.webroot + "js/**/*.min.js";
paths.css = paths.webroot + "css/**/*.css";
paths.minCss = paths.webroot + "css/**/*.min.css";
paths.concatJsDest = paths.webroot + "js/site.min.js";
paths.concatCssDest = paths.webroot + "css/site.min.css";
O código acima Especifica quais módulos de nó são necessários. O require função importa cada módulo para
que as tarefas dependentes podem utilizar seus recursos. Cada um dos módulos importados é atribuída a uma
variável. Os módulos podem ser localizados por nome ou caminho. Neste exemplo, os módulos denominado
gulp , rimraf , gulp-concat , gulp-cssmin , e gulp-uglify são recuperados por nome. Além disso, uma série de
caminhos são criados para que os locais dos arquivos CSS e JavaScript podem ser reutilizados e referenciados
dentro das tarefas. A tabela a seguir fornece descrições dos módulos do incluídos no gulpfile. js.
NOME DO MÓDULO DESCRIÇÃO
gulp O sistema de compilação streaming Gulp. Para obter mais

informações, consulte gulp.
rimraf Um módulo de exclusão do nó. Para obter mais informações,

consulte rimraf.
gulp-concat Um módulo que concatena arquivos com base em caractere

de nova linha do sistema operacional. Para obter mais
informações, consulte gulp-concat.
gulp cssmin Um módulo que minimiza os arquivos CSS. Para obter mais
informações, consulte gulp cssmin.
tarefa uglify gulp Um módulo que minimiza . js arquivos. Para obter mais
informações, consulte tarefa uglify gulp.
Depois que o requisito os módulos são importados, as tarefas podem ser especificadas. Aqui, há seis tarefas
registrado, representado pelo código a seguir:
gulp.task("clean:js", done => rimraf(paths.concatJsDest, done));

gulp.task("clean:css", done => rimraf(paths.concatCssDest, done));
gulp.task("clean", gulp.series(["clean:js", "clean:css"]));
gulp.task("min:js", () => {
return gulp.src([paths.js, "!" + paths.minJs], { base: "." })
.pipe(concat(paths.concatJsDest))
.pipe(uglify())
.pipe(gulp.dest("."));
});
gulp.task("min:css", () => {
return gulp.src([paths.css, "!" + paths.minCss])
.pipe(concat(paths.concatCssDest))
.pipe(cssmin())
});
gulp.task("min", gulp.series(["min:js", "min:css"]));
// A 'default' task is required by Gulp v4

gulp.task("default", gulp.series(["min"]));
A tabela a seguir fornece uma explicação sobre as tarefas especificadas no código acima:
NOME DA TAREFA DESCRIÇÃO
Limpar: js Uma tarefa que usa o módulo de exclusão do nó rimraf para

remover a versão reduzida do arquivo js.
Limpar: css Uma tarefa que usa o módulo de exclusão do nó rimraf para
remover a versão reduzida do arquivo site CSS.
Limpar Uma tarefa que chama o clean:js tarefa, seguida de

clean:css tarefa.
NOME DA TAREFA DESCRIÇÃO
min:js Uma tarefa que minimiza e concatena todos os arquivos. js na

pasta js. A. Min arquivos são excluídos.
min:CSS Uma tarefa que minimiza e concatena todos os arquivos. CSS

dentro da pasta de css. A. min.css arquivos são excluídos.
min Uma tarefa que chama o min:js tarefa, seguida de

min:css tarefa.
Execução de tarefas padrão

Se você já não tiver criado um novo aplicativo Web, crie um novo projeto de aplicativo Web ASP.NET no Visual
Studio.
1. Abra o Package. JSON arquivo (Adicionar se não existe) e adicione o seguinte.
{
"devDependencies": {
"gulp": "^4.0.0",
"gulp-concat": "2.6.1",
"gulp-cssmin": "0.2.0",
"gulp-uglify": "3.0.0",
"rimraf": "2.6.1"
}
}
2. Adicionar um novo arquivo JavaScript ao seu projeto e denomine gulpfile. js, em seguida, copie o código a
seguir.
/// <binding Clean='clean' />
"use strict";
const gulp = require("gulp"),

rimraf = require("rimraf"),
concat = require("gulp-concat"),
cssmin = require("gulp-cssmin"),
uglify = require("gulp-uglify");
const paths = {
webroot: "./wwwroot/"
};
paths.js = paths.webroot + "js/**/*.js";

paths.minJs = paths.webroot + "js/**/*.min.js";
paths.css = paths.webroot + "css/**/*.css";
paths.minCss = paths.webroot + "css/**/*.min.css";
paths.concatJsDest = paths.webroot + "js/site.min.js";
paths.concatCssDest = paths.webroot + "css/site.min.css";
gulp.task("clean:js", done => rimraf(paths.concatJsDest, done));

gulp.task("clean:css", done => rimraf(paths.concatCssDest, done));
gulp.task("clean", gulp.series(["clean:js", "clean:css"]));
gulp.task("min:js", () => {
return gulp.src([paths.js, "!" + paths.minJs], { base: "." })
.pipe(concat(paths.concatJsDest))
.pipe(uglify())
});
gulp.task("min:css", () => {
return gulp.src([paths.css, "!" + paths.minCss])
.pipe(concat(paths.concatCssDest))
.pipe(cssmin())
});
gulp.task("min", gulp.series(["min:js", "min:css"]));

gulp.task("default", gulp.series(["min"]));
3. Na Gerenciador de soluções, clique com botão direito gulpfile. jse selecione Task Runner Explorer.
Explorador do Executador de tarefas mostra a lista de tarefas de Gulp. (Talvez você precise clicar o
Refresh botão que aparece à esquerda do nome do projeto.)
IMPORTANT
O Task Runner Explorer item de menu de contexto será exibida apenas se gulpfile. js está no diretório do projeto
raiz.
4. Sob tarefas na Task Runner Explorer, clique com botão direito limpae selecione executar no menu pop-
up.
Explorador do Executador de tarefas criará uma nova guia chamada limpa e execute a tarefa limpar
conforme definido na gulpfile. js.
5. Com o botão direito do limpa da tarefa e, em seguida, selecione associações > antes da compilação.
O antes da compilação associação configura a tarefa Limpar para serem executados automaticamente
antes de cada compilação do projeto.
As associações que você configura o com Task Runner Explorer são armazenadas na forma de um comentário
na parte superior da sua gulpfile. js e entrarão em vigor apenas no Visual Studio. Uma alternativa que não requer
o Visual Studio é configurar a execução automática de tarefas de gulp em seu . csproj arquivo. Por exemplo,
colocar isso no seu . csproj arquivo:
<Target Name="MyPreCompileTarget" BeforeTargets="Build">

<Exec Command="gulp clean" />
</Target>
Agora a tarefa de limpeza é executada quando você executar o projeto no Visual Studio ou de um prompt de
comando usando o execução dotnet comando (executar npm install primeiro).
Definir e executar uma nova tarefa

Para definir uma nova tarefa Gulp, modifique gulpfile. js.
1. Adicione o seguinte JavaScript ao final da gulpfile. js:
gulp.task('first', done => {

console.log('first task! <-----');
done(); // signal completion
});
Essa tarefa é denominada first , e ele simplesmente exibe uma cadeia de caracteres.
2. Salve gulpfile. js.
3. Na Gerenciador de soluções, clique com botão direito gulpfile. jse selecione Task Runner Explorer.
4. Na Task Runner Explorer, clique com botão direito primeiroe selecione executar.
O texto de saída é exibido. Para obter exemplos com base em cenários comuns, consulte receitas do Gulp.
Definir e executar tarefas em uma série

Quando você executa várias tarefas, as tarefas executadas simultaneamente por padrão. No entanto, se você
precisar executar tarefas em uma ordem específica, você deve especificar quando cada tarefa é concluída, bem
como quais tarefas dependem da conclusão de outra tarefa.
1. Para definir uma série de tarefas a serem executados em ordem, substitua a first que você adicionou
acima na tarefa gulpfile. js com o seguinte:
gulp.task('series:first', done => {

console.log('first task! <-----');
});
gulp.task('series:second', done => {
console.log('second task! <-----');
});
gulp.task('series', gulp.series(['series:first', 'series:second']), () => { });

gulp.task('default', gulp.series('series'));
Agora você tem três tarefas: series:first , series:second , e series . O series:second tarefa inclui um
segundo parâmetro que especifica uma matriz de tarefas para serem executados e concluídos antes do
series:second tarefa será executada. Conforme especificado no código acima, somente o series:first
tarefa deve ser concluída antes do series:second tarefa será executada.
2. Salve gulpfile. js.
3. Na Gerenciador de soluções, clique com botão direito gulpfile. js e selecione Task Runner Explorer se
ainda não estiver aberto.
4. Na Task Runner Explorer, clique com botão direito série e selecione executar.
IntelliSense
IntelliSense fornece conclusão de código, descrições de parâmetro e outros recursos para aumentar a
produtividade e diminuir a erros. As tarefas de gulp são escritas em JavaScript; Portanto, o IntelliSense pode
fornecer assistência durante o desenvolvimento. Conforme você trabalha com JavaScript, o IntelliSense lista os
objetos, funções, propriedades e parâmetros que estão disponíveis com base em seu contexto atual. Selecione
uma opção de codificação na lista pop-up fornecida pelo IntelliSense para concluir o código.
Para obter mais informações sobre o IntelliSense, consulte JavaScript IntelliSense.
Ambientes de desenvolvimento, preparo e produção

Quando o Gulp é usado para otimizar arquivos do lado do cliente para produção e preparo, os arquivos
processados são salvos em um local de preparo e produção local. O layout. cshtml arquivo de usar o ambiente
auxiliar para fornecer duas versões diferentes de arquivos CSS de marcação. Uma versão de arquivos CSS é para
o desenvolvimento e a outra versão é otimizada para produção e preparo. No Visual Studio 2017, quando você
altera a ASPNETCORE_ENVIRONMENT variável de ambiente Production , Visual Studio criará o aplicativo
Web e um link para os arquivos CSS minimizados. A marcação a seguir mostra a ambiente que contém as
marcações de link para os auxiliares de marca a Development CSS arquivos e o minificado Staging, Production
arquivos CSS.
</environment>
</script>
</script>
</environment>
Alternância entre ambientes

Para alternar entre a compilação para ambientes diferentes, modifique a ASPNETCORE_ENVIRONMENT valor
da variável de ambiente.
1. No Task Runner Explorer, verifique se que o min foi definida para executar tarefas antes da
compilação.
2. Na Gerenciador de soluções, clique com botão direito no nome do projeto e selecione propriedades.
A folha de propriedades para o aplicativo Web é exibida.
3. Clique na guia Depurar.
4. Definir o valor de : ambiente de hospedagem variável de ambiente Production .
5. Pressione F5 para executar o aplicativo em um navegador.
6. Na janela do navegador, a página com o botão direito e selecione Exibir código-fonte para exibir o HTML
da página.
Observe que os links de folha de estilos apontam para os arquivos CSS minificados.
7. Feche o navegador para parar o aplicativo Web.
8. No Visual Studio, retorne para a folha de propriedades para o aplicativo Web e altere o : ambiente de
hospedagem variável de ambiente de volta para Development .
9. Pressione F5 para executar o aplicativo em um navegador novamente.
10. Na janela do navegador, a página com o botão direito e selecione Exibir código-fonte para ver o HTML
da página.
Observe que os links de folha de estilos apontam para as versões unminified dos arquivos CSS.
Para obter mais informações relacionadas aos ambientes no ASP.NET Core, consulte usar vários ambientes.
Detalhes da tarefa e o módulo

Uma tarefa Gulp está registrada com um nome de função. É possível especificar dependências se outras tarefas
devem ser executadas antes da tarefa atual. Funções adicionais permitem que você execute e assistir as tarefas de
Gulp, bem como definir a origem (src) e de destino (dest) dos arquivos que está sendo modificados. Estas são as
funções de API do Gulp primárias:
FUNÇÃO GULP SINTAXE DESCRIÇÃO
tarefa gulp.task(name[, deps], fn) { } O task função cria uma tarefa. O

name parâmetro define o nome da
tarefa. O deps parâmetro contém
uma matriz de tarefas a serem
concluídas antes que essa tarefa é
executada. O fn parâmetro
representa uma função de retorno de
chamada que executa as operações da
tarefa.
Inspeção gulp.watch(glob [, opts], tasks) O watch function monitora arquivos e

{ } execuções de tarefas quando ocorre
uma alteração de arquivo. O glob
parâmetro é um string ou array
que determina quais arquivos assistir. O
opts parâmetro fornece
monitoramento opções de arquivo
adicional.
src gulp.src(globs[, options]) { } O src função fornece os arquivos que

correspondem os valores de glob. O
glob parâmetro é um string ou
array que determina quais arquivos
para ler. O options parâmetro fornece
opções de arquivo adicionais.
dest gulp.dest(path[, options]) { } O dest função define um local para o

qual os arquivos podem ser gravados.
O path parâmetro é uma cadeia de
caracteres ou uma função que
determina a pasta de destino. O
options parâmetro é um objeto que
especifica as opções de pasta de saída.
Para obter informações de referência de API Gulp, consulte Gulp Docs API.
Receitas do gulp
A comunidade do Gulp fornece Gulp receitas. Essas receitas consistem em tarefas de Gulp para lidar com cenários
comuns.
Recursos adicionais
Documentação do gulp
Agrupamento e minificação no ASP.NET Core
Usar o Grunt no ASP.NET Core
Use o assistente no núcleo do ASP.NET
Por Noel arroz

Pesado é um executor de tarefas do JavaScript que automatiza minimização de script, a compilação TypeScript,
ferramentas de "pano" de qualidade do código, pré-processadores de CSS e praticamente qualquer tarefa
repetitiva que precisa fazer para dar suporte ao desenvolvimento de cliente. Pesado tem suporte total no Visual
Studio, embora os modelos de projeto do ASP.NET usam Gulp por padrão (consulte usar Gulp).
Este exemplo usa um projeto vazio do ASP.NET Core como ponto de partida, para mostrar como automatizar o
processo de compilação do cliente desde o início.
O exemplo concluído limpa o diretório de implantação de destino, combina arquivos JavaScript, verifica a
qualidade do código, condensa o conteúdo do arquivo JavaScript e implanta para a raiz do seu aplicativo web.
Usaremos os seguintes pacotes:
Assistente de: pacote de executor de tarefas a pesado.
Limpeza de Contribuidor pesado: um plug-in que remove os arquivos ou diretórios.
Assistente de Contribuidor de jshint: um plug-in que analisa a qualidade do código JavaScript.
Assistente de Contribuidor de concat: um plug-in que une os arquivos em um único arquivo.
uglify pesado-Contribuidor: um plug-in que minimiza o JavaScript para reduzir o tamanho.
Observação de Contribuidor pesado: um plug-in que observa a atividade de arquivos.
Preparando o aplicativo
Para começar, configure um novo aplicativo web vazio e adicionar arquivos de exemplo de TypeScript. Arquivos
typeScript são compilados automaticamente para JavaScript usando as configurações do Visual Studio e serão
nosso matérias-primas para processar usando o assistente.
1. No Visual Studio, crie um novo ASP.NET Web Application .
2. No novo projeto ASP.NET caixa de diálogo, selecione o ASP.NET Core vazio modelo e clique no botão
Okey.
3. No Gerenciador de soluções, revise a estrutura do projeto. O \src pasta inclui vazio wwwroot e
Dependencies nós.
4. Adicionar uma nova pasta chamada TypeScript para o diretório do projeto.
5. Antes de adicionar todos os arquivos, certifique-se de que o Visual Studio tem a opção ' Compilar ao
salvar ' para arquivos TypeScript check. Navegue até ferramentas > opções > Editor de texto >
Typescript > Projeto:
6. Clique com botão direito do TypeScript diretório e selecione Adicionar > Novo Item no menu de
contexto. Selecione o arquivo JavaScript item e nomeie o arquivo Tastes.ts (Observe o *extensão. TS ).
Copie a linha de código do TypeScript abaixo no arquivo (quando você salva, um novo Tastes.js arquivo
aparecerá com a origem de JavaScript).
enum Tastes { Sweet, Sour, Salty, Bitter }
7. Adicionar um segundo arquivo para o TypeScript diretório e nomeie-o Food.ts . Copie o código abaixo
para o arquivo.
class Food {
constructor(name: string, calories: number) {
this._name = name;
this._calories = calories;
}
private _name: string;

get Name() {
return this._name;
}
private _calories: number;

get Calories() {
return this._calories;
}
private _taste: Tastes;

get Taste(): Tastes { return this._taste }
set Taste(value: Tastes) {
this._taste = value;
}
}
Configurando NPM
Em seguida, configure NPM para baixar pesado e tarefas do assistente.
1. No Gerenciador de soluções, clique com o botão direito e selecione Adicionar > Novo Item no menu de
contexto. Selecione o arquivo de configuração NPM item, deixe o nome padrão, Package. JSONe clique
no adicionar botão.
2. No Package. JSON arquivo, dentro de devDependencies chaves de objeto, digite "pesado". Selecione
grunt o Intellisense de lista e pressione a tecla Enter. Visual Studio será colocada entre aspas no nome do
pacote pesado e adicionar dois-pontos. À direita dos dois pontos, selecione a versão estável mais recente
do pacote da parte superior da lista do Intellisense (pressione Ctrl-Space se o Intellisense não aparece).
NOTE
Usa NPM controle de versão semântico para organizar as dependências. Controle de versão semântico, também
conhecido como SemVer, identifica os pacotes com o esquema de numeração .. . IntelliSense simplifica o controle de
versão semântico, mostrando apenas algumas opções comuns. O item superior na lista do Intellisense (0.4.5 no
exemplo acima) é considerado a versão estável mais recente do pacote. O símbolo de acento circunflexo (^)
corresponde a mais recente versão principal e o til () co rresp o n de a versão secu n dária mais recen te. Consulte o referência de
analisador NPM semver versão como um guia para a expressividade completa que fornece SemVer.
3. Adicionar mais dependências carregar pesadom-Contribuidor -* pacotes para limpa, jshint, concat, uglifye
inspecionar conforme mostrado no exemplo a seguir. As versões não precisam coincidir com o exemplo.
"grunt": "0.4.5",
"grunt-contrib-clean": "0.6.0",
"grunt-contrib-jshint": "0.11.0",
"grunt-contrib-concat": "0.5.1",
"grunt-contrib-uglify": "0.8.0",
"grunt-contrib-watch": "0.6.1"
}
4. Salve o Package. JSON arquivo.

Baixarão os pacotes para cada item devDependencies, juntamente com todos os arquivos que requer que cada
pacote. Você pode encontrar os arquivos de pacote no node_modules diretório, permitindo que o Mostrar todos
os arquivos botão no Gerenciador de soluções.
NOTE
Se você precisar, você pode restaurar manualmente as dependências no Gerenciador de soluções clicando em
Dependencies\NPM e selecionando o restaurar pacotes opção de menu.
Assistente de configuração
Pesado estiver configurado para usar um manifesto chamado Gruntfile.js que define, carrega e registra as tarefas
que podem ser executadas manualmente ou configuradas para ser executado automaticamente com base em
eventos no Visual Studio.
1. Clique com o botão direito e selecione Adicionar > Novo Item. Selecione o arquivo de configuração
Grunt opção, deixe o nome padrão, Gruntfile.jse clique no adicionar botão.
O código inicial inclui uma definição de módulo e o grunt.initConfig() método. O initConfig() é usado
para definir opções para cada pacote, e o restante do módulo serão carregadas e registrar tarefas.
module.exports = function (grunt) {

grunt.initConfig({
});
};
2. Dentro de initConfig() método, adicionar opções para o clean conforme mostrado no exemplo de
tarefa Gruntfile.js abaixo. A tarefa de limpeza aceita uma matriz de cadeias de caracteres de diretório. Essa
tarefa remove arquivos de wwwroot/lib e o diretório temp/inteiro.
module.exports = function (grunt) {

grunt.initConfig({
clean: ["wwwroot/lib/*", "temp/"],
});
};
3. Abaixo do método initConfig(), adicione uma chamada para grunt.loadNpmTasks() . Isso fará a tarefa
executável do Visual Studio.
grunt.loadNpmTasks("grunt-contrib-clean");
4. Salvar Gruntfile.js. O arquivo deve ser semelhante a captura de tela abaixo.
5. Clique com botão direito Gruntfile.js e selecione Explorador do Executador de tarefas no menu de
contexto. A janela Explorador do Executador de tarefas será aberto.
6. Verifique clean mostra em tarefas no Explorador do Executador de tarefas.
7. A tarefa de limpeza e selecione executar no menu de contexto. Uma janela de comando exibe o progresso
da tarefa.
NOTE
Não existem arquivos ou diretórios para limpar ainda. Se desejar, você pode criá-las manualmente no Gerenciador
de soluções e, em seguida, executar a tarefa de limpeza como um teste.
8. No método initConfig(), adicione uma entrada para concat usando o código abaixo.
O src matriz de propriedade lista arquivos combinar, na ordem em que eles devem ser combinados. O
dest propriedade atribui o caminho para o arquivo combinado que é produzido.
concat: {
all: {
src: ['TypeScript/Tastes.js', 'TypeScript/Food.js'],
dest: 'temp/combined.js'
}
},
NOTE
O all propriedade no código acima é o nome de um destino. Destinos são usados em algumas tarefas pesado
para permitir que vários ambientes de desenvolvimento. Você pode exibir os destinos internos usando o Intellisense
ou atribuir seu próprio.
9. Adicionar o jshint tarefas usando o código abaixo.

O utilitário de qualidade do código jshint é executado em todos os arquivos JavaScript encontrado no
diretório temp.
jshint: {
files: ['temp/*.js'],
options: {
'-W069': false,
}
},
NOTE
A opção "-W069" é um erro gerado pelo jshint quando colchete de JavaScript usa a sintaxe para atribuir uma
propriedade em vez da notação de ponto, ou seja, Tastes["Sweet"] em vez de Tastes.Sweet . A opção desativa
o aviso para permitir que o restante do processo para continuar.
10. Adicionar o uglify tarefas usando o código abaixo.

A tarefa minimiza o combined.js arquivo encontrado no diretório temp e cria o arquivo de resultado no
wwwroot/lib seguindo a convenção de nomenclatura padrão <nome de arquivo>. min.js.
uglify: {
all: {
src: ['temp/combined.js'],
dest: 'wwwroot/lib/combined.min.js'
}
},
11. Sob o grunt.loadNpmTasks() de chamada que carrega a limpeza de Contribuidor pesado, incluem a
mesma chamada para jshint, concat e uglify usando o código abaixo.
grunt.loadNpmTasks('grunt-contrib-jshint');
grunt.loadNpmTasks('grunt-contrib-concat');
grunt.loadNpmTasks('grunt-contrib-uglify');
12. Salvar Gruntfile.js. O arquivo deve ser algo como o exemplo a seguir.
13. Observe que a lista de tarefas do Gerenciador de executor inclui clean , concat , jshint e uglify tarefas.
Execute cada tarefa na ordem e observar os resultados no Gerenciador de soluções. Cada tarefa deve ser
executada sem erros.
A tarefa concat cria um novo combined.js de arquivo e o coloca na pasta temp. A tarefa de jshint
simplesmente executa e não produz saída. A tarefa uglify cria um novo combined.min.js de arquivo e o
coloca na wwwroot/lib. Após a conclusão, a solução deve ser semelhante a captura de tela abaixo:
NOTE
Para obter mais informações sobre as opções para cada pacote, visite https://www.npmjs.com/ e o nome do pacote
na caixa de pesquisa na página principal de pesquisa. Por exemplo, você pode pesquisar o pacote limpeza de
Contribuidor pesado para obter um link de documentação que explica a todos os seus parâmetros.
Todos juntos agora

Use o Assistente de registerTask() método para executar uma série de tarefas em uma determinada sequência.
Por exemplo, para executar o exemplo etapas acima na ordem limpa -> concat -> jshint -> uglify, adicione o
código abaixo para o módulo. O código deve ser adicionado no mesmo nível como as chamadas loadNpmTasks(),
fora initConfig.
grunt.registerTask("all", ['clean', 'concat', 'jshint', 'uglify']);
A nova tarefa aparece no Explorador do Executador de tarefas em tarefas de Alias. Pode-se com o botão direito e
executá-lo como faria com outras tarefas. O all tarefa executará clean , concat , jshint e uglify , em ordem.
Monitorando alterações
Um watch tarefa fica de olho em arquivos e diretórios. O relógio dispara tarefas automaticamente se detectar
alterações. Adicione o código abaixo para initConfig para observar as alterações *no diretório TypeScript. js. Se
um arquivo JavaScript for alterado, watch executará o all tarefa.
watch: {
files: ["TypeScript/*.js"],
tasks: ["all"]
}
Adicionar uma chamada para loadNpmTasks() para mostrar o watch tarefa no Explorador do Executador de
tarefas.
grunt.loadNpmTasks('grunt-contrib-watch');
Clique na tarefa de inspeção no Explorador do Executador de tarefas e selecione Executar no menu de contexto. A
janela de comando que mostra a execução de tarefa watch exibirá um "Aguardando..." . Abra um dos arquivos
TypeScript, adicione um espaço e, em seguida, salve o arquivo. Isso disparar a tarefa de inspeção e disparar
outras tarefas executadas em ordem. Captura de tela abaixo mostra uma exemplo de execução.
Associação a eventos do Visual Studio

A menos que você deseja iniciar manualmente as tarefas toda vez que você trabalha no Visual Studio, você pode
associar tarefas a serem antes de criar, depois de criar, limpar, e Projeto aberto eventos.
Vamos associar watch para que ele seja executado sempre que o Visual Studio abrirá. No Explorador do
Executador de tarefas, a tarefa de inspeção e selecione associações > Abrir projeto no menu de contexto.
Descarregar e recarregar o projeto. Quando o projeto é carregado novamente, a tarefa de inspeção iniciará a
execução automaticamente.
Resumo
Pesado é um executor de tarefa avançada que pode ser usado para automatizar a maioria das tarefas de
compilação do cliente. Pesado aproveita NPM para fornecer seus pacotes e recursos de ferramentas de
integração com o Visual Studio. Explorador do Executador de tarefas do Visual Studio detecta alterações nos
arquivos de configuração e fornece uma interface conveniente para executar tarefas, exibir tarefas em execução e
associar tarefas a eventos do Visual Studio.
Recursos adicionais
Usar o Gulp
Aquisição de biblioteca do lado do cliente no
ASP.NET Core com LibMan
Por Scott Addie

O Gerenciador de Bibliotecas (LibMan) é uma ferramenta leve de aquisição de bibliotecas do lado do cliente. O
LibMan baixa bibliotecas e estruturas populares do sistema de arquivos ou de uma CDN (rede de distribuição de
conteúdo). As CDNs compatíveis incluem CDNJS e unpkg. Os arquivos de biblioteca selecionados são buscados e
colocados no local adequado dentro do projeto do ASP.NET Core.
Casos de uso do LibMan

O LibMan oferece os seguintes benefícios:
Somente os arquivos de biblioteca necessários são baixados.
Ferramentas adicionais, tais como Node.js, npm e WebPack, não são necessárias para adquirir um subconjunto
de arquivos em uma biblioteca.
Arquivos podem ser colocados em um local específico sem recorrer a tarefas de build ou à cópia manual de
arquivos.
Para obter mais informações sobre os benefícios do LibMan, assista a Modern front-end web development in
Visual Studio 2017: LibMan segment (Desenvolvimento de front-end da Web moderno no Visual Studio 2017:
segmento LibMan).
O LibMan não é um sistema de gerenciamento de pacotes. Se você já está usando um gerenciador de pacotes,
assim como o npm ou yarn, continue fazendo isso. O LibMan não foi desenvolvido para substituir essas
ferramentas.
Recursos adicionais
LibMan de uso com o ASP.NET Core no Visual Studio
Use a interface de linha de comando LibMan (CLI) com o ASP.NET Core
Repositório do GitHub do LibMan
Use a interface de linha de comando LibMan (CLI)
com o ASP.NET Core
Por Scott Addie

O LibMan CLI é uma ferramenta de plataforma cruzada que tem suporte em qualquer lugar, há suporte para .NET
Core.
Pré-requisitos
Instalação
Para instalar a CLI LibMan:
dotnet tool install -g Microsoft.Web.LibraryManager.Cli
Um ferramenta Global do .NET Core for instalado a partir de Microsoft.Web.LibraryManager.Cli pacote do

NuGet.
Para instalar a CLI LibMan de uma fonte específica de pacote do NuGet:
dotnet tool install -g Microsoft.Web.LibraryManager.Cli --version 1.0.94-g606058a278 --add-source C:\Temp\
No exemplo anterior, uma ferramenta Global do .NET Core é instalada do computador Windows local
C:\Temp\Microsoft.Web.LibraryManager.Cli.1.0.94 -g606058a278.nupkg arquivo.
Uso
Após a instalação bem-sucedida da CLI, o comando a seguir pode ser usado:
libman
Para exibir a versão da CLI instalada:
libman --version
Para exibir os comandos da CLI disponíveis:
libman --help
O comando anterior exibe uma saída semelhante à seguinte:

1.0.163+g45474d37ed
Usage: libman [options] [command]
Options:
--help|-h Show help information
--version Show version information
Commands:
cache List or clean libman cache contents
clean Deletes all library files defined in libman.json from the project
init Create a new libman.json
install Add a library definition to the libman.json file, and download the
library to the specified location
restore Downloads all files from provider and saves them to specified
destination
uninstall Deletes all files for the specified library from their specified
destination, then removes the specified library definition from
libman.json
update Updates the specified library
Use "libman [command] --help" for more information about a command.
As seções a seguir descrevem os comandos da CLI disponíveis.
Inicializar LibMan no projeto

O libman init comando cria um libman.json arquivo se ele não existir. O arquivo é criado com o conteúdo do
modelo de item padrão.
Sinopse
libman init [-d|--default-destination] [-p|--default-provider] [--verbosity]

libman init [-h|--help]
Opções
As seguintes opções estão disponíveis para o libman init comando:
-d|--default-destination <PATH>
Um caminho relativo à pasta atual. Arquivos de biblioteca são instalados nesse local, se nenhum
destination propriedade está definida para uma biblioteca no libman.json. O <PATH> valor é gravado para
o defaultDestination propriedade de libman.json.
-p|--default-provider <PROVIDER>
O provedor a ser usado se nenhum provedor é definido para uma determinada biblioteca. O <PROVIDER>
valor é gravado para o defaultProvider propriedade de libman.json. Substitua <PROVIDER> com um dos
seguintes valores:
cdnjs
filesystem
unpkg
-h|--help
Mostre informações de Ajuda.

--verbosity <LEVEL>
Defina o detalhamento da saída. Substitua <LEVEL> com um dos seguintes valores:
quiet
normal
detailed
Exemplos
Para criar uma libman.json arquivo em um projeto ASP.NET Core:
Navegue até a raiz do projeto.
libman init
Digite o nome do provedor padrão, ou pressione Enter para usar o provedor do CDNJS padrão. Os
valores válidos incluem:
cdnjs
filesystem
unpkg
Um libman.json arquivo é adicionado à raiz do projeto com o seguinte conteúdo:
{
"version": "1.0",
"defaultProvider": "cdnjs",
"libraries": []
}
Adicione arquivos de biblioteca

O libman install comando baixa e instala os arquivos de biblioteca no projeto. Um libman.json arquivo for
adicionado, se ele existir. O libman.json arquivo é modificado para armazenar detalhes de configuração para os
arquivos de biblioteca.
Sinopse
libman install <LIBRARY> [-d|--destination] [--files] [-p|--provider] [--verbosity]

libman install [-h|--help]
Arguments
LIBRARY
O nome da biblioteca para instalar. Esse nome pode incluir a notação de número de versão (por exemplo, @1.2.0
).
Opções
As seguintes opções estão disponíveis para o libman install comando:
-d|--destination <PATH>
O local para instalar a biblioteca. Se não for especificado, o local padrão é usado. Se nenhum
defaultDestination propriedade é especificada em libman.json, essa opção é necessária.
--files <FILE>
Especifique o nome do arquivo para instalá-lo da biblioteca. Se não for especificado, todos os arquivos da
biblioteca são instalados. Forneça um --files opção por arquivo para ser instalado. Caminhos relativos
são suportados também. Por exemplo: --files dist/browser/signalr.js .
-p|--provider <PROVIDER>
O nome do provedor a ser usado para a aquisição de biblioteca. Substitua <PROVIDER> com um dos
seguintes valores:
cdnjs
filesystem
unpkg
Se não for especificado, o defaultProvider propriedade na libman.json é usado. Se nenhum
defaultProvider propriedade é especificada em libman.json, essa opção é necessária.
-h|--help

--verbosity <LEVEL>

quiet
normal
detailed
Exemplos
Considere o seguinte libman.json arquivo:
{
"version": "1.0",
"libraries": []
}
Para instalar a versão do jQuery 3.2.1 jQuery do arquivo para o wwwroot/scripts/jquery pasta usando o provedor
do CDNJS:
libman install jquery@3.2.1 --provider cdnjs --destination wwwroot/scripts/jquery --files jquery.min.js
O libman.json arquivo semelhante ao seguinte:

{
"version": "1.0",
"libraries": [
{
"library": "jquery@3.2.1",
"destination": "wwwroot/scripts/jquery",
"files": [
"jquery.min.js"
]
}
]
}
Para instalar o calendar.js e calendar.css arquivos da c:\temp\contosoCalendar\ usando o sistema de arquivos

provedor:
libman install C:\temp\contosoCalendar\ --provider filesystem --files calendar.js --files calendar.css
O seguinte aviso é exibido por dois motivos:

O libman.json arquivo não contém um defaultDestination propriedade.
O libman install comando não contém o -d|--destination opção.
Depois de aceitar o destino padrão, o libman.json arquivo semelhante ao seguinte:

{
"version": "1.0",
"libraries": [
{
"destination": "wwwroot/scripts/jquery",
"files": [
"jquery.min.js"
]
},
{
"library": "C:\\temp\\contosoCalendar\\",
"provider": "filesystem",
"destination": "wwwroot/lib/contosoCalendar",
"files": [
"calendar.js",
"calendar.css"
]
}
]
}
Restaurar arquivos de biblioteca

O libman restore comando instala arquivos de biblioteca definidos nas libman.json. As seguintes regras se
aplicam:
Se nenhum libman.json arquivo existir na raiz do projeto, um erro será retornado.
Se uma biblioteca Especifica um provedor, o defaultProvider propriedade na libman.json será ignorado.
Se uma biblioteca Especifica um destino, o defaultDestination propriedade na libman.json será ignorado.
Sinopse
libman restore [--verbosity]

libman restore [-h|--help]
Opções
As seguintes opções estão disponíveis para o libman restore comando:
-h|--help

--verbosity <LEVEL>

quiet
normal
detailed
Exemplos
Para restaurar os arquivos de biblioteca definidos em libman.json:
libman restore
Excluir arquivos de biblioteca
O libman clean comando exclui os arquivos de biblioteca restaurados anteriormente por meio de LibMan. Pastas
se tornar vazias depois dessa operação são excluídas. Os arquivos de biblioteca associados configurações na
libraries propriedade de libman.json não são removidos.
Sinopse
libman clean [--verbosity]

libman clean [-h|--help]
Opções
As seguintes opções estão disponíveis para o libman clean comando:
-h|--help

--verbosity <LEVEL>

quiet
normal
detailed
Exemplos
Para excluir arquivos de biblioteca instalados por meio de LibMan:
libman clean
Desinstalar os arquivos de biblioteca

O libman uninstall comando:
Exclui todos os arquivos associados a biblioteca especificada do destino no libman.json.
Remove a configuração de biblioteca associado de libman.json.
Ocorre um erro quando:
Não libman.json arquivo existe na raiz do projeto.
A biblioteca especificada não existe.
Se mais de uma biblioteca com o mesmo nome estiver instalada, solicitado para escolher um.
Sinopse
libman uninstall <LIBRARY> [--verbosity]

libman uninstall [-h|--help]
Arguments
LIBRARY
O nome da biblioteca para desinstalar. Esse nome pode incluir a notação de número de versão (por exemplo,
@1.2.0 ).
Opções
As seguintes opções estão disponíveis para o libman uninstall comando:
-h|--help

--verbosity <LEVEL>

quiet
normal
detailed
Exemplos
Considere o seguinte libman.json arquivo:
{
"version": "1.0",
"libraries": [
{
"files": [
"jquery.min.js",
"jquery.js",
"jquery.min.map"
],
"destination": "wwwroot/lib/jquery/"
},
{
"provider": "unpkg",
"library": "bootstrap@4.1.3",
"destination": "wwwroot/lib/bootstrap/"
},
{
"library": "C:\\temp\\lodash\\",
"files": [
"lodash.js",
"lodash.min.js"
],
"destination": "wwwroot/lib/lodash/"
}
]
}
Para desinstalar o jQuery, qualquer um dos comandos a seguir bem-sucedida:
libman uninstall jquery
libman uninstall jquery@3.3.1
Para desinstalar os arquivos de Lodash instalados por meio de filesystem provedor:
libman uninstall C:\temp\lodash\

Atualizar a versão da biblioteca
O libman update comando atualiza uma biblioteca instalada via LibMan à versão especificada.
Ocorre um erro quando:
Não libman.json arquivo existe na raiz do projeto.
A biblioteca especificada não existe.
Se mais de uma biblioteca com o mesmo nome estiver instalada, solicitado para escolher um.
Sinopse
libman update <LIBRARY> [-pre] [--to] [--verbosity]

libman update [-h|--help]
Arguments
LIBRARY
O nome da biblioteca para atualizar.

Opções
As seguintes opções estão disponíveis para o libman update comando:
-pre
Obter a versão de pré-lançamento mais recente da biblioteca.

--to <VERSION>
Obtenha uma versão específica da biblioteca.

-h|--help

--verbosity <LEVEL>

quiet
normal
detailed
Exemplos
Para atualizar o jQuery para a versão mais recente:
libman update jquery
Para atualizar o jQuery versão 3.3.1:
libman update jquery --to 3.3.1
Para atualizar o jQuery para a versão de pré-lançamento mais recente:
libman update jquery -pre

Gerenciar o cache de biblioteca
O libman cache comando gerencia o cache de biblioteca LibMan. O filesystem provedor não usa o cache de
biblioteca.
Sinopse
libman cache clean [<PROVIDER>] [--verbosity]

libman cache list [--files] [--libraries] [--verbosity]
libman cache [-h|--help]
Arguments
PROVIDER
Usado somente com o clean comando. Especifica para limpar o cache do provedor. Os valores válidos incluem:
cdnjs
filesystem
unpkg
Opções
As seguintes opções estão disponíveis para o libman cache comando:
--files
Liste os nomes de arquivos que são armazenados em cache.

--libraries
Liste os nomes de bibliotecas que são armazenados em cache.

-h|--help

--verbosity <LEVEL>

quiet
normal
detailed
Exemplos
Para exibir os nomes de bibliotecas em cache por um provedor, use um dos seguintes comandos:
libman cache list
libman cache list --libraries
Uma saída semelhante à apresentada a seguir será exibida:

Cache contents:
---------------
unpkg:
knockout
react
vue
cdnjs:
font-awesome
jquery
knockout
lodash.js
react
Para exibir os nomes dos arquivos de biblioteca em cache por provedor:
libman cache list --files
Uma saída semelhante à apresentada a seguir será exibida:
Cache contents:
---------------
unpkg:
knockout:
<list omitted for brevity>
react:
vue:
cdnjs:
font-awesome
metadata.json
jquery
metadata.json
3.2.1\core.js
3.2.1\jquery.js
3.2.1\jquery.min.js
3.2.1\jquery.min.map
3.2.1\jquery.slim.js
3.2.1\jquery.slim.min.js
3.2.1\jquery.slim.min.map
3.3.1\core.js
3.3.1\jquery.js
3.3.1\jquery.min.js
3.3.1\jquery.min.map
3.3.1\jquery.slim.js
3.3.1\jquery.slim.min.js
3.3.1\jquery.slim.min.map
knockout
metadata.json
3.4.2\knockout-debug.js
3.4.2\knockout-min.js
lodash.js
metadata.json
4.17.10\lodash.js
4.17.10\lodash.min.js
react
metadata.json
Observe que a saída anterior mostra que o jQuery versões 3.2.1 e 3.3.1 são armazenados em cache no
provedor de CDNJS.
Para esvaziar o cache de biblioteca para o provedor do CDNJS:
libman cache clean cdnjs
Depois de esvaziar o cache do provedor do CDNJS o libman cache list comando exibe o seguinte:
Cache contents:
---------------
unpkg:
knockout
react
vue
cdnjs:
(empty)
Para esvaziar o cache para todos os provedores com suporte:
libman cache clean
Depois de esvaziar todos os caches de provedor, o libman cache list comando exibe o seguinte:
Cache contents:
---------------
unpkg:
(empty)
cdnjs:
(empty)
Recursos adicionais
Instalar uma ferramenta Global
Por Scott Addie

O Visual Studio tem suporte interno para LibMan em projetos do ASP.NET Core, incluindo:
Suporte para configurar e executar operações de restauração LibMan no build.
Itens de menu para o disparo de operações de limpeza e LibMan restauração.
Caixa de diálogo de pesquisa para localizar bibliotecas e adicionar os arquivos a um projeto.
Suporte de edição para libman.json—o arquivo de manifesto LibMan.
Pré-requisitos
Visual Studio 2017 versão 15,8 ou posterior com o ASP.NET e desenvolvimento web carga de trabalho
Adicione arquivos de biblioteca

Arquivos de biblioteca podem ser adicionados a um projeto ASP.NET Core de duas maneiras diferentes:
1. Use a caixa de diálogo Adicionar biblioteca de cliente
2. Configurar manualmente as entradas do arquivo de manifesto LibMan
Use a caixa de diálogo Adicionar biblioteca de cliente
Siga estas etapas para instalar uma biblioteca de cliente:
Na Gerenciador de soluções, clique na pasta de projeto no qual os arquivos devem ser adicionados.
Escolher adicione > biblioteca de cliente. O adicionar a biblioteca do lado do cliente caixa de
diálogo aparece:
Selecione o provedor de biblioteca do provedor lista suspensa. CDNJS é o provedor padrão.

Digite o nome da biblioteca para buscar na biblioteca caixa de texto. IntelliSense fornece uma lista de
bibliotecas, começando com o texto fornecido.
Selecione a biblioteca da lista do IntelliSense. Observe que o nome da biblioteca é sufixado com o @
símbolo e a versão estável mais recente conhecido para o provedor selecionado.
Decida quais arquivos a serem incluídos:
Selecione o incluir todos os arquivos de biblioteca botão de opção para incluir todos os arquivos da
biblioteca.
Selecione o escolher arquivos específicos botão de opção para incluir um subconjunto dos arquivos
da biblioteca. Quando o botão de opção é selecionado, a árvore do seletor de arquivos está habilitada.
Marque as caixas à esquerda dos nomes de arquivo para baixar.
Especifique a pasta de projeto para armazenar os arquivos a local de destino caixa de texto. Como uma
recomendação, armazene cada biblioteca em uma pasta separada.
Sugeridas local de destino pasta baseia-se no local a partir do qual a caixa de diálogo iniciado:
Se iniciado a partir da raiz do projeto:
wwwroot/lib será usado se wwwroot existe.
lib será usado se wwwroot não existe.
Se iniciado em uma pasta de projeto, o nome da pasta correspondente será usado.
A sugestão de pasta é sufixada com o nome da biblioteca. A tabela a seguir ilustra as sugestões de pasta
durante a instalação do jQuery em um projeto de páginas do Razor.
INICIE O LOCAL PASTA SUGERIDA
raiz do projeto (se wwwroot existe) wwwroot/lib/jquery /
raiz do projeto (se wwwroot não existe) jquery/lib /
Páginas pasta do projeto Páginas/jquery /
Clique o instale botão para baixar os arquivos, de acordo com a configuração no libman.json.
Examine a Gerenciador de biblioteca feed da saída janela para obter detalhes de instalação. Por
exemplo:
Restore operation started...

Restoring libraries for project LibManSample
Restoring library jquery@3.3.1... (LibManSample)
wwwroot/lib/jquery/jquery.min.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.min.map written to destination (LibManSample)
Restore operation completed
1 libraries restored in 2.32 seconds
Configurar manualmente as entradas do arquivo de manifesto LibMan

Todas as operações de LibMan no Visual Studio são baseadas no conteúdo do manifesto de LibMan da raiz do
projeto (libman.json). Você pode editar manualmente libman.json para configurar arquivos de biblioteca do
projeto. O Visual Studio restaura todos os arquivos de biblioteca uma vez libman.json é salvo.
Para abrir libman.json para edição, existem as seguintes opções:
Clique duas vezes o libman.json arquivo no Gerenciador de soluções.
Clique com botão direito no projeto no Gerenciador de soluções e selecione gerenciar bibliotecas de
cliente. †
Selecione gerenciar bibliotecas do lado do cliente do Visual Studio projeto menu. †
† Se o libman.json arquivo ainda não existir na raiz do projeto, ele será criado com o conteúdo do modelo de item
padrão.
Visual Studio oferece um rico JSON, suporte, como colorização de edição, formatação, IntelliSense e validação de
esquema. Esquema JSON do manifesto LibMan é encontrada em http://json.schemastore.org/libman .
Com o seguinte arquivo de manifesto, LibMan recupera arquivos de acordo com a configuração definida no
libraries propriedade. Obter uma explicação dos literais de objeto definidos dentro libraries segue:
Um subconjunto de jQuery versão 3.3.1 é recuperado do provedor CDNJS. O subconjunto é definido na

files propriedade—jQuery, obtive, e jquery.min.map. Os arquivos são colocados no projeto do
wwwroot/lib/jquery pasta.
Na íntegra Bootstrap versão 4.1.3 é recuperado e colocado em um wwwroot/lib/bootstrap pasta. O literal de
objeto provider substituições de propriedades de defaultProvider valor da propriedade. LibMan recupera os
arquivos de inicialização do provedor de unpkg.
Um subconjunto de Lodash foi aprovada por um corpo regulador dentro da organização. O lodash.js e
lodash.min.js arquivos são recuperados do sistema de arquivos local no c:\temp\lodash\. Os arquivos são
copiados para o projeto wwwroot/lib/lodash pasta.
{
"version": "1.0",
"libraries": [
{
"files": [
"jquery.min.js",
"jquery.js",
"jquery.min.map"
],
"destination": "wwwroot/lib/jquery/"
},
{
"provider": "unpkg",
"library": "bootstrap@4.1.3",
"destination": "wwwroot/lib/bootstrap/"
},
{
"library": "C:\\temp\\lodash\\",
"files": [
"lodash.js",
"lodash.min.js"
],
"destination": "wwwroot/lib/lodash/"
}
]
}
NOTE
LibMan só dá suporte a uma versão de cada biblioteca de cada provedor. O libman.json arquivo Falha na validação de
esquema, se ele contiver duas bibliotecas com o mesmo nome de biblioteca para determinado provedor.
Restaurar arquivos de biblioteca

Para restaurar os arquivos de biblioteca de dentro do Visual Studio, deve haver um válido libman.json arquivo na
raiz do projeto. Arquivos restaurados são colocados no projeto no local especificado para cada biblioteca.
Arquivos de biblioteca podem ser restaurados em um projeto do ASP.NET Core de duas maneiras:
1. Restaurar os arquivos durante a compilação
2. Restaurar os arquivos manualmente
Restaurar os arquivos durante a compilação
LibMan pode restaurar os arquivos de biblioteca definidas como parte do processo de compilação. Por padrão, o
restauração no build comportamento está desabilitado.
Para ativar e testar o comportamento de restauração no build:
Clique com botão direito libman.json na Gerenciador de soluções e selecione habilitar bibliotecas de
cliente restaurar no Build no menu de contexto.
Clique o Sim botão quando for solicitado a instalar um pacote do NuGet. O
Microsoft.Web.LibraryManager.Build pacote do NuGet é adicionado ao projeto:
<PackageReference Include="Microsoft.Web.LibraryManager.Build" Version="1.0.113" />
Compile o projeto para confirmar a restauração de arquivo LibMan ocorre. O

Microsoft.Web.LibraryManager.Build pacote injeta um destino do MSBuild que executa LibMan durante a
operação de compilação do projeto.
Examine a compilar feed da saída janela para um log de atividades LibMan:
1>------ Build started: Project: LibManSample, Configuration: Debug Any CPU ------
1>
1>Restore operation started...
1>Restoring library jquery@3.3.1...
1>Restoring library bootstrap@4.1.3...
1>
1>2 libraries restored in 10.66 seconds
1>LibManSample -> C:\LibManSample\bin\Debug\netcoreapp2.1\LibManSample.dll
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
Quando o comportamento de restauração no build está habilitado, o libman.json menu de contexto exibe um
desabilitar bibliotecas de cliente restaurar no Build opção. Esta opção remove o
Microsoft.Web.LibraryManager.Build referência do arquivo de projeto de pacote. Consequentemente, as bibliotecas
do lado do cliente não são restauradas em cada compilação.
Independentemente da configuração de restauração no build, você pode restaurar manualmente a qualquer
momento do libman.json menu de contexto. Para obter mais informações, consulte restaurar os arquivos
manualmente.
Restaurar os arquivos manualmente
Para restaurar manualmente os arquivos de biblioteca:
Para todos os projetos na solução:
Clique com botão direito no nome da solução no Gerenciador de soluções.
Selecione o bibliotecas de cliente restaurar opção.
Para um projeto específico:
Clique com botão direito do libman.json arquivo no Gerenciador de soluções.
Selecione o bibliotecas de cliente restaurar opção.
Enquanto a operação de restauração está em execução:
O ícone do Centro de Status da tarefa (TSC ) na barra de status do Visual Studio será animado e lerá
iniciada a operação de restauração. Clicando no ícone abre uma dica de ferramenta listando as tarefas em
segundo plano conhecidos.
As mensagens serão enviadas à barra de status e o Gerenciador de biblioteca feed da saída janela. Por
exemplo:
Restore operation started...

Restoring libraries for project LibManSample
Restoring library jquery@3.3.1... (LibManSample)
wwwroot/lib/jquery/jquery.min.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.min.map written to destination (LibManSample)
Restore operation completed
1 libraries restored in 2.32 seconds
Excluir arquivos de biblioteca

Para executar o limpa operação, que exclui os arquivos de biblioteca restaurados anteriormente no Visual Studio:
Clique com botão direito do libman.json arquivo no Gerenciador de soluções.
Selecione o bibliotecas de cliente limpa opção.
Para evitar a remoção não intencional de arquivos não seja de biblioteca, a operação de limpeza não exclui
diretórios inteiros. Ela remove somente os arquivos que foram incluídos na restauração anterior.
Enquanto a operação de limpeza é executado:
O ícone TSC na barra de status do Visual Studio será animado e lerá operação de bibliotecas de cliente
iniciada. Clicando no ícone abre uma dica de ferramenta listando as tarefas em segundo plano conhecidos.
As mensagens são enviadas para a barra de status e o Gerenciador de biblioteca feed da saída janela. Por
exemplo:
Clean libraries operation started...

Clean libraries operation completed
2 libraries were successfully deleted in 1.91 secs
A operação de limpeza exclui somente os arquivos do projeto. Arquivos de biblioteca permanecem no cache para
uma recuperação mais rápida em operações de restauração futuras. Para gerenciar arquivos de biblioteca
armazenados no cache do computador local, use o LibMan CLI.
Desinstalar os arquivos de biblioteca

Para desinstalar os arquivos de biblioteca:
Abra libman.json.
Posicione o cursor dentro correspondente libraries literal de objeto.
Clique no ícone de lâmpada que aparece na margem esquerda e selecione Uninstall
<nome_da_biblioteca > @<library_version >:
Como alternativa, você pode editar e salvar o manifesto LibMan manualmente (libman.json). O operação de
restauração é executado quando o arquivo é salvo. Arquivos de biblioteca que não estão definidos na libman.json
são removidas do projeto.
Atualizar a versão da biblioteca

Para verificar se há uma versão atualizada de biblioteca:
Abra libman.json.
Posicione o cursor dentro correspondente libraries literal de objeto.
Clique no ícone de lâmpada que aparece na margem esquerda. Passe o mouse sobre verificar se há
atualizações.
LibMan verifica se há uma versão mais recente do que a versão instalada da biblioteca. Podem ocorrer os
seguintes resultados:
Um nenhuma atualização encontrada mensagem será exibida se a versão mais recente já está instalada.
A versão estável mais recente é exibida se não estiver instalada.
Se houver uma versão de pré-lançamento mais recente do que a versão instalada, a versão de pré-
lançamento é exibida.
Para fazer o downgrade para uma versão mais antiga da biblioteca, edite manualmente o libman.json arquivo.
Quando o arquivo é salvo, o LibMan operação de restauração:
Remove arquivos redundantes da versão anterior.
Adiciona arquivos novos e atualizados da nova versão.
Recursos adicionais
Use a interface de linha de comando LibMan (CLI) com o ASP.NET Core
Gerenciar pacotes do lado do cliente com Bower no
ASP.NET Core
Por Rick Anderson, Noel arroz, e Scott Addie
IMPORTANT
Enquanto o Bower é mantido, seus mantenedores recomendam usando uma solução diferente. Gerenciador de biblioteca
(LibMan de forma abreviada) é a ferramenta de aquisição de biblioteca do lado do cliente novo do Visual Studio (Visual
Studio 15,8 ou posterior). Para obter mais informações, consulte Aquisição de biblioteca do lado do cliente no ASP.NET Core
com LibMan. Bower tem suporte no Visual Studio versão 15.5.
Yarn com Webpack é uma alternativa popular para a qual instruções de migração estão disponíveis.
Bower chama a próprio "Um Gerenciador de pacotes para a web". Dentro do ecossistema do .NET, ele preenche
essa lacuna deixado pela incapacidade do NuGet para entregar os arquivos de conteúdo estático. Para projetos do
ASP.NET Core, esses arquivos estáticos são inerentes às bibliotecas do lado do cliente, como jQuery e Bootstrap.
Para bibliotecas do .NET, você usar NuGet Gerenciador de pacotes.
Processo de compilação de novos projetos criados com os modelos de projeto do ASP.NET Core configurar lado
do cliente. jQuery e Bootstrap estiverem instalados, e Bower é suportado.
Pacotes do lado do cliente são listados na bower. JSON arquivo. Os modelos de projeto do ASP.NET Core
configura bower. JSON com o jQuery, validação do jQuery e Bootstrap.
Neste tutorial, vamos adicionar suporte para Font Awesome. Pacotes do bower podem ser instalados com o
gerenciar pacotes do Bower interface do usuário ou manualmente na bower. JSON arquivo.
Instalação por meio de pacotes do Bower gerenciar da interface do usuário
Criar um novo aplicativo Web do ASP.NET Core com o aplicativo Web do ASP.NET Core (.NET Core)
modelo. Selecione aplicativo Web e nenhuma autenticação.
Clique com botão direito no projeto no Gerenciador de soluções e selecione gerenciar pacotes do Bower
(como alternativa, no menu principal, Project > gerenciar pacotes Bower).
No Bower: <nome do projeto> janela, clique na guia "Procurar" e, em seguida, filtre a lista de pacotes
inserindo font-awesome na caixa de pesquisa:
Confirme se o "Salvar alterações bower. JSON" caixa de seleção é marcada. Selecione uma versão na lista
suspensa e clique no instalar botão. O saída janela mostra os detalhes da instalação.
Instalação manual no bower. JSON
Abra o bower. JSON arquivo e adicione "font-incrível" para as dependências. O IntelliSense mostra os pacotes
disponíveis. Quando um pacote é selecionado, as versões disponíveis são exibidas. As imagens abaixo são mais
antigas e não corresponder ao que você vê.
Usos para bower controle de versão semântico para organizar as dependências. Controle de versão semântico,
também conhecido como SemVer, identifica os pacotes com o esquema de numeração <principal >.< secundária
>. <patch >. IntelliSense simplifica o controle de versão semântico, mostrando apenas algumas opções comuns. O
item superior na lista do IntelliSense (4.6.3 no exemplo acima) é considerado a versão estável mais recente do
pacote. O símbolo de acento circunflexo (^) corresponde à versão principal mais recente e o til () corresponde a versão
secundária mais recente.
Salvar a bower. JSON arquivo. Visual Studio inspeciona as bower. JSON arquivo para que as alterações. Ao salvar,
o bower install comando é executado. Consulte a janela de saída npm/Bower modo de exibição para o comando
executado.
Abra o . bowerrc do arquivo sob bower. JSON. O directory estiver definida como wwwroot/lib que indica o local
do Bower instalará os ativos do pacote.
{
"directory": "wwwroot/lib"
}
Você pode usar a caixa de pesquisa no Gerenciador de soluções para localizar e exibir o pacote font awesome.
Abra o Views\Shared_layout. cshtml arquivo e adicione o arquivo CSS font awesome no ambiente auxiliar de
marca para Development . No Gerenciador de soluções, arraste e solte fonte awesome.css dentro de
<environment names="Development"> elemento.
<link href="~/lib/font-awesome/css/font-awesome.css" rel="stylesheet" />
</environment>
Um aplicativo de produção, você adicionaria fonte awesome.min.css para o auxiliar de marca de ambiente para
Staging,Production .
Substitua o conteúdo do Views\Home\About.cshtml arquivo Razor com a seguinte marcação:
@{
}
<div class="list-group">
<a class="list-group-item" href="#"><i class="fa fa-home fa-fw" aria-hidden="true"></i> Home</a>
<a class="list-group-item" href="#"><i class="fa fa-book fa-fw" aria-hidden="true"></i> Library</a>
<a class="list-group-item" href="#"><i class="fa fa-pencil fa-fw" aria-hidden="true"></i>
Applications</a>
<a class="list-group-item" href="#"><i class="fa fa-cog fa-fw" aria-hidden="true"></i> Settings</a>
</div>
Execute o aplicativo e navegue até a exibição About sobre para verificar se o pacote font awesome funciona.
Explorando o processo de compilação do lado do cliente

A maioria dos modelos de projeto do ASP.NET Core já estão configurados para usar o Bower. Este passo a passo
de próximo começa com um projeto vazio do ASP.NET Core e adiciona cada parte manualmente, portanto, você
pode ter uma ideia de como o Bower é usado em um projeto. Você pode ver o que acontece com a estrutura do
projeto e o tempo de execução de saída que cada alteração de configuração é feita.
As etapas gerais para usar o processo de compilação do lado do cliente com o Bower são:
Defina pacotes usados em seu projeto.
Pacotes de referência de suas páginas da web.
Definir pacotes
Depois que você listar pacotes na bower. JSON arquivo, o Visual Studio irá baixá-los. O exemplo a seguir usa o
Bower para carregar o jQuery e Bootstrap para o wwwroot pasta.
Criar um novo aplicativo Web do ASP.NET Core com o aplicativo Web do ASP.NET Core (.NET Core)
modelo. Selecione o vazio modelo de projeto e clique em Okey.
No Gerenciador de soluções, clique com botão direito no projeto > Adicionar Novo Item e selecione
arquivo de configuração Bower. Observação: Um . bowerrc arquivo também é adicionado.
Abra bower. JSONe adicionar o jquery e bootstrap para o dependencies seção. Resultante bower. JSON
arquivo se parecerá com o exemplo a seguir. As versões serão alterado ao longo do tempo e podem não
corresponder a imagem a seguir.
{
"name": "asp.net",
"private": true,
"dependencies": {
"jquery": "3.1.1",
"bootstrap": "3.3.7"
}
}
Salvar a bower. JSON arquivo.

Verifique se o projeto inclui o bootstrap e jQuery diretórios wwwroot/lib. Bower usa o . bowerrc arquivo
para instalar os ativos na wwwroot/lib.
Observação: A interface do usuário "Gerenciar pacotes do Bower" fornece uma alternativa à edição do
arquivo manual.
Habilitar arquivos estáticos
Adicionar o Microsoft.AspNetCore.StaticFiles pacote NuGet ao projeto.
Habilitar arquivos estáticos a serem atendidos com o middleware de arquivo estático. Adicione uma chamada
para UseStaticFiles para o Configure método Startup .

{
{

{
});
}
}
Pacotes de referência
Nesta seção, você criará uma página HTML para verificar se que ele pode acessar os pacotes implantados.
Adicionar uma nova página HTML chamada index. HTML para o wwwroot pasta. Observação: Você deve
adicionar o arquivo HTML para o wwwroot pasta. Por padrão, o conteúdo estático não pode ser servido
fora wwwroot. Ver arquivos estáticos para obter mais informações.
Substitua o conteúdo do index. HTML com a seguinte marcação:
<!DOCTYPE html>
<html>
<head>
<title>Bower Example</title>
<link href="lib/bootstrap/dist/css/bootstrap.css" rel="stylesheet" />
</head>
<body>
<h1>Using the jumbotron style</h1>
<p>
<a class="btn btn-primary btn-lg" role="button">Stateful button</a>
</p>
</div>
<script src="lib/jquery/dist/jquery.js"></script>
<script src="lib/bootstrap/dist/js/bootstrap.js"></script>
<script>
$(".btn").click(function () {
$(this).text('loading')
.delay(1000)
.queue(function () {
$(this).text('reset');
$(this).dequeue();
});
});
</script>
</body>
</html>
Execute o aplicativo e navegue até http://localhost:<port>/Index.html . Como alternativa, com index. HTML
aberto, pressione Ctrl+Shift+W . Verifique se que o estilo de jumbotron é aplicado, o código jQuery
responde quando o botão é clicado e que o Bootstrap botão muda de estado.
Less, Sass e fonte Awesome no ASP.NET Core
Por Steve Smith

Os usuários de aplicativos da web têm expectativas cada vez mais altas quando se trata de estilo e a experiência
geral. Aplicativos web modernos frequentemente aproveitam avançadas ferramentas e estruturas para definir e
gerenciar sua aparência de uma maneira consistente. Estruturas como inicialização pode ir um longo caminho para
definir um conjunto comum de opções de layout para sites da web e estilos. No entanto, a maioria dos sites não
trivial também se beneficiar de ser capaz de definir e manter estilos e arquivos de folhas de estilo em cascata com
eficiência, bem como acesso fácil a imagem não ícones que ajudam a tornar a interface do site mais intuitiva. É
onde linguagens e ferramentas que dão suporte a menos e Sass, e bibliotecas, como fonte Awesome, entrar.
Idiomas de pré-processador de CSS

Idiomas que são compilados em outros idiomas, para melhorar a experiência de trabalhar com o idioma base são
chamados de pré-processador. Há dois pré-processadores populares de CSS: menor e Sass. Esses pré-
processadores adicionar recursos a CSS, como suporte para variáveis e regras aninhadas que melhorar a
facilidade de manutenção de folhas de estilo grandes e complexas. CSS como uma linguagem é muito básica, sem
suporte a até mesmo algo simples, como variáveis e isso tende a fazer arquivos CSS repetitivas e inchada.
Adicionando recursos de idioma real de programação via pré-processadores pode ajudar a reduzir a duplicação e
fornecer melhor organização de regras de estilo. Visual Studio fornece suporte interno para ambos os menor e
Sass, bem como as extensões que podem melhorar ainda mais a experiência de desenvolvimento ao trabalhar com
esses idiomas.
Como um exemplo rápido de como pré-processadores podem melhorar a leitura e a manutenção de informações
de estilo, considere este CSS:
.header {
color: black;
font-weight: bold;
font-size: 18px;
font-family: Helvetica, Arial, sans-serif;
}
.small-header {
color: black;
font-weight: bold;
font-size: 14px;
}
Usando Less, isso pode ser reescrito para eliminar a duplicação, usando um mixin (chamada assim porque ele
permite que você "misture" propriedades de uma classe ou conjunto de regras em outra):
.header {
color: black;
font-weight: bold;
font-size: 18px;
}
.small-header {
.header;
font-size: 14px;
}
Less
O pré-processador CSS less é executado usando o Node. js. Para instalar less, use o Gerenciador de pacotes de nó
(npm) em um prompt de comando (-g significa "global"):
npm install -g less
Se você estiver usando o Visual Studio, você pode começar com less adicionando um ou mais arquivos less ao seu
projeto e, em seguida, configurando Gulp (ou Grunt) para processá-los em tempo de compilação. Adicione uma
pasta estilos ao seu projeto e, em seguida, adicione um novo arquivo less chamado main.less nesta pasta.
Depois de adicionado, a estrutura de pastas deve ser algo assim:

Agora você pode adicionar alguns estilos básicos para o arquivo, que será compilado em CSS e implantado na
pasta wwwroot por vez.
Modificar main.less para incluir o conteúdo a seguir, que cria uma paleta de cores simples de uma única cor base.
@base: #663333;
@background: spin(@base, 180);
@lighter: lighten(spin(@base, 5), 10%);
@lighter2: lighten(spin(@base, 10), 20%);
@darker: darken(spin(@base, -5), 10%);
@darker2: darken(spin(@base, -10), 20%);
body {
background-color:@background;
}
.baseColor {color:@base}
.bgLight {color:@lighter}
.bgLight2 {color:@lighter2}
.bgDark {color:@darker}
.bgDark2 {color:@darker2}
@base e o outro @-prefixed itens são variáveis. Cada um deles representa uma cor. Exceto para @base , eles são
definidos usando funções de cor: mais claro, mais escuro e rotação. Mais claro e escureça fazer muito bem o que
você esperaria; rotação ajusta o matiz da cor por um número de graus (ao redor do círculo de cores). O
processador de menos é inteligente ignore variáveis que não são usados, por isso, para demonstrar como
funcionam essas variáveis, precisamos usá-los em algum lugar. As classes .baseColor , etc. demonstrará os valores
calculados de cada uma das variáveis no arquivo CSS que é produzida.
Introdução
Criar um arquivo de configuração npm (Package. JSON ) na pasta do projeto e editá-lo para fazer referência a
gulp e gulp-less :
{
"version": "1.0.0",
"name": "asp.net",
"private": true,
"gulp": "3.9.1",
"gulp-less": "3.3.0"
}
}
Instalar as dependências em um prompt de comando na pasta do projeto ou no Visual Studio Solution Explorer
(dependências > npm > restaurar os pacotes).
npm install
Na pasta do projeto, criar um Gulp arquivo de configuração (gulpfile.js) para definir o processo automatizado.
Adicione uma variável na parte superior do arquivo para representar less e uma tarefa para execução less:

fs = require("fs"),
less = require("gulp-less");
gulp.task("less", function () {
return gulp.src('Styles/main.less')
.pipe(less())
.pipe(gulp.dest('wwwroot/css'));
});
Abra o Explorador do Executador de tarefas (exibição > outras janelas > Explorador do Executador de
tarefas). Entre as tarefas, você verá uma nova tarefa denominada less . Você talvez precise atualizar a janela.
Execute o less tarefa e você verá uma saída semelhante ao que é mostrado aqui:
O wwwroot/css pasta agora contém um novo arquivo, Main:

Abra Main e você verá algo parecido com o seguinte:
body {
}
.baseColor {
color: #663333;
}
.bgLight {
color: #884a44;
}
.bgLight2 {
color: #aa6355;
}
.bgDark {
color: #442225;
}
.bgDark2 {
color: #221114;
}
Adicionar uma página HTML simples para o wwwroot pasta e referência Main para ver a paleta de cores em ação.
<!DOCTYPE html>
<html>
<head>
<link href="css/main.css" rel="stylesheet" />
<title></title>
</head>
<body>
<div>
<div class="baseColor">BaseColor</div>
<div class="bgLight">Light</div>
<div class="bgLight2">Light2</div>
<div class="bgDark">Dark</div>
<div class="bgDark2">Dark2</div>
</div>
</body>
</html>
Você pode ver que o grau de 180 girar na @base usada para produzir @background resultou no disco de cores
opostas cor de @base :
Less também oferece suporte para regras aninhadas, bem como as consultas de mídia aninhada. Por exemplo,
definindo hierarquias aninhadas como menus podem resultar em regras de CSS detalhadas como estes:
nav {
height: 40px;
width: 100%;
}
nav li {
height: 38px;
width: 100px;
}
nav li a:link {
color: #000;
text-decoration: none;
}
nav li a:visited {
text-decoration: none;
color: #CC3333;
}
nav li a:hover {
text-decoration: underline;
font-weight: bold;
}
nav li a:active {
text-decoration: underline;
}
O ideal é todas as regras de estilo relacionados serão colocadas juntos dentro do arquivo CSS, mas na prática, não
há nada impor essa regra exceto convenção e talvez os comentários do bloco.
Definir essas mesmas regras usando less tem esta aparência:
nav {
height: 40px;
width: 100%;
li {
height: 38px;
width: 100px;
a {
color: #000;
&:link { text-decoration:none}
&:visited { color: #CC3333; text-decoration:none}
&:hover { text-decoration:underline; font-weight:bold}
&:active {text-decoration:underline}
}
}
}
Observe que, nesse caso, todos os elementos subordinados do nav estão contidos dentro de seu escopo. Não há
nenhuma repetição dos elementos pai ( nav , li , a ), e a contagem de linha de total caiu também (embora
algumas das é um resultado de colocar valores nas linhas da mesmas no segundo exemplo). Ele pode ser muito
útil, organizacional, para ver todas as regras para um determinado elemento de interface do usuário em um
escopo explicitamente associado, nesse caso definido do restante do arquivo de chaves.
O & sintaxe é um recurso seletor less, com & que representa o pai de seletor atual. Portanto, dentro do {...} bloco,
& representa um a marca e, portanto, &:link é equivalente a a:link .
Consultas de mídia, extremamente úteis na criação de designs de resposta também podem contribuir muito para
repetição e a complexidade em CSS. Less permite que as consultas de mídia a ser aninhada dentro de classes, para
que a definição de classe inteira não precisa ser repetido em diferentes nível superior @media elementos. Por
exemplo, aqui está o CSS para um menu de resposta:
.navigation {
margin-top: 30%;
width: 100%;
}
@media screen and (min-width: 40em) {
.navigation {
margin: 0;
}
}
.navigation {
width: 960px;
margin: 0;
}
}
Isso pode ser melhor definido em less como:
.navigation {
margin-top: 30%;
width: 100%;
margin: 0;
}
width: 960px;
margin: 0;
}
}
Outro recurso de less que já vimos é seu suporte para operações matemáticas, permitindo que os atributos de
estilo a ser construído de variáveis predefinidas. Isso facilita a atualização estilos relacionados muito mais fácil, já
que a variável de base pode ser modificada e todos os valores dependentes alterar automaticamente.
Arquivos CSS, especialmente para grandes sites (e especialmente se as consultas de mídia estão sendo usadas),
tendem a ter muito grandes ao longo do tempo, tornando a trabalhar com elas complicada. Arquivos less podem
ser definidos separadamente, obtidas usando @import diretivas. Less também pode ser usado para importar
arquivos CSS individuais, se desejado.
Mixins pode aceitar parâmetros e less oferece suporte à lógica condicional na forma de protege mesclado, que
fornecem uma maneira declarativa para definir quando determinados mixins entra em vigor. Um uso comum para
protege mesclado ajustar as cores com base em como a luz ou escuro a cor da fonte. Dado um mesclado que
aceita um parâmetro para a cor, um protetor mesclado pode ser usado para modificar o mesclado com base na cor:
.box (@color) when (lightness(@color) >= 50%) {
}
.box (@color) when (lightness(@color) < 50%) {
background-color: #FFF;
}
.box (@color) {
color: @color;
}
.feature {
.box (@base);
}
Considerando nossa atual @base valor #663333 , esse script less produzirá o seguinte CSS:
.feature {
background-color: #FFF;
color: #663333;
}
Less fornece uma série de recursos adicionais, mas isso deve dar uma ideia da energia desse idioma de pré-
processamento.
Sass
Sass é semelhante ao menos, fornecendo suporte para muitos dos mesmos recursos, mas com sintaxe
ligeiramente diferente. Ele é criado usando o Ruby, em vez de JavaScript, e portanto tem requisitos de instalação
diferentes. O idioma Sass original não usa chaves ou ponto e vírgula, mas em vez disso, definida escopo usando o
recuo e espaços em branco. Na versão 3 dos Sass, uma nova sintaxe foi introduzida, SCSS ("Sassy CSS"). SCSS é
semelhante ao CSS que ignora os níveis de recuo e espaços em branco e, em vez disso, usa o ponto e vírgula e
chaves.
Para instalar Sass, normalmente você deve primeiro instalar Ruby (pré-instalado macOS ) e, em seguida, execute:
gem install sass
No entanto, se você estiver executando o Visual Studio, você pode começar com Sass em grande parte da mesma
maneira como você faria com less. Abra Package. JSON e adicionar o pacote "gulp sass" devDependencies :
"gulp": "3.9.1",
"gulp-less": "3.3.0",
"gulp-sass": "3.1.0"
}
Em seguida, modifique gulpfile.js para adicionar uma variável de sass e uma tarefa para compilar os arquivos Sass
e colocar os resultados na pasta wwwroot:
fs = require("fs"),
less = require("gulp-less"),
sass = require("gulp-sass");
// other content removed
gulp.task("sass", function () {
return gulp.src('Styles/main2.scss')
.pipe(sass())
.pipe(gulp.dest('wwwroot/css'));
});
Agora você pode adicionar o arquivo Sass main2.scss para o estilos pasta na raiz do projeto:
Abra main2.scss e adicione o seguinte:
$base: #CC0000;
body {
background-color: $base;
}
Salve todos os arquivos. Agora quando você atualiza Explorador do Executador de tarefas, você verá um sass
tarefa. Executá-lo e examinar o /wwwroot/css pasta. Agora há uma main2.css arquivo com esse conteúdo:
body {
background-color: #CC0000;
}
Sass oferece suporte a aninhamento praticamente o mesmo foi que less não, fornecer benefícios semelhantes. Os
arquivos podem ser divididos por função e incluídos usando a @import diretiva:
@import 'anotherfile';
Sass oferece suporte a mixins, usando o @mixin palavra-chave para defini-los e @include para incluí-los, como
neste exemplo de sass lang.com:
@mixin border-radius($radius) {
-webkit-border-radius: $radius;
-moz-border-radius: $radius;
-ms-border-radius: $radius;
border-radius: $radius;
}
.box { @include border-radius(10px); }
Além mixins, Sass também oferece suporte ao conceito de herança, permitindo que uma classe estender o outro.
Ele é conceitualmente semelhante a um mesclado, mas resulta em menos código CSS. Ela é realizada usando o
@extend palavra-chave. Para testar mixins, adicione o seguinte ao seu main2.scss arquivo:
@mixin alert {
border: 1px solid black;
padding: 5px;
color: #333333;
}
.success {
@include alert;
border-color: green;
}
.error {
@include alert;
color: red;
border-color: red;
font-weight:bold;
}
Examine a saída em main2.css depois de executar o sass tarefa no Explorador do Executador de tarefas:
.success {
padding: 5px;
color: #333333;
}
.error {
padding: 5px;
color: #333333;
color: red;
border-color: red;
font-weight: bold;
}
Observe que todas as propriedades comuns do alerta mesclado são repetidas em cada classe. O mesclado foi um
bom trabalho de ajudar a eliminar a duplicação no tempo de desenvolvimento, mas ela ainda está criando um CSS
com muita duplicação, resultando em maior do que arquivos CSS necessários - um possível problema de
desempenho.
Agora, substitua o alerta mesclado com um .alert classe e altere @include para @extend (Lembre-se estender
.alert , não alert ):
.alert {
padding: 5px;
color: #333333;
}
.success {
@extend .alert;
}
.error {
@extend .alert;
color: red;
border-color: red;
font-weight:bold;
}
Execute Sass mais uma vez e examine o CSS resultante:
.alert, .success, .error {

padding: 5px;
color: #333333;
}
.success {
}
.error {
color: red;
border-color: red;
font-weight: bold;
}
Agora as propriedades são definidas apenas como quantas vezes forem necessárias, e melhor CSS é gerado.
Sass também inclui funções e operações de lógica condicional, semelhantes ao less. Na verdade, os recursos de
dois idiomas são muito semelhantes.
Less ou Sass?
Ainda não há consenso se geralmente é melhor usar less ou Sass (ou até mesmo se preferir o Sass original ou a
sintaxe SCSS mais recente em Sass). Provavelmente, a decisão mais importante é usar uma dessas ferramentas,
em vez de apenas codificação manual em seus arquivos CSS. Depois que você fez essa decisão, ambos Less e Sass
são boas opções.
Font Awesome
Além de pré-processadores CSS, outro excelente recurso para aplicativos web modernos de estilo é incrível de
fonte. Lista de fonte é um kit de ferramentas fornece mais de 500 ícones de SVG que podem ser usados livremente
em seus aplicativos web. Ela foi originalmente projetada para trabalhar com inicialização, mas ele não tem
nenhuma dependência no framework ou em qualquer biblioteca de JavaScript.
A maneira mais fácil começar com o incríveis fonte é adicionar uma referência a ele, usando seu local de rede
(CDN ) do fornecimento de conteúdo público:
<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
Você também pode adicioná-lo ao seu projeto do Visual Studio adicionando-as "dependências" em bower. JSON:
{
"name": "ASP.NET",
"private": true,
"dependencies": {
"bootstrap": "3.0.0",
"jquery": "1.10.2",
"jquery-validation": "1.11.1",
"jquery-validation-unobtrusive": "3.2.2",
"hammer.js": "2.0.4",
"bootstrap-touch-carousel": "0.8.0",
"Font-Awesome": "4.3.0"
}
}
Depois que você tem uma referência para o incríveis fonte em uma página, você pode adicionar ícones para o seu
aplicativo aplicando fonte Awesome classes, normalmente é prefixados com "fa-", para os elementos embutidos
HTML (como <span> ou <i> ). Por exemplo, você pode adicionar ícones de listas simples e menus usando código
como este:
<!DOCTYPE html>
<html>
<head>
<title></title>
<link href="lib/font-awesome/css/font-awesome.css" rel="stylesheet" />
</head>
<body>
<ul class="fa-ul">
<li><i class="fa fa-li fa-home"></i> Home</li>
<li><i class="fa fa-li fa-cog"></i> Settings</li>
</ul>
</body>
</html>
Isso produz o seguinte no navegador - Observe o ícone ao lado de cada item:
Você pode exibir uma lista completa de ícones disponíveis:

http://fontawesome.io/icons/
Resumo
Aplicativos web modernos exigem designs cada vez mais responsivos e fluidos que são normais, intuitivos e fáceis
de usar em uma variedade de dispositivos. Gerenciar a complexidade das folhas de estilo CSS necessárias para
atingir essas metas é melhor usando um tipo de pré-processador less ou Sass. Além disso, kits de ferramentas
como a Awesome fonte rapidamente fornecem ícones conhecidos a menus de navegação textual e experiência de
botões, melhorando o usuário do seu aplicativo.
Agrupar e minificar ativos estáticos no ASP.NET Core
Por Scott Addie e Alcatrão de David

Este artigo explica os benefícios da aplicação de agrupamento e minificação, incluindo como esses recursos
podem ser usados com aplicativos web ASP.NET Core.
O que é o agrupamento e minificação

Agrupamento e minificação são duas otimizações de desempenho distintos, que você pode aplicar em um
aplicativo web. Usados juntos, agrupamento e minificação melhoram o desempenho reduzindo o número de
solicitações do servidor e reduzindo o tamanho dos ativos mais solicitados estáticos.
Agrupamento e minificação basicamente melhoram o tempo de carregamento de solicitação de página primeiro.
Depois que uma página da web foi solicitado, o navegador armazena em cache os recursos estáticos (JavaScript,
CSS e imagens). Consequentemente, agrupamento e minificação não melhoram o desempenho ao solicitar a
mesma página ou páginas, no mesmo site que está solicitando os mesmos recursos. Se a expira cabeçalho não
está definido corretamente nos ativos e se não for usado o agrupamento e minificação, heurística de atualização
do navegador marca os ativos obsoletos depois de alguns dias. Além disso, o navegador requer uma solicitação
de validação para cada ativo. Nesse caso, o agrupamento e minificação fornecem uma melhoria de desempenho,
mesmo após a primeira solicitação de página.
Agrupamento
O agrupamento combina vários arquivos em um único arquivo. Agrupamento reduz o número de solicitações de
servidor que são necessários para renderizar um ativo da web, como uma página da web. Você pode criar
qualquer número de pacotes individuais especificamente para o CSS, JavaScript, etc. Menos arquivos significa
menos solicitações HTTP do navegador para o servidor ou do serviço de fornecimento de seu aplicativo. Isso
resulta em melhor desempenho de carregamento de página primeiro.
Minimização
Minificação remove caracteres desnecessários de código sem alterar a funcionalidade. O resultado é uma redução
de tamanho significativo nos ativos mais solicitados (como CSS, imagens e arquivos JavaScript). Os efeitos
colaterais de minimização incluem encurtar os nomes de variável para um caractere e remover comentários e
espaço em branco desnecessário.
Considere a seguinte função de JavaScript:
AddAltToImg = function (imageTagAndImageID, imageContext) {

///<signature>
///<summary> Adds an alt tab to the image
// </summary>
//<param name="imgElement" type="String">The image selector.</param>
//<param name="ContextForImage" type="String">The image context.</param>
///</signature>
var imageElement = $(imageTagAndImageID, imageContext);
imageElement.attr('alt', imageElement.attr('id').replace(/ID/, ''));
}
Minimização reduz a função para o seguinte:

AddAltToImg=function(t,a){var r=$(t,a);r.attr("alt",r.attr("id").replace(/ID/,""))};
Além de remover os comentários e espaço em branco desnecessário, os seguintes nomes de parâmetro e variável
foram renomeados da seguinte maneira:
ORIGINAL RENOMEADO
imageTagAndImageID t
imageContext a
imageElement r
Impacto de agrupamento e minificação

A tabela a seguir descreve as diferenças entre carregar ativos individualmente e usando o agrupamento e
minificação:
AÇÃO COM B/M SEM B/M ALTERAÇÃO
Solicitações de arquivos 7 18 157%
KB transferido 156 264.68 70%
Tempo de carregamento 885 2360 167%

(ms)
Navegadores são bastante detalhados em relação a cabeçalhos de solicitação HTTP. O total de bytes enviados
métrica viu uma redução significativa ao agrupamento. O tempo de carregamento mostra uma melhoria
significativa, no entanto, este exemplo foi executado localmente. Maior ganhos de desempenho são obtidos ao
usar o agrupamento e minificação com ativos transferidos por uma rede.
Escolher uma estratégia de agrupamento e minificação

Os modelos de projeto do MVC e páginas Razor oferecem uma solução de out-of-the-box para agrupamento e
minificação consiste em um arquivo de configuração JSON. Ferramentas de terceiros, tais como o Gulp e Grunt
executores de tarefas, executar as mesmas tarefas com um pouco mais complexidade. Uma ferramenta de
terceiros é uma excelente opção quando o fluxo de trabalho de desenvolvimento requer processamento além do
agrupamento e minificação—como otimização linting e imagem. Usando o agrupamento e minificação tempo de
design, os arquivos reduzidos são criados antes da implantação do aplicativo. Empacotando e minimizando antes
da implantação tem a vantagem de carga do servidor reduzido. No entanto, é importante reconhecer que esse
tempo de design de agrupamento e minificação aumenta a complexidade de build e só funciona com arquivos
estáticos.
Configurar o agrupamento e minificação

Os modelos de projeto MVC e páginas do Razor fornecem uma bundleconfig.json arquivo de configuração que
define as opções para cada pacote. Por padrão, uma configuração de pacote único é definida para o JavaScript
personalizado (wwwroot/js/site.js) e a folha de estilos (wwwroot/css/site.css) arquivos:
[
{
"outputFileName": "wwwroot/css/site.min.css",
"inputFiles": [
"wwwroot/css/site.css"
]
},
{
"outputFileName": "wwwroot/js/site.min.js",
"inputFiles": [
"wwwroot/js/site.js"
],
"minify": {
"enabled": true,
"renameLocals": true
},
"sourceMap": false
}
]
Opções de configuração incluem:

outputFileName : O nome do arquivo de pacote de saída. Pode conter um caminho relativo do
bundleconfig.json arquivo. Necessário
inputFiles : Uma matriz de arquivos para agrupar. Esses são os caminhos relativos para o arquivo de
configuração. opcional, * um valor vazio resulta em um arquivo de saída vazia. recurso de curinga padrões
são suportados.
minify : As opções de minimização para o tipo de saída. opcional, padrão: minify: { enabled: true }
Opções de configuração estão disponíveis por tipo de arquivo de saída.
Minificador CSS
Minificador de JavaScript
Minificador de HTML
includeInProject : O sinalizador que indica se deseja adicionar os arquivos gerados para o arquivo de projeto.
opcional, padrão – false
sourceMap : O sinalizador que indica se é necessário gerar um mapa de código-fonte para o arquivo agrupado.
opcional, padrão – false
sourceMapRootPath : O caminho raiz para armazenar o arquivo de mapa de código-fonte gerado.
Compilação em tempo de execução de agrupamento e minificação

O BuildBundlerMinifier pacote NuGet permite que a execução de agrupamento e minificação no momento da
compilação. O pacote injeta destinos do MSBuild quais executar na compilação e de hora limpa. O
bundleconfig.json arquivo é analisado pelo processo de compilação para produzir os arquivos de saída com base
na configuração definida.
NOTE
BuildBundlerMinifier pertence a um projeto voltado à comunidade no GitHub para o qual a Microsoft fornece sem suporte.
Problemas devem ser arquivados aqui.
Visual Studio
CLI do .NET Core
Adicione a BuildBundlerMinifier pacote ao seu projeto.
Compile o projeto. O exemplo a seguir é exibida na janela de saída:
1>------ Build started: Project: BuildBundlerMinifierApp, Configuration: Debug Any CPU ------
1>
1>Bundler: Begin processing bundleconfig.json
1> Minified wwwroot/css/site.min.css
1> Minified wwwroot/js/site.min.js
1>Bundler: Done processing bundleconfig.json
1>BuildBundlerMinifierApp -> C:\BuildBundlerMinifierApp\bin\Debug\netcoreapp2.0\BuildBundlerMinifierApp.dll
Limpe o projeto. O exemplo a seguir é exibida na janela de saída:
1>------ Clean started: Project: BuildBundlerMinifierApp, Configuration: Debug Any CPU ------
1>
1>Bundler: Cleaning output from bundleconfig.json
1>Bundler: Done cleaning output file from bundleconfig.json
========== Clean: 1 succeeded, 0 failed, 0 skipped ==========
Execução ad hoc de agrupamento e minificação

É possível executar as tarefas de empacotamento e minimização em uma base ad hoc, sem compilar o projeto.
Adicione a BundlerMinifier.Core pacote NuGet ao seu projeto:
<DotNetCliToolReference Include="BundlerMinifier.Core" Version="2.6.362" />
NOTE
BundlerMinifier.Core pertence a um projeto voltado à comunidade no GitHub para o qual a Microsoft fornece sem suporte.
Problemas devem ser arquivados aqui.
Este pacote estende a CLI do .NET Core para incluir a pacote dotnet ferramenta. O comando a seguir pode ser
executado na janela do Console de Gerenciador de pacote (PMC ) ou em um shell de comando:
dotnet bundle
IMPORTANT
Gerenciador de pacotes NuGet adiciona as dependências para o arquivo *. csproj como <PackageReference /> nós. O
dotnet bundle comando está registrado com a CLI do .NET Core somente quando um <DotNetCliToolReference /> nó
é usado. Modifique o arquivo *. csproj adequadamente.
Adicionar arquivos ao fluxo de trabalho

Considere um exemplo no qual adicional Custom. CSS arquivo for adicionado a seguir:
.about, [role=main], [role=complementary] {
margin-top: 60px;
}
footer {
margin-top: 10px;
}
Para minificar Custom. CSS e agrupá-la com CSS em um site arquivo, adicione o caminho relativo para
bundleconfig.json:
[
{
"outputFileName": "wwwroot/css/site.min.css",
"inputFiles": [
"wwwroot/css/site.css",
"wwwroot/css/custom.css"
]
},
{
"outputFileName": "wwwroot/js/site.min.js",
"inputFiles": [
"wwwroot/js/site.js"
],
"minify": {
"enabled": true,
"renameLocals": true
},
"sourceMap": false
}
]
NOTE
Como alternativa, é possível usar o seguinte padrão de recurso de curinga:
"inputFiles": ["wwwroot/**/*(*.css|!(*.min.css))"]
Esse padrão de recurso de curinga corresponde a todos os arquivos CSS e exclui o padrão de arquivo reduzido.
Compile o aplicativo. Abra site e observe o conteúdo da Custom. CSS é acrescentado ao final do arquivo.
Agrupamento e minificação com base no ambiente

Como prática recomendada, os arquivos agrupados e minificados do seu aplicativo devem ser usados em um
ambiente de produção. Durante o desenvolvimento, os arquivos originais fazem para depuração mais fácil do
aplicativo.
Especificar quais arquivos serão incluídos em suas páginas usando o auxiliar de marca de ambiente em modos de
exibição. O auxiliar de marca de ambiente renderiza apenas seu conteúdo ao executar em particular ambientes.
O seguinte environment marca renderiza os arquivos CSS não processados durante a execução no Development
ambiente:
ASP.NET Core 2.x
ASP.NET Core 1.x
</environment>
O seguinte environment marca renderiza os arquivos CSS agrupados e minificados quando em execução em um
ambiente diferente de Development . Por exemplo, em execução no Production ou Staging dispara o
processamento dessas folhas de estilo:
ASP.NET Core 2.x
ASP.NET Core 1.x
value="absolute" />
</environment>
Consumir bundleconfig.json do Gulp

Há casos em que o fluxo de trabalho agrupamento e minificação do aplicativo requer processamento adicional.
Exemplos incluem processamento de ativos da CDN, extrapolação de cache e otimização de imagem. Para
atender a esses requisitos, você pode converter o fluxo de trabalho de agrupamento e minificação para usar o
Gulp.
Usar a extensão Bundler & Minifier
O Visual Studio Bundler & Minifier extensão lida com a conversão para o Gulp.
NOTE
A extensão Bundler & Minifier pertence a um projeto voltado à comunidade no GitHub para o qual a Microsoft fornece sem
suporte. Problemas devem ser arquivados aqui.
Clique com botão direito do bundleconfig.json arquivo no Gerenciador de soluções e selecione Bundler &
Minifier > converter Gulp... :
O gulpfile. js e Package. JSON arquivos são adicionados ao projeto. O suporte a npm os pacotes listados na
Package. JSON do arquivo devDependencies seção estão instalados.
Execute o seguinte comando na janela do PMC para instalar a CLI do Gulp como uma dependência global:
npm i -g gulp-cli
O gulpfile. js leituras de arquivos a bundleconfig.json arquivo para as entradas, saídas e as configurações.
'use strict';
var gulp = require('gulp'),

concat = require('gulp-concat'),
cssmin = require('gulp-cssmin'),
htmlmin = require('gulp-htmlmin'),
uglify = require('gulp-uglify'),
merge = require('merge-stream'),
del = require('del'),
bundleconfig = require('./bundleconfig.json');
// Code omitted for brevity
Converter manualmente
Se o Visual Studio e/ou a extensão Bundler & Minifier não estiverem disponível, converta manualmente.
Adicionar um Package. JSON arquivo pelo seguinte devDependencies , para a raiz do projeto:
"del": "^3.0.0",
"gulp": "^4.0.0",
"gulp-concat": "^2.6.1",
"gulp-cssmin": "^0.2.0",
"gulp-htmlmin": "^3.0.0",
"gulp-uglify": "^3.0.0",
"merge-stream": "^1.0.1"
}
Instalar as dependências, executando o comando a seguir no mesmo nível que Package. JSON:
npm i
Instale a CLI do Gulp como uma dependência global:
npm i -g gulp-cli
Cópia de gulpfile. js abaixo o arquivo para a raiz do projeto:

'use strict';
var gulp = require('gulp'),

concat = require('gulp-concat'),
cssmin = require('gulp-cssmin'),
htmlmin = require('gulp-htmlmin'),
uglify = require('gulp-uglify'),
merge = require('merge-stream'),
del = require('del'),
bundleconfig = require('./bundleconfig.json');
const regex = {
css: /\.css$/,
html: /\.(html|htm)$/,
js: /\.js$/
};
gulp.task('min:js',
() => merge(getBundles(regex.js).map(bundle => {
return gulp.src(bundle.inputFiles, { base: '.' })
.pipe(concat(bundle.outputFileName))
.pipe(uglify())
.pipe(gulp.dest('.'));
})));
gulp.task('min:css',
() => merge(getBundles(regex.css).map(bundle => {
.pipe(cssmin())
})));
gulp.task('min:html',
() => merge(getBundles(regex.html).map(bundle => {
.pipe(htmlmin({ collapseWhitespace: true, minifyCSS: true, minifyJS: true }))
})));
gulp.task('min', gulp.series(['min:js', 'min:css', 'min:html']));
gulp.task('clean', () => {
return del(bundleconfig.map(bundle => bundle.outputFileName));
});
gulp.task('watch', () => {
getBundles(regex.js).forEach(
bundle => gulp.watch(bundle.inputFiles, gulp.series(["min:js"])));
getBundles(regex.css).forEach(
bundle => gulp.watch(bundle.inputFiles, gulp.series(["min:css"])));
getBundles(regex.html).forEach(
bundle => gulp.watch(bundle.inputFiles, gulp.series(['min:html'])));
});
const getBundles = (regexPattern) => {

return bundleconfig.filter(bundle => {
return regexPattern.test(bundle.outputFileName);
});
};
gulp.task('default', gulp.series(['min']));
Executar tarefas de Gulp
Para disparar a tarefa do Gulp minificação antes que o projeto é compilado no Visual Studio, adicione o seguinte
destino do MSBuild para o arquivo *. csproj:
<Target Name="MyPreCompileTarget" BeforeTargets="Build">

<Exec Command="gulp min" />
</Target>
Neste exemplo, as tarefas definidas dentro de MyPreCompileTarget execução antes do predefinidos de destino
Build destino. Saída semelhante à seguinte é exibida na janela de saída do Visual Studio:
1>------ Build started: Project: BuildBundlerMinifierApp, Configuration: Debug Any CPU ------
1>BuildBundlerMinifierApp -> C:\BuildBundlerMinifierApp\bin\Debug\netcoreapp2.0\BuildBundlerMinifierApp.dll
1>[14:17:49] Using gulpfile C:\BuildBundlerMinifierApp\gulpfile.js
1>[14:17:49] Starting 'min:js'...
1>[14:17:49] Starting 'min:css'...
1>[14:17:49] Starting 'min:html'...
1>[14:17:49] Finished 'min:js' after 83 ms
1>[14:17:49] Finished 'min:css' after 88 ms
Como alternativa, o Gerenciador de executor de tarefas do Visual Studio pode ser usado para associar as tarefas
de Gulp a eventos específicos do Visual Studio. Ver execução de tarefas padrão para obter instruções sobre como
fazer isso.
Recursos adicionais
Usar o Gulp
Usar o Grunt
Usar vários ambientes
Link do navegador no ASP.NET Core
Por Nicolò Carandini, Mike Wasson, e Tom Dykstra

Link do navegador é um recurso no Visual Studio que cria um canal de comunicação entre o ambiente de
desenvolvimento e um ou mais navegadores da web. Você pode usar o Link do navegador para atualizar seu
aplicativo web em vários navegadores ao mesmo tempo, que é útil para testes entre navegadores.
Configuração do Link de navegador

Ao converter um projeto do ASP.NET Core 2.0 para ASP.NET Core 2.1 e fazer a transição para o metapacote do
Microsoft, instale o browserlink do pacote para Funcionalidade BrowserLink. Usam os modelos de projeto do
ASP.NET Core 2.1 a Microsoft.AspNetCore.App metapacote por padrão.
O ASP.NET Core 2.0 aplicativo Web, vazia, e API da Web uso de modelos de projeto a
Microsoft.AspNetCore.All metapacote , que contém uma referência de pacote para browserlink. Portanto, usando o
Microsoft.AspNetCore.All metapacote não requer nenhuma ação adicional para disponibilizar o Link do
navegador para uso.
O ASP.NET Core 1.x aplicativo Web modelo de projeto possui uma referência de pacote para o browserlink
pacote. O vazio ou API da Web exigem que você adicione uma referência de pacote para projetos de modelo
Microsoft.VisualStudio.Web.BrowserLink .
Como esse é um recurso do Visual Studio, a maneira mais fácil para adicionar o pacote para um vazio ou API da
Web projeto modelo é abrir o Package Manager Console (Modo de exibição > Other Windows > Package
Manager Console) e execute o seguinte comando:
install-package Microsoft.VisualStudio.Web.BrowserLink
Como alternativa, você pode usar Gerenciador de pacotes NuGet. Clique com botão direito no nome do projeto
no Gerenciador de soluções e escolha Manage NuGet Packages:
Localizar e instalar o pacote:
Configuração
No método Startup.Configure :
Normalmente, o código está dentro de um if bloco que apenas permite que o Link do navegador no ambiente
de desenvolvimento, como mostrado aqui:
{
}
Para obter mais informações, veja Usar vários ambientes.
Como usar o Link do navegador

Quando um projeto do ASP.NET Core está aberto, o Visual Studio mostra o controle de barra de ferramentas do
Link do navegador ao lado do controle de barra de ferramentas do Destino de Depuração:
O controle de barra de ferramentas do Link do navegador, você pode:

Atualizar o aplicativo Web em vários navegadores de uma vez.
Abrir o Painel de link do navegador.
Habilitar ou desabilitar Link do navegador. Observação: O Link do navegador está desabilitado por padrão no
Visual Studio 2017 (15.3).
Habilitar ou desabilitar sincronização automática de CSS.
NOTE
Alguns plug-ins do Visual Studio, mais notavelmente Web extensão Pack 2015 e 2017 de pacote de extensão do Web,
oferecem funcionalidade estendida para o Link do navegador, mas alguns dos recursos adicionais não funcionam com o ASP.
Projetos do .NET Core.
Atualizar o aplicativo web em vários navegadores ao mesmo tempo

Para escolher um único navegador Web para abrir ao iniciar o projeto, use o menu suspenso do controle de barra
de ferramentas do Destino de depuração:
Para abrir vários navegadores, ao mesmo tempo, escolha procurar com... da mesma lista suspensa. Mantenha
pressionada a tecla CTRL para selecionar os navegadores que você deseja e, em seguida, clique em procurar:
Aqui está uma captura de tela mostrando o Visual Studio com o modo de exibição de índice aberto e dois
navegadores abertas:
Passe o mouse sobre o controle de barra de ferramentas do Link do navegador para ver os navegadores que estão
conectados ao projeto:
Altere o modo de exibição de índice e todos os navegadores conectados são atualizados quando você clicar no
botão de atualização de Link do navegador:
Link do navegador também funciona com navegadores que você inicie de fora do Visual Studio e navegue até a
URL do aplicativo.
O painel de Link do navegador
Abra o painel de Link do navegador de menu para gerenciar a conexão com o navegador abertas suspenso Link
do navegador:
Se nenhum navegador estiver conectado, você pode iniciar uma sessão de depuração não, selecionando Se
nenhum navegador estiver conectado, você poderá iniciar uma sessão de não depuração selecionando o link exibir
no navegador:
Caso contrário, os navegadores conectados são mostrados com o caminho para a página que mostra cada
navegador:
Se desejar, você pode clicar em um nome de navegador listados para atualizar esse único navegador.
Habilitar ou desabilitar o Link do navegador
Quando você habilita novamente o Link do navegador depois de desabilitá-lo, você deve atualizar os navegadores
para reconectar-se-los.
Habilitar ou desabilitar a sincronização automática de CSS
Quando a sincronização automática de CSS está habilitada, os navegadores conectados serão atualizados
automaticamente quando você fizer qualquer alteração em arquivos CSS.
Como ele funciona

Link do navegador usa o SignalR para criar um canal de comunicação entre o Visual Studio e o navegador.
Quando o Link do navegador está habilitado, o Visual Studio atua como um servidor de SignalR que vários
clientes (navegadores) podem se conectar ao. Link do navegador também registra um componente de middleware
no pipeline de solicitação do ASP.NET Core. Esse componente injeta especial <script> referências em cada
solicitação de página do servidor. Você pode ver as referências de script selecionando Exibir código-fonte no
navegador e rolar até o final do <body> conteúdo de marca:


<script type="application/json" id="__browserLink_initializationData">
{"requestId":"a717d5a07c1741949a7cefd6fa2bad08","requestMappingFromServer":false}
</script>
<script type="text/javascript" src="http://localhost:54139/b6e36e429d034f578ebccd6a79bf19bf/browserLink"
async="async"></script>

</body>
Os arquivos de origem não são modificados. O componente de middleware injeta as referências de script
dinamicamente.
Como o código do navegador é todo JavaScript, ele funciona em todos os navegadores SignalR dá suporte a sem
a necessidade de um plug-in de navegador.
Usar os modelos de Aplicativo de Página Única com
o ASP.NET Core
NOTE
O SDK do .NET Core 2.0.x inclui modelos de projeto mais antigos para Angular, React e React with Redux. Esta documentação
não é sobre esses modelos de projeto antigos. Essa documentação é para os modelos Angular, React e React with Redux
mais recentes, que podem ser instalados manualmente no ASP.NET Core 2.0. Os modelos são incluídos por padrão com o
ASP.NET Core 2.1.
Pré-requisitos
Node.js, versão 6 ou posterior
Instalação
Os modelos já estão instalados com o ASP.NET Core 2.1.
Se você tiver o ASP.NET Core 2.0, execute o seguinte comando para instalar os modelos do ASP.NET Core
atualizados para Angular, React e React with Redux:
dotnet new --install Microsoft.DotNet.Web.Spa.ProjectTemplates::2.0.0
Usar os modelos
Usar o modelo de projeto Angular
Usar o modelo de projeto React
Usar o modelo de projeto React with Redux
Usar o modelo de projeto Angular com o ASP.NET
Core
NOTE
Esta documentação não é sobre o modelo de projeto do Angular incluído no ASP.NET Core 2.0. Ela é sobre o modelo
Angular mais recente, para o qual você pode atualizar manualmente. O modelo está incluído no ASP.NET Core 2.1 por
padrão.
O modelo de projeto do Angular atualizado fornece um ponto inicial conveniente para aplicativos do ASP.NET
Core usando o Angular e a CLI do Angular para implementar uma IU (interface do usuário) avançada do lado do
cliente.
O modelo é equivalente à criação de um projeto do ASP.NET Core para atuar como um back-end de API e um
projeto de CLI do Angular para atuar como uma interface do usuário. O modelo oferece a conveniência de
hospedagem de ambos os tipos de projeto em um projeto de aplicativo único. Consequentemente, o projeto de
aplicativo pode ser criado e publicado como uma única unidade.
Criar um novo aplicativo

Se usar o ASP.NET Core 2.0, verifique se você instalou o modelo de projeto do Angular atualizado.
Se você tiver o ASP.NET Core 2.1 instalado, não será necessário instalar o modelo de projeto Angular.
Crie um novo projeto de um prompt de comando usando o comando dotnet new angular em um diretório vazio.
Por exemplo, os seguintes comandos criam o aplicativo em um diretório my-new -app e mudam para esse
diretório:
dotnet new angular -o my-new-app

cd my-new-app
Execute o aplicativo do Visual Studio ou da CLI do .NET Core:

Visual Studio
CLI do .NET Core
Abra o arquivo .csproj gerado e execute o aplicativo normalmente de lá.
O processo de build restaura dependências npm na primeira execução, o que pode levar vários minutos. Builds
subsequentes são muito mais rápidos.
O modelo de projeto cria um aplicativo ASP.NET Core e um aplicativo do Angular. O aplicativo ASP.NET Core
destina-se a ser usado para acesso a dados, autorização e outras questões do lado do servidor. O aplicativo do
Angular, que reside no subdiretório ClientApp, destina-se a ser usado para todas as questões de interface do
usuário.
Adicione páginas, imagens, estilos, módulos, etc.

O diretório ClientApp contém um aplicativo padrão da CLI do Angular. Veja a documentação oficial do Angular
para obter mais informações.
Há pequenas diferenças entre o aplicativo do Angular criado por este modelo e um criado pela CLI do Angular
propriamente dita (por meio de ng new ); no entanto, os recursos do aplicativo são inalterados. O aplicativo criado
pelo modelo contém um layout com base em Bootstrap e um exemplo básico de roteamento.
Executar comandos ng
Em um prompt de comando, mude para o subdiretório ClientApp:
cd ClientApp
Se você tiver a ferramenta ng instalada globalmente, você poderá executar qualquer um dos seus comandos. Por
exemplo, você poderá executar ng lint , ng test ou qualquer um dos outros comandos da CLI do Angular. No
entanto, não é necessário executar ng serve , porque o seu aplicativo ASP.NET Core dá conta de servir tanto a
parte do lado do servidor quanto a do lado do cliente do seu aplicativo. Internamente, ele usa ng serve em
desenvolvimento.
Se você não tiver a ferramenta ng instalada, execute npm run ng em vez dela. Por exemplo, você pode executar
npm run ng lint ou npm run ng test .
Instalar pacotes npm

Para instalar pacotes npm de terceiros, use um prompt de comando no subdiretório ClientApp. Por exemplo:
cd ClientApp
npm install --save <package_name>
Publicar e implantar
No desenvolvimento, o aplicativo é executado de um modo otimizado para conveniência do desenvolvedor. Por
exemplo, pacotes JavaScript incluem mapas de origem (de modo que durante a depuração, você pode ver o
código TypeScript original). O aplicativo observa alterações em arquivos TypeScript, HTML e CSS no disco e
recompila e recarrega automaticamente quando as detecta.
Em produção, atende a uma versão de seu aplicativo que é otimizada para desempenho. Isso é configurado para
ocorrer automaticamente. Quando você publica, a configuração de build emite um build minificado em
compilação AoT (Ahead Of Time) do código do lado do cliente. Diferentemente do build de desenvolvimento, o
build de produção não requer que o Node.js esteja instalado no servidor (a menos que você tenha habilitado a
pré-renderização do lado do servidor ).
Você pode usar os métodos padrão de implantação e hospedagem do ASP.NET Core.
Executar "ng serve" independentemente

O projeto está configurado para iniciar sua própria instância do servidor da CLI do Angular em segundo plano
quando o aplicativo ASP.NET Core é iniciado no modo de desenvolvimento. Isso é conveniente, porque você não
precisa executar um servidor separado manualmente.
Há uma desvantagem nessa configuração padrão. Cada vez que você modificar seu código C# e o aplicativo
ASP.NET Core precisar ser reiniciado, o servidor da CLI do Angular será reiniciado também. São necessários
aproximadamente 10 segundos para iniciar um backup. Se você estiver fazendo edições frequentes de código C#
e não quiser esperar a CLI do Angular reiniciar, execute o servidor da CLI do Angular externamente,
independentemente do processo do ASP.NET Core. Para fazer isso:
1. Em um prompt de comando, vá para o subdiretório ClientApp e inicie o Development Server da CLI do
Angular:
cd ClientApp
npm start
IMPORTANT
Use npm start para iniciar o Development Server da CLI do Angular, não ng serve , de modo que a configuração
no package.json seja respeitada. Para passar parâmetros adicionais para o servidor da CLI do Angular, adicione-os à
linha scripts relevante em seu arquivo package.json.
2. Modifique o aplicativo ASP.NET Core para, em vez de iniciar uma instância da CLI do Angular própria,
usar a externa. Na classe Startup, substitua a invocação spa.UseAngularCliServer pelo seguinte:
spa.UseProxyToSpaDevelopmentServer("http://localhost:4200");
Quando você iniciar seu aplicativo ASP.NET Core, ele não inicializará um servidor da CLI do Angular. Em vez
disso, a instância que você iniciou manualmente é usada. Isso permite a ele iniciar e reiniciar mais rapidamente.
Ele não está mais aguardando a CLI do Angular recompilar o aplicativo cliente a cada vez.
Renderização do lado do servidor

Como um recurso de desempenho, você pode escolher pré-renderizar seu aplicativo do Angular no servidor, bem
como executá-lo no cliente. Isso significa que os navegadores recebem uma marcação HTML que representa a
interface do usuário inicial do aplicativo, para exibirem mesmo antes de baixar e executar os pacotes de
JavaScript. A maior parte da implementação disso vem de um recurso do Angular chamado Angular Universal.
TIP
Habilitar a SSR (renderização do lado do servidor) apresenta uma série de complicações adicionais, durante o
desenvolvimento e a implantação. Leia desvantagens da SSR para determinar se a SSR é uma boa opção para as suas
necessidades.
Para habilitar a SSR, você precisa fazer um número de adições ao seu projeto.
Na classe Startup, após a linha que configura spa.Options.SourcePath e antes da chamada para
UseAngularCliServer ou UseProxyToSpaDevelopmentServer , adicione o seguinte:
app.UseSpa(spa =>
{
spa.Options.SourcePath = "ClientApp";
spa.UseSpaPrerendering(options =>
{
options.BootModulePath = $"{spa.Options.SourcePath}/dist-server/main.bundle.js";
options.BootModuleBuilder = env.IsDevelopment()
? new AngularCliBuilder(npmScript: "build:ssr")
: null;
options.ExcludeUrls = new[] { "/sockjs-node" };
});
{
spa.UseAngularCliServer(npmScript: "start");
}
});
No modo de desenvolvimento, esse código tentará criar o pacote SSR executando o script build:ssr , que é
definido em ClientApp\package.json. Isso cria um aplicativo do Angular chamado ssr , que ainda não está
definido.
No final da matriz apps em ClientApp/.angular-cli.json, defina um aplicativo adicional com o nome ssr . Use as
seguintes opções:
{
"name": "ssr",
"root": "src",
"outDir": "dist-server",
"assets": [
"assets"
],
"main": "main.server.ts",
"tsconfig": "tsconfig.server.json",
"prefix": "app",
"scripts": [],
"environmentSource": "environments/environment.ts",
"environments": {
"dev": "environments/environment.ts",
"prod": "environments/environment.prod.ts"
},
"platform": "server"
}
Essa nova configuração de aplicativo habilitada para SSR requer dois arquivos adicionais: tsconfig.server.json e
main.server.ts. O arquivo tsconfig.server.json especifica opções de compilação de TypeScript. O arquivo
main.server.ts serve como o ponto de entrada de código durante a SSR.
Adicione um novo arquivo chamado tsconfig.server.json dentro de ClientApp/src (junto com o tsconfig.app.json
existente), contendo o seguinte:
{
"extends": "../tsconfig.json",
"baseUrl": "./",
"module": "commonjs"
},
"angularCompilerOptions": {
"entryModule": "app/app.server.module#AppServerModule"
}
}
Esse arquivo configura o compilador AoT do Angular para procurar por um módulo chamado app.server.module .
Adicione isso ao criar um novo arquivo em ClientApp/src/app/app.server.module.ts (junto com o app.module.ts
existente) que contém o seguinte:
import { NgModule } from '@angular/core';

import { ServerModule } from '@angular/platform-server';
import { ModuleMapLoaderModule } from '@nguniversal/module-map-ngfactory-loader';
import { AppComponent } from './app.component';
import { AppModule } from './app.module';
@NgModule({
imports: [AppModule, ServerModule, ModuleMapLoaderModule],
bootstrap: [AppComponent]
})
export class AppServerModule { }
Esse módulo herda de seu app.module do lado do cliente e define quais módulos extra do Angular estão
disponíveis durante a SSR.
Lembre-se de que a nova entrada ssr em .angular cli.json referenciou de um arquivo de ponto de entrada
chamado main.server.ts. Você ainda não adicionou esse arquivo e agora é hora de fazê-lo. Crie um novo arquivo
em ClientApp/src/main.server.ts (junto com o main.ts existente), contendo o seguinte:
import 'zone.js/dist/zone-node';
import 'reflect-metadata';
import { renderModule, renderModuleFactory } from '@angular/platform-server';
import { APP_BASE_HREF } from '@angular/common';
import { enableProdMode } from '@angular/core';
import { provideModuleMap } from '@nguniversal/module-map-ngfactory-loader';
import { createServerRenderer } from 'aspnet-prerendering';
export { AppServerModule } from './app/app.server.module';
enableProdMode();
export default createServerRenderer(params => {

const { AppServerModule, AppServerModuleNgFactory, LAZY_MODULE_MAP } = (module as any).exports;
const options = {
document: params.data.originalHtml,
url: params.url,
extraProviders: [
provideModuleMap(LAZY_MODULE_MAP),
{ provide: APP_BASE_HREF, useValue: params.baseUrl },
{ provide: 'BASE_URL', useValue: params.origin + params.baseUrl }
]
};
const renderPromise = AppServerModuleNgFactory

? /* AoT */ renderModuleFactory(AppServerModuleNgFactory, options)
: /* dev */ renderModule(AppServerModule, options);
return renderPromise.then(html => ({ html }));

});
O código do arquivo é o que o ASP.NET Core executa para cada solicitação quando ele executa o middleware
UseSpaPrerendering que você adicionou à classe Startup. Ele trata do recebimento de params do código .NET (por
exemplo, a URL que está sendo solicitada) e de fazer chamadas a APIs de SSR do Angular para obter o HTML
resultante.
A rigor, isso é suficiente para habilitar a SSR no modo de desenvolvimento. É essencial para fazer uma alteração
final para que seu aplicativo funcione corretamente quando publicado. No arquivo .csproj principal do seu
aplicativo, defina o valor da propriedade BuildServerSideRenderer para true :


<BuildServerSideRenderer>true</BuildServerSideRenderer>
Isso configura o processo de build para executar build:ssr durante a publicação e implantar os arquivos SSR no
servidor. Se você não habilitar isso, a SSR falhará em produção.
Quando o aplicativo é executado no modo de desenvolvimento ou de produção, o código do Angular é
previamente renderizado como HTML no servidor. O código do lado do cliente é executado normalmente.
Passar dados de código .NET para código do TypeScript
Durante a SSR, convém passar dados por solicitação, do aplicativo ASP.NET Core para o aplicativo do Angular.
Por exemplo, você pode transmitir informações de cookie ou algo lido de um banco de dados. Para fazer isso,
edite a classe Startup. No retorno de chamada para UseSpaPrerendering , defina um valor para options.SupplyData
como o seguinte:
options.SupplyData = (context, data) =>
{
// Creates a new value called isHttpsRequest that's passed to TypeScript code
data["isHttpsRequest"] = context.Request.IsHttps;
};
O retorno de chamada SupplyData permite que você passe dados serializáveis por JSON arbitrários e por
solicitação (por exemplo, cadeias de caracteres, boolianos ou números). O código de main.server.ts recebe isso
como params.data . Por exemplo, o exemplo de código anterior passa um valor booliano como
params.data.isHttpsRequest para o retorno de chamada createServerRenderer . Você pode passar isso para outras
partes do seu aplicativo de alguma forma compatível com o Angular. Por exemplo, veja como main.server.ts passa
o valor BASE_URL para qualquer componente cujo construtor é declarado para recebê-lo.
Desvantagens da SSR
Nem todos os aplicativos se beneficiam da SSR. O principal benefício é o desempenho percebido. Os visitantes
que chegam ao aplicativo por uma conexão de rede lenta ou em dispositivos móveis lentos veem a interface do
usuário inicial rapidamente, mesmo que leve algum tempo para buscar ou para analisar os pacotes de JavaScript.
No entanto, muitos SPAs são usados principalmente em redes de empresa internas e rápidas, em computadores
rápidos nos quais o aplicativo aparece quase instantaneamente.
Ao mesmo tempo, há desvantagens significativas em habilitar a SSR. Ele adiciona complexidade ao seu processo
de desenvolvimento. O código deve ser executado em dois ambientes diferentes: no lado do cliente e no do
servidor (em um ambiente Node.js invocado do ASP.NET Core). Estes são alguns pontos a considerar:
A SSR requer uma instalação de Node.js nos servidores de produção. Isso ocorre automaticamente para
alguns cenários de implantação como Serviços de Aplicativos do Azure, mas não para outros como o Azure
Service Fabric.
Habilitar o sinalizador de build BuildServerSideRenderer faz com que o diretório node_modules seja
publicado. Esta pasta contém mais de 20.000 arquivos, o que aumenta o tempo de implantação.
Para executar o código em um ambiente Node.js, ele não pode depender da existência de APIs de
JavaScript específicas a um navegador, tais como window ou localStorage . Se seu código (ou alguma
biblioteca de terceiros à qual você faz referência) tentar usar essas APIs, você obterá um erro durante a
SSR. Por exemplo, não use jQuery porque faz referência a APIs específicas a um navegador em vários
locais. Para evitar erros, você deve evitar a SSR ou então evitar APIs ou bibliotecas específicas a um
navegador. Você pode encapsular todas as chamadas para essas APIs em verificações para garantir que
elas não sejam invocadas durante a SSR. Por exemplo, use uma verificação como a seguinte no código
JavaScript ou TypeScript:
if (typeof window !== 'undefined') {

// Call browser-specific APIs here
}
Usar o modelo de projeto do React com o ASP.NET
Core
NOTE
Esta documentação não é sobre o modelo de projeto do React incluído no ASP.NET Core 2.0. Ela é sobre o modelo React
mais recente, para o qual você pode atualizar manualmente. O modelo está incluído no ASP.NET Core 2.1 por padrão.
O modelo de projeto do React atualizado fornece um ponto inicial conveniente para aplicativos do ASP.NET Core
usando convenções do React e de CRA (criar-aplicativo-do-React) para implementar uma IU (interface do
usuário) avançada do lado do cliente.
O modelo é equivalente à criação de dois projetos: um projeto do ASP.NET Core, para atuar como um back-end
de API, e um projeto do React CRA padrão, para atuar como uma interface do usuário, mas com a praticidade de
hospedar ambos em um único projeto de aplicativo que pode ser criado e publicado como uma única unidade.
Criar um novo aplicativo

Se usar o ASP.NET Core 2.0, verifique se você instalou o modelo de projeto do React atualizado.
Se você tiver o ASP.NET Core 2.1 instalado, não será necessário instalar o modelo de projeto React.
Crie um novo projeto de um prompt de comando usando o comando dotnet new react em um diretório vazio.
Por exemplo, os seguintes comandos criam o aplicativo em um diretório my-new -app e mudam para esse
diretório:
dotnet new react -o my-new-app

cd my-new-app
Execute o aplicativo do Visual Studio ou da CLI do .NET Core:

Visual Studio
CLI do .NET Core
Abra o arquivo .csproj gerado e execute o aplicativo normalmente de lá.
O processo de build restaura dependências npm na primeira execução, o que pode levar vários minutos. Builds
subsequentes são muito mais rápidos.
O modelo de projeto cria um aplicativo ASP.NET Core e um aplicativo do React. O aplicativo ASP.NET Core
destina-se a ser usado para acesso a dados, autorização e outras questões do lado do servidor. O aplicativo do
React, que reside no subdiretório ClientApp, destina-se a ser usado para todas as questões de interface do
usuário.
Adicione páginas, imagens, estilos, módulos, etc.

O diretório ClientApp é um aplicativo do React CRA padrão. Veja a documentação oficial do CRA para obter mais
informações.
Há pequenas diferenças entre o aplicativo do React criado por este modelo e um criado pelo CRA propriamente
dito; no entanto, os recursos do aplicativo são inalterados. O aplicativo criado pelo modelo contém um layout com
base em Bootstrap e um exemplo básico de roteamento.
Instalar pacotes npm

Para instalar pacotes npm de terceiros, use um prompt de comando no subdiretório ClientApp. Por exemplo:
cd ClientApp
npm install --save <package_name>
Publicar e implantar
No desenvolvimento, o aplicativo é executado de um modo otimizado para conveniência do desenvolvedor. Por
exemplo, pacotes JavaScript incluem mapas de origem (de modo que durante a depuração, você pode ver o
código-fonte original). O aplicativo observa alterações em arquivos JavaScript, HTML e CSS no disco e recompila
e recarrega automaticamente quando as detecta.
Em produção, atende a uma versão de seu aplicativo que é otimizada para desempenho. Isso é configurado para
ocorrer automaticamente. Quando você publica, a configuração de build emite um build minificado e transpilado
do seu código do lado do cliente. Diferentemente do build de desenvolvimento, o build de produção não requer
que o Node.js esteja instalado no servidor.
Você pode usar os métodos padrão de implantação e hospedagem do ASP.NET Core.
Executar o servidor CRA independentemente

O projeto está configurado para iniciar sua própria instância do Development Server do CRA em segundo plano
quando o aplicativo ASP.NET Core é iniciado no modo de desenvolvimento. Isso é conveniente, porque significa
que você não precisa executar um servidor separado manualmente.
Há uma desvantagem nessa configuração padrão. Cada vez que você modificar seu código C# e o aplicativo
ASP.NET Core precisar ser reiniciado, o servidor CRA será reiniciado também. São necessários alguns segundos
para iniciar um backup. Se você estiver fazendo edições frequentes de código C# e não quiser esperar o servidor
CRA reiniciar, execute o servidor CRA externamente, independentemente do processo do ASP.NET Core. Para
fazer isso:
1. Em um prompt de comando, vá para o subdiretório ClientApp e inicie o Development Server do CRA:
cd ClientApp
npm start
2. Modifique o aplicativo ASP.NET Core para, em vez de iniciar uma instância do servidor CRA própria, usar
a externa. Na classe Startup, substitua a invocação spa.UseReactDevelopmentServer pelo seguinte:
spa.UseProxyToSpaDevelopmentServer("http://localhost:3000");
Quando você iniciar seu aplicativo ASP.NET Core, ele não inicializará um servidor CRA. Em vez disso, a instância
que você iniciou manualmente é usada. Isso permite a ele iniciar e reiniciar mais rapidamente. Ele não aguarda
mais que o aplicativo do React seja recompilado a cada vez.
Usar o modelo de projeto do React com Redux com
o ASP.NET Core
NOTE
Esta documentação não é sobre o modelo de projeto do React com Redux incluído no ASP.NET Core 2.0. Ela é sobre o
modelo React com Redux mais recente, para o qual você pode atualizar manualmente. O modelo está incluído no ASP.NET
Core 2.1 por padrão.
O modelo de projeto do React com Redux atualizado fornece um ponto inicial conveniente para aplicativos do
ASP.NET Core usando convenções do React, do Redux e de CRA (create-react-app) para implementar uma IU
(interface do usuário) avançada do lado do cliente.
Com exceção do comando de criação de projeto, todas as informações sobre o modelo React com Redux são as
mesmas que aquelas sobre o modelo React. Para criar esse tipo de projeto, execute dotnet new reactredux em vez
de dotnet new react . Para obter mais informações sobre a funcionalidade comum para ambos os modelos
baseados em reagir, confira a Documentação do modelo React.
Usar JavaScriptServices para criar aplicativos de
única página no ASP.NET Core
Por Scott Addie e Fiyaz Hasan

Um aplicativo de página única (SPA) é um tipo popular de aplicativo web devido à sua experiência de usuário
avançada inerente. A integração do lado do cliente estruturas de SPA ou bibliotecas, como Angular ou reagir, com
estruturas do lado do servidor, como ASP.NET Core pode ser difícil. JavaScriptServices foi desenvolvido para
reduzir a fricção no processo de integração. Ele permite que a operação contínua entre o cliente diferentes e pilhas
de tecnologia do servidor.
O que é JavaScriptServices
JavaScriptServices é uma coleção de tecnologias do lado do cliente para o ASP.NET Core. Sua meta é posicionar o
ASP.NET Core como plataforma de servidor preferencial dos desenvolvedores para a criação de SPAs.
JavaScriptServices consiste em três pacotes do NuGet distintos:
Microsoft.AspNetCore.NodeServices (NodeServices)
Microsoft.AspNetCore.SpaServices (SpaServices)
Microsoft.AspNetCore.SpaTemplates (SpaTemplates)
Esses pacotes são úteis se você:
Executar o JavaScript no servidor
Usar uma estrutura de SPA ou biblioteca
Criar ativos do lado do cliente com o Webpack
O foco deste artigo é colocado sobre como usar o pacote SpaServices.
O que é SpaServices
SpaServices foi criado para posicionar o ASP.NET Core como plataforma de servidor preferencial dos
desenvolvedores para a criação de SPAs. SpaServices não é necessário para desenvolver os SPAs com o ASP.NET
Core, e ele não bloqueie você em uma estrutura de cliente específico.
SpaServices fornece infraestrutura úteis, como:
Pré-processamento do lado do servidor
Middleware de desenvolvimento webpack
Substituição do módulo quente
Auxiliares de roteamentos
Coletivamente, esses componentes de infraestrutura aprimoram o fluxo de trabalho de desenvolvimento e a
experiência de tempo de execução. Os componentes podem ser adotados individualmente.
Pré-requisitos para usar SpaServices

Para trabalhar com SpaServices, instale o seguinte:
Node. js (versão 6 ou posterior) com npm
Para verificar se esses componentes estão instalados e podem ser encontrados, execute o seguinte
na linha de comando:
node -v && npm -v
Observação: Se você estiver implantando em um site do Azure, você não precisará fazer nada aqui — Node. js está
instalado e disponível em ambientes de servidor.
Se você estiver no Windows usando o Visual Studio 2017, o SDK está instalado, selecionando o
desenvolvimento de plataforma cruzada do .NET Core carga de trabalho.
Microsoft.AspNetCore.SpaServices pacote do NuGet
Pré-processamento do lado do servidor

Um aplicativo universal de (também conhecido como isomórficos) é um aplicativo de JavaScript pode ser
executada tanto no servidor e cliente. Angular, React e outras estruturas populares fornecem uma plataforma
universal para esse estilo de desenvolvimento do aplicativo. A ideia é renderizado primeiro os componentes do
framework no servidor por meio do Node. js e delegar ainda mais a execução para o cliente.
ASP.NET Core auxiliares de marca fornecidos pelo SpaServices simplificar a implementação de pré-
processamento do lado do servidor, chamando as funções de JavaScript no servidor.
Pré -requisitos
Instale o seguinte:
ASPNET pré-processamento pacote npm:
npm i -S aspnet-prerendering
Configuração
Os auxiliares de marca são feitos podem ser descobertos por meio do registro do namespace do projeto
viewimports. cshtml arquivo:
@using SpaServicesSampleApp
@addTagHelper "*, Microsoft.AspNetCore.Mvc.TagHelpers"
@addTagHelper "*, Microsoft.AspNetCore.SpaServices"
Esses auxiliares de marcação abstraem as complexidades de se comunicar diretamente com as APIs de baixo nível,
utilizando uma sintaxe semelhante ao HTML dentro a exibição do Razor:
<app asp-prerender-module="ClientApp/dist/main-server">Loading...</app>
O asp-prerender-module auxiliar de marca

O asp-prerender-module auxiliar de marca, usado no exemplo de código anterior executa ClientApp/dist/main-
server.js no servidor por meio do Node. js. Para clareza, main-Server. js arquivo é um artefato da tarefa em que a
transcompilação TypeScript e JavaScript a Webpack processo de compilação. Webpack define um alias de ponto
de entrada de main-server ; e, passagem de grafo de dependência para este alias começa em de
ClientApp/inicialização -server.ts arquivo:
entry: { 'main-server': './ClientApp/boot-server.ts' },
No exemplo a seguir Angular, o ClientApp/inicialização -server.ts arquivo utiliza a createServerRenderer função e

RenderResult tipo do aspnet-prerendering pacote npm para configurar a renderização do servidor por meio do
Node. js. A marcação HTML destinada a renderização do lado do servidor é passada para uma chamada de função
de resolução, que é encapsulada em um JavaScript fortemente tipada Promise objeto. O Promise significância do
objeto é que ele fornece assincronamente a marcação HTML para a página para injeção no elemento de espaço
reservado do DOM.
import { createServerRenderer, RenderResult } from 'aspnet-prerendering';

const providers = [
{ provide: INITIAL_CONFIG, useValue: { document: '<app></app>', url: params.url } },
{ provide: 'ORIGIN_URL', useValue: params.origin }
];
return platformDynamicServer(providers).bootstrapModule(AppModule).then(moduleRef => {

const appRef = moduleRef.injector.get(ApplicationRef);
const state = moduleRef.injector.get(PlatformState);
const zone = moduleRef.injector.get(NgZone);
return new Promise<RenderResult>((resolve, reject) => {

zone.onError.subscribe(errorInfo => reject(errorInfo));
appRef.isStable.first(isStable => isStable).subscribe(() => {
// Because 'onStable' fires before 'onError', we have to delay slightly before
// completing the request in case there's an error to report
setImmediate(() => {
resolve({
html: state.renderToString()
});
moduleRef.destroy();
});
});
});
});
});
O asp-prerender-data auxiliar de marca

Quando combinado com o asp-prerender-module auxiliar de marca, o asp-prerender-data auxiliar de marca pode
ser usado para passar informações contextuais da exibição do Razor para o JavaScript do lado do servidor. Por
exemplo, a marcação a seguir passa os dados do usuário para o main-server módulo:
<app asp-prerender-module="ClientApp/dist/main-server"
asp-prerender-data='new {
UserName = "John Doe"
}'>Loading...</app>
Recebido argumento for serializado usando o serializador JSON interno e é armazenado no

UserName
params.data objeto. No exemplo a seguir Angular, os dados são usados para construir uma saudação
personalizada dentro de um h1 elemento:

const providers = [
];


const result = `<h1>Hello, ${params.data.userName}</h1>`;

resolve({
html: result
});
});
});
});
});
});
Observação: Os nomes de propriedade passados na auxiliares de marca são representados com PascalCase
notação. Compare isso com JavaScript, onde os mesmos nomes de propriedade são representados com
camelCase. A configuração de serialização JSON padrão é responsável por essa diferença.
Para expandir o exemplo de código anterior, dados podem ser passados do servidor para o modo de exibição por
hydrating a globals propriedade fornecida para o resolve função:

const providers = [
];


const result = `<h1>Hello, ${params.data.userName}</h1>`;

resolve({
html: result,
globals: {
postList: [
'Introduction to ASP.NET Core',
'Making apps with Angular and ASP.NET Core'
]
}
});
});
});
});
});
});
O postList matriz definida dentro de globals objeto está anexado para o navegador global window objeto. Essa
elevação de variáveis em escopo global elimina a duplicação de esforço, particularmente, pois pertence ao
carregar os mesmos dados, uma vez no servidor e novamente no cliente.
Middleware de desenvolvimento webpack

Middleware de desenvolvimento webpack introduz um fluxo de trabalho de desenvolvimento simplificado no qual
o Webpack cria recursos sob demanda. O middleware automaticamente compila e atende recursos do lado do
cliente quando uma página é recarregada no navegador. A abordagem alternativa é invocar manualmente
Webpack por meio do script de compilação do projeto npm quando uma dependência de terceiros ou o código
personalizado é alterado. Script de construção de um npm Package. JSON arquivo é mostrado no exemplo a
seguir:
"build": "npm run build:vendor && npm run build:custom",
Pré -requisitos
Instale o seguinte:
ASPNET webpack pacote npm:
npm i -D aspnet-webpack
Configuração
Webpack Dev Middleware é registrado no pipeline de solicitação HTTP por meio de código a seguir na Startup.cs
do arquivo Configure método:
O UseWebpackDevMiddleware método de extensão deve ser chamado antes Registrando a hospedagem de arquivos
estáticos por meio de UseStaticFiles método de extensão. Por motivos de segurança, registre o middleware
somente quando o aplicativo é executado no modo de desenvolvimento.
O webpack.config.js do arquivo output.publicPath propriedade informa o middleware para observar o dist
pasta para que as alterações:
module.exports = (env) => {

output: {
filename: '[name].js',
publicPath: '/dist/' // Webpack dev middleware, if enabled, handles requests for this URL prefix
},
Substituição do módulo quente

Pense do Webpack módulo de substituição a quente recurso (HMR ) como uma evolução do Webpack Dev
Middleware. HMR apresenta todos os mesmos benefícios, mas ela simplifica ainda mais o fluxo de trabalho de
desenvolvimento, atualizando automaticamente o conteúdo da página depois de compilar as alterações. Não
confunda isso com uma atualização do navegador, que poderia interferir com o estado atual de na memória e a
sessão de depuração do SPA. Há um link em tempo real entre o serviço de Middleware de desenvolvimento
Webpack e o navegador, o que significa que alterações são enviadas para o navegador.
Pré -requisitos
Instale o seguinte:
middleware hot webpack pacote npm:
npm i -D webpack-hot-middleware
Configuração
O componente HMR deve ser registrado no pipeline de solicitação HTTP do MVC no Configure método:
app.UseWebpackDevMiddleware(new WebpackDevMiddlewareOptions {
HotModuleReplacement = true
});
Como ocorria com Webpack Dev Middleware, o UseWebpackDevMiddleware método de extensão deve ser chamado
antes do UseStaticFiles método de extensão. Por motivos de segurança, registre o middleware somente quando
o aplicativo é executado no modo de desenvolvimento.
O webpack.config.js arquivo deve definir um plugins de matriz, mesmo se ela for deixada em branco:
module.exports = (env) => {

plugins: [new CheckerPlugin()]
Depois de carregar o aplicativo no navegador, a guia Console de ferramentas de desenvolvedor fornece

confirmação de ativação de HMR:
Auxiliares de roteamentos
A maioria dos SPAs com base no ASP.NET Core, você desejará roteamento do lado do cliente além do
roteamento do lado do servidor. Os sistemas de roteamento do SPA e o MVC podem trabalhar de forma
independente, sem interferência. Há, no entanto, os desafios de uma borda caso apresentando: identificando as
respostas HTTP 404.
Considere o cenário em que uma rota sem extensão de /some/page é usado. Suponha que a solicitação não-
correspondência de padrão uma rota do lado do servidor, mas seu padrão corresponde a uma rota do lado do
cliente. Agora, considere uma solicitação de entrada para /images/user-512.png , que geralmente espera encontrar
um arquivo de imagem no servidor. Se esse caminho de recurso solicitado não corresponder a qualquer rota do
lado do servidor ou um arquivo estático, é improvável que o aplicativo do lado do cliente seria lidará com isso,
você geralmente deseja retornar um código de status HTTP 404.
Pré -requisitos
Instale o seguinte:
O pacote npm de roteamento do lado do cliente. Usando Angular como um exemplo:
npm i -S @angular/router
Configuração
Um método de extensão denominado MapSpaFallbackRoute é usado no Configure método:
Dica: As rotas são avaliadas na ordem em que eles foram configurados. Consequentemente, o default rota no
exemplo de código anterior é usada primeiro para correspondência de padrões.
Criar um novo projeto

JavaScriptServices fornece modelos de aplicativos pré-configurados. SpaServices é usado nesses modelos, em
conjunto com diferentes estruturas e bibliotecas, como Angular, React e Redux.
Esses modelos podem ser instalados por meio da CLI do .NET Core, executando o seguinte comando:
dotnet new --install Microsoft.AspNetCore.SpaTemplates::*
Uma lista de modelos SPA disponíveis é exibida:
MODELOS NOME CURTO IDIOMA MARCAS
MVC ASP.NET Core com angular [C#] Web/MVC/SPA

Angular
MVC ASP.NET Core com react [C#] Web/MVC/SPA

React. js
MVC ASP.NET Core com reactredux [C#] Web/MVC/SPA

React. js e Redux
Para criar um novo projeto usando um dos modelos do SPA, inclua o nome curto do modelo na dotnet novo
comando. O comando a seguir cria um aplicativo Angular com ASP.NET Core MVC configurado para o lado do
servidor:
dotnet new angular
Definir o modo de configuração de tempo de execução

Existem dois modos de configuração de tempo de execução principal:
Desenvolvimento:
Inclui mapas de código-fonte para facilitar a depuração.
Não Otimize o código do lado do cliente para o desempenho.
Produção:
Exclui os mapas de origem.
Otimiza o código do lado do cliente por meio do agrupamento e minificação.
O ASP.NET Core usa uma variável de ambiente denominada ASPNETCORE_ENVIRONMENT para armazenar o modo de
configuração. Ver defina o ambiente para obter mais informações.
Executando com a CLI do .NET Core
Restaure os pacotes de npm e NuGet necessários, executando o seguinte comando na raiz do projeto:
dotnet restore && npm i
Compilar e executar o aplicativo:
dotnet run
O aplicativo é iniciado no localhost de acordo com o modo de configuração de tempo de execução. Navegando até
http://localhost:5000 no navegador exibe a página de aterrissagem.
Em execução com o Visual Studio 2017

Abra o . csproj arquivo gerado pelo dotnet novo comando. Os pacotes NuGet e npm necessários são restaurados
automaticamente ao projeto aberto. Esse processo de restauração pode demorar alguns minutos e o aplicativo
está pronto para ser executado quando ele for concluído. Clique no botão de execução verde ou pressione
Ctrl + F5 , e o navegador abre a página de aterrissagem do aplicativo. O aplicativo é executado no localhost de
acordo com o modo de configuração de tempo de execução.
Testar o aplicativo
Modelos SpaServices são pré-configuradas para executar testes do lado do cliente usando Karma e Jasmine.
Jasmine é uma estrutura de teste para JavaScript, de unidade popular enquanto Karma é um executor de teste
para que esses testes. Karma está configurado para funcionar com o Webpack Dev Middleware , de modo que o
desenvolvedor não é necessário parar e executar o teste sempre que forem feitas alterações. Se ele é o código em
execução no caso de teste ou caso de teste em si, o teste é executado automaticamente.
Usando o aplicativo Angular como exemplo, dois casos de teste Jasmine já são fornecidos para o
CounterComponent no counter.component.spec.ts arquivo:
it('should display a title', async(() => {

const titleText = fixture.nativeElement.querySelector('h1').textContent;
expect(titleText).toEqual('Counter');
}));
it('should start with count 0, then increments by 1 when clicked', async(() => {
const countElement = fixture.nativeElement.querySelector('strong');
expect(countElement.textContent).toEqual('0');
const incrementButton = fixture.nativeElement.querySelector('button');

incrementButton.click();
fixture.detectChanges();
expect(countElement.textContent).toEqual('1');
}));
Abra o prompt de comando de ClientApp diretório. Execute o seguinte comando:
npm test
O script inicia o executor de teste Karma, que lê as configurações definidas na karma.conf.js arquivo. Entre outras
configurações, o karma.conf.js identifica os arquivos de teste para ser executada por meio do seu files matriz:
module.exports = function (config) {
config.set({
files: [
'../../wwwroot/dist/vendor.js',
'./boot-tests.ts'
],
Publicando o aplicativo
Combinando os ativos gerados do lado do cliente e os artefatos publicados do ASP.NET Core em um pacote
pronto para implantar pode ser complicado. Felizmente, SpaServices orquestra o processo de publicação inteira
com um destino MSBuild personalizado chamado RunWebpack :
<Target Name="RunWebpack" AfterTargets="ComputeFilesToPublish">


<Exec Command="npm install" />
<Exec Command="node node_modules/webpack/bin/webpack.js --config webpack.config.vendor.js --env.prod" />
<Exec Command="node node_modules/webpack/bin/webpack.js --env.prod" />


<ItemGroup>
<DistFiles Include="wwwroot\dist\**; ClientApp\dist\**" />
<ResolvedFileToPublish Include="@(DistFiles->'%(FullPath)')" Exclude="@(ResolvedFileToPublish)">
<RelativePath>%(DistFiles.Identity)</RelativePath>
<CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
</ResolvedFileToPublish>
</ItemGroup>
</Target>
O destino do MSBuild tem as seguintes responsabilidades:

1. Restaure os pacotes de npm
2. Criar uma compilação de nível de produção dos ativos de terceiros, do lado do cliente
3. Criar uma compilação de nível de produção dos ativos do cliente personalizados
4. Copie os ativos gerados pelo Webpack para a pasta de publicação
O destino do MSBuild é chamado durante a execução:
dotnet publish -c Release
Recursos adicionais
Docs angular
Em geral, implantar um aplicativo ASP.NET Core em um ambiente de hospedagem:

Publique o aplicativo em uma pasta no servidor de hospedagem.
Configure um gerenciador de processo que inicia o aplicativo quando a solicitação chega e reinicia-o depois
que ele falha ou que o servidor é reinicializado.
Se a configuração de um proxy reverso for desejada, configure um proxy reverso que encaminha
solicitações para o aplicativo.
Publicar em uma pasta

O comando dotnet publish da CLI compila o código do aplicativo e copia os arquivos necessários para executar
o aplicativo em uma pasta publish. Ao implantar usando o Visual Studio, a etapa dotnet publish é executada
automaticamente antes de os arquivos serem copiados para o destino da implantação.
Conteúdo da pasta
A pasta publish contém arquivos .exe e .dll para o aplicativo, as respectivas dependências e, opcionalmente, o
tempo de execução do .NET.
Um aplicativo .NET Core pode ser publicado como autocontido ou dependente de estrutura. Se o aplicativo é
autocontido, os arquivos .dll que contêm o tempo de execução do .NET são incluídos na pasta publish. Se o
aplicativo depender da estrutura, os arquivos de tempo de execução do .NET não serão incluídos porque o
aplicativo tem uma referência para uma versão do .NET que está instalada no servidor. O modelo de
implantação padrão é dependente da estrutura. Para obter mais informações, consulte Implantação de
aplicativos .NET Core.
Além de arquivos .exe e .dll, a pasta publish para um aplicativo ASP.NET Core normalmente contém arquivos
de configuração, ativos estáticos e exibições do MVC. Para obter mais informações, consulte Estrutura de
diretórios.
Configure um gerenciador de processo

Um aplicativo ASP.NET Core é um aplicativo de console que deve ser iniciado quando um servidor é
inicializado e reiniciado após falhas. Para automatizar inicializações e reinicializações, um gerenciador de
processo é necessário. Os gerenciadores de processo mais comuns para o ASP.NET Core são:
Linux
Nginx
Apache
Windows
IIS
Serviço Windows
Configurar um proxy reverso

ASP.NET Core 2.x
ASP.NET Core 1.x
Se o aplicativo usar o servidor Web Kestrel, você poderá usar Nginx, Apache ou IIS como um servidor proxy
reverso. Um servidor proxy reverso recebe solicitações HTTP da Internet e as encaminha para o Kestrel após
algum tratamento preliminar.
Qualquer configuração —com ou sem um servidor proxy reverso— é uma configuração de hospedagem válida
e compatível com o ASP.NET Core 2.0 ou aplicativos posteriores. Para obter mais informações, consulte
Quando usar Kestrel com um proxy reverso.

Configuração adicional pode ser necessária para aplicativos hospedados atrás de servidores proxy e
balanceadores de carga. Sem configuração adicional, um aplicativo pode não ter acesso ao esquema
(HTTP/HTTPS ) e ao endereço IP remoto em que uma solicitação foi originada. Para obter mais informações,
veja Configurar o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga.
Usando o Visual Studio e o MSBuild para automatizar a implantação

A implantação muitas vezes requer tarefas adicionais além de copiar a saída da dotnet publish para um
servidor. Por exemplo, arquivos extras podem ser necessários ou excluídos da pasta publish. O MSBuild, que é
usado pelo Visual Studio para implantação da Web, pode ser personalizado para fazer muitas outras tarefas
durante a implantação. Para obter mais informações, consulte Perfis de publicação no Visual Studio e o livro
Usando MSBuild e o Team Foundation Build.
Você pode implantar diretamente do Visual Studio para o Serviço de Aplicativo do Azure usando o recurso
Publicar na Web ou usando o suporte ao Git interno. O Azure DevOps Services dá suporte à implantação
contínua para o Serviço de Aplicativo do Azure.
Publicação no Azure
Confira as instruções sobre como publicar um aplicativo no Azure usando o Visual Studio em Publicar um
aplicativo Web ASP.NET Core no Serviço de Aplicativo do Azure usando o Visual Studio. O aplicativo também
pode ser publicado no Azure através da linha de comando.
Hospedar em uma web farm

Para obter informações sobre a configuração para hospedar aplicativos do ASP.NET Core em um ambiente de
web farm (por exemplo, a implantação de várias instâncias do aplicativo para escalabilidade), veja Hospedar o
ASP.NET Core em um web farm.
Recursos adicionais
Para obter informações sobre como usar o Docker como um ambiente de hospedagem, consulte Hospedar
Aplicativos ASP.NET Core no Docker.
Implantar aplicativos ASP.NET Core no Serviço de
Aplicativo do Azure
Serviço de Aplicativo do Azure é um serviço de plataforma de computação em nuvem da Microsoft para

hospedar aplicativos Web, incluindo o ASP.NET Core.
Recursos úteis
A Documentação de Aplicativos Web do Azure é a página inicial para documentação de Azure Apps, tutoriais,
exemplos, guias de instruções e outros recursos. Dois tutoriais importantes que pertencem à hospedagem de
aplicativos ASP.NET Core são:
Início rápido: Criar um aplicativo Web ASP.NET Core no Azure
Use o Visual Studio para criar e implantar um aplicativo Web ASP.NET Core no Serviço de Aplicativo do Azure
no Windows.
Início rápido: Criar um aplicativo Web .NET Core no Serviço de Aplicativo no Linux
Use a linha de comando do Visual Studio para criar e implantar um aplicativo Web ASP.NET Core no Serviço
de Aplicativo do Azure no Linux.
Os artigos a seguir estão disponíveis na documentação do ASP.NET Core:
Aprenda como publicar um aplicativo ASP.NET Core no Serviço de Aplicativo do Azure usando o Visual Studio.
Implantação contínua no Azure com o Visual Studio e o GIT com o ASP.NET Core
Saiba como criar um aplicativo Web ASP.NET Core usando o Visual Studio e implantá-lo no Serviço de
Aplicativo do Azure, usando o Git para implantação contínua.
Criar seu primeiro pipeline com o Azure Pipelines
Configurar um build de CI para um aplicativo ASP.NET Core e, em seguida, criar uma versão de implantação
contínua para o Serviço de Aplicativo do Azure.
Área restrita de aplicativo Web do Azure
Descubra as limitações de tempo de execução do Serviço de Aplicativo do Azure impostas pela plataforma de
Aplicativos do Azure.
Configuração do aplicativo
Os seguintes pacotes NuGet fornecem recursos de registro em log automático para aplicativos implantados no
Serviço de Aplicativo do Azure:
O Microsoft.AspNetCore.AzureAppServices.HostingStartup usa IHostingStartup para fornecer integração
leve do ASP.NET Core com o Serviço de Aplicativo do Azure. Os recursos de registro em log adicionais são
fornecidos pelo pacote Microsoft.AspNetCore.AzureAppServicesIntegration .
Microsoft.AspNetCore.AzureAppServicesIntegration executa AddAzureWebAppDiagnostics para adicionar
provedores de log de diagnósticos do Serviço de Aplicativo do Azure no pacote
Microsoft.Extensions.Logging.AzureAppServices .
Microsoft.Extensions.Logging.AzureAppServices fornece implementações de agente para dar suporte a
recursos de streaming de log e logs de diagnóstico do Serviço de Aplicativo do Azure.
Se você estiver direcionando o .NET Core e estiver referenciando o metapacote Microsoft.AspNetCore.All, os
pacotes anteriores estarão incluídos. Os pacotes estão ausentes no metapacote Microsoft.AspNetCore.App. Se
você estiver direcionando ao .NET Framework ou referenciando ao metapacote Microsoft.AspNetCore.App ,
referencie os pacotes individuais de registro em log.
Substituir a configuração do aplicativo no Portal do Azure

A área Configurações de aplicativo da folha Configurações de aplicativo permite definir variáveis de
ambiente para o aplicativo. As variáveis de ambiente podem ser consumidas pelo Provedor de configuração de
variáveis de ambiente.
Quando uma configuração de aplicativo é criada ou modificada no Portal do Azure e o botão Salvar é
selecionado, o Aplicativo Azure é reiniciado. A variável de ambiente estará disponível para o aplicativo após o
serviço ser reiniciado.
Quando o aplicativo usa o host da Web e cria o host usando WebHost.CreateDefaultBuilder, as variáveis de
ambiente que configuram o host usam o prefixo ASPNETCORE_ . Para saber mais, confira Host da Web do
ASP.NET Core e o Provedor de configuração de variáveis de ambiente.
Quando o aplicativo usa o host genérico, as variáveis de ambiente não são carregadas na configuração do
aplicativo por padrão, e o provedor de configuração deve ser adicionado pelo desenvolvedor. O desenvolvedor
determina o prefixo da variável de ambiente quando o provedor de configuração é adicionado. Para saber mais,
confira Host Genérico .NET e o Provedor de configuração de variáveis de ambiente.

O Middleware de integração do IIS, que configura Middleware de cabeçalhos encaminhados, e o módulo do
ASP.NET Core são configurados para encaminhar o esquema (HTTP/HTTPS ) e o endereço IP remoto de onde a
solicitação foi originada. Configuração adicional pode ser necessária para aplicativos hospedados atrás de
servidores proxy adicionais e balanceadores de carga. Para obter mais informações, veja Configurar o ASP.NET
Core para trabalhar com servidores proxy e balanceadores de carga.
Monitoramento e registro em log

Para monitoramento, registro em log e informações de solução de problemas, veja os seguintes artigos:
Como: monitorar aplicativos no Serviço de Aplicativo do Azure
Saiba como examinar as cotas e métricas para aplicativos e planos do Serviço de Aplicativo.
Habilitar log de diagnósticos para aplicativos Web no Serviço de Aplicativo do Azure
Descubra como habilitar e acessar o log de diagnósticos para os códigos de status HTTP, solicitações com falha
e atividade do servidor Web.
Entenda as abordagens comuns para o tratamento de erros em aplicativos ASP.NET Core.
Saiba como diagnosticar problemas com implantações do Serviço de Aplicativo do Azure com aplicativos
ASP.NET Core.
Consulte os erros comuns de configuração de implantação para aplicativos hospedados pelo Serviço de
Aplicativo do Azure/IIS com orientação para solução de problemas.
Anel de chave de proteção de dados e slots de implantação

Chaves de proteção de dados são mantidas na pasta %HOME%\ASP.NET\DataProtection-Keys. Essa pasta é
apoiada pelo repositório de rede e é sincronizada em todos os computadores que hospedam o aplicativo. As
chaves não são protegidas em repouso. Essa pasta fornece o anel de chave para todas as instâncias de um
aplicativo em um único slot de implantação. Slots de implantação separados, como de preparo e produção, não
compartilham um anel de chave.
Quando ocorre a troca entre os slots de implantação, nenhum sistema que usa a proteção de dados consegue
descriptografar dados armazenados usando o anel de chave dentro do slot anterior. O middleware de cookie do
ASP.NET usa a proteção de dados para proteger seus cookies. Com isso, os usuários são desconectados de um
aplicativo que usa o Middleware de Cookie padrão do ASP.NET. Para uma solução de anel de chave
independente de slot, use um provedor de anel de chave externo, como:
Armazenamento do Blobs do Azure
Azure Key Vault
Repositório SQL
Cache redis
Para obter mais informações, consulte Provedores de armazenamento de chaves no ASP.NET Core.
Implantar a versão de visualização do ASP.NET Core para o Serviço

de Aplicativo do Azure
Use uma das abordagens a seguir:
Instalar a extensão de site da versão prévia.
Implantar o aplicativo autocontido.
Usar o Docker com aplicativos Web para contêineres.
Instalar a extensão de site de visualização
Se houver problemas ao usar a extensão de site de visualização, abra um problema no GitHub.
1. No portal do Azure, navegue até a folha Serviço de Aplicativo.
2. Selecione o aplicativo Web.
3. Insira "ex" na caixa de pesquisa ou role para baixo na lista de seções de gerenciamento para
FERRAMENTAS DE DESENVOLVIMENTO.
4. Selecione FERRAMENTAS DE DESENVOLVIMENTO > Extensões.
5. Selecione Adicionar.
6. Selecione a extensão de Tempo de execução do ASP.NET Core <x.y> (x86) na lista, em que <x.y> é a
versão prévia do ASP.NET Core (por exemplo, Tempo de execução do ASP.NET Core 2.2 (x86)). O
tempo de execução x86 é apropriado para implantações dependentes de estrutura que dependem de
hospedagem de fora do processo pelo Módulo do ASP.NET Core.
7. Selecione OK para aceitar os termos legais.
8. Selecione OK para instalar a extensão.
Quando a operação for concluída, a versão prévia mais recente do .NET Core será instalada. Verifique a
instalação:
1. Selecione Ferramentas Avançadas sob FERRAMENTAS DE DESENVOLVIMENTO.
2. Selecione Ir na folha Ferramentas Avançadas.
3. Selecione o item de menu Console de depuração > PowerShell.
4. No prompt do PowerShell, execute o seguinte comando. Substitua a versão de tempo de execução do
ASP.NET Core por <x.y> no comando:
Test-Path D:\home\SiteExtensions\AspNetCoreRuntime.<x.y>.x86\
Se o tempo de execução da versão prévia instalada for ASP.NET Core 2.2, o comando será:
Test-Path D:\home\SiteExtensions\AspNetCoreRuntime.2.2.x86\
O comando retornará True quando o tempo de execução da versão prévia x64 estiver instalado.
NOTE
A arquitetura da plataforma (x86/x64) de um aplicativo de Serviços de Aplicativos é definida na folha Configurações do
Aplicativo em Configurações Gerais para aplicativos que são hospedados em uma computação de série A ou em uma
melhor camada de hospedagem. Se o aplicativo for executado no modo em processo e a arquitetura da plataforma estiver
configurada para 64 bits (x64), o Módulo do ASP.NET Core usará o tempo de execução da versão prévia de 64 bits, se
estiver presente. Instalar a extensão Tempo de execução do ASP.NET Core <x.y> (x64) (por exemplo, Tempo de
execução do ASP.NET Core 2.2 (x64)).
Depois de instalar o tempo de execução da versão prévia x64, execute o seguinte comando na janela de comando do
Kudu PowerShell para verificar a instalação. Substitua a versão de tempo de execução do ASP.NET Core por <x.y> no
comando:
Test-Path D:\home\SiteExtensions\AspNetCoreRuntime.<x.y>.x64\
Se o tempo de execução da versão prévia instalada for ASP.NET Core 2.2, o comando será:
Test-Path D:\home\SiteExtensions\AspNetCoreRuntime.2.2.x64\
O comando retornará True quando o tempo de execução da versão prévia x64 estiver instalado.
NOTE
As Extensões do ASP.NET Core habilitam uma funcionalidade adicional para o ASP.NET Core nos Serviços de Aplicativo
do Azure, como a habilitação do registro em log do Azure. A extensão é instalada automaticamente durante a
implantação do Visual Studio. Se a extensão não estiver instalada, instale-a para o aplicativo.
Usar a extensão de site de visualização com um modelo do ARM

Se um modelo do ARM for usado para criar e implantar aplicativos, o tipo de recurso siteextensions poderá
ser usado para adicionar a extensão de site a um aplicativo Web. Por exemplo:
{
"type": "siteextensions",
"name": "AspNetCoreRuntime",
"apiVersion": "2015-04-01",
"location": "[resourceGroup().location]",
"properties": {
"version": "[parameters('aspnetcoreVersion')]"
},
"dependsOn": [
"[resourceId('Microsoft.Web/Sites', parameters('siteName'))]"
]
}
Implantar o aplicativo autocontido

Uma SCD (implantação autocontida) voltada para um tempo de execução de versão prévia transporta o tempo
de execução da versão prévia na implantação.
Ao implantar um aplicativo autocontido:
O site no Serviço de Aplicativo do Azure não exige a extensão de site da versão prévia.
O aplicativo precisa ser publicado após uma abordagem diferente da publicação em uma FDD (implantação
dependente de estrutura).
Publicar no Visual Studio
1. Selecione Build > Publicar {Nome do Aplicativo} na barra de ferramentas do Visual Studio.
2. Na caixa de diálogo Escolher um destino de publicação, confirme se o Serviço de Aplicativo está
selecionado.
3. Selecione Avançado. A caixa de diálogo Publicar será aberta.
4. Na caixa de diálogo Publicar:
Confirme se a configuração Versão está selecionada.
Abra a lista suspensa Modo de Implantação e selecione Autocontido.
Selecione o tempo de execução de destino na lista suspensa Tempo de Execução de Destino. O
padrão é win-x86 .
Se você precisar remover arquivos adicionais após a implantação, abra as Opções de Publicação do
Arquivo e marque a caixa de seleção para remover arquivos adicionais no destino.
Selecione Salvar.
5. Crie um novo site ou atualize um site existente seguindo as solicitações restantes do assistente de
publicação.
Publicar usando as ferramentas de CLI (interface de linha de comando)
1. No arquivo de projeto, especifique um ou mais RIDs (identificadores de tempo de execução). Use
<RuntimeIdentifier> (singular ) para um único RID ou use <RuntimeIdentifiers> (plural) para fornecer
uma lista de RIDs delimitada por ponto e vírgula. No exemplo a seguir, o RID win-x86 é especificado:
<PropertyGroup>
<RuntimeIdentifier>win-x86</RuntimeIdentifier>
</PropertyGroup>
2. Em um shell de comando, publique o aplicativo na configuração de Versão do tempo de execução do

host com o comando dotnet publish. No exemplo a seguir, o aplicativo é publicado para o RID win-x86 .
O RID fornecido para a opção --runtime precisa ser fornecida na propriedade <RuntimeIdentifier> (ou
<RuntimeIdentifiers> ) no arquivo de projeto.
dotnet publish --configuration Release --runtime win-x86
3. Mova o conteúdo do diretório bin/Release/{TARGET FRAMEWORK }/{RUNTIME IDENTIFIER }/publish

para o site no Serviço de Aplicativo.
Usar o Docker com aplicativos Web para contêineres
O Docker Hub contém as imagens de versão prévia do Docker mais recentes. As imagens podem ser usadas
como uma imagem de base. Use a imagem e implante aplicativos Web para contêineres normalmente.
Configurações de protocolo (HTTPS)

As associações de protocolo de segurança permitem que você especifique um certificado a ser usado ao
responder a solicitações em HTTPS. A associação requer um certificado privado válido ( .pfx) emitido para o
nome do host específico. Para mais informações, veja Tutorial: associar um certificado SSL personalizado
existente aos Aplicativos Web do Azure.
Recursos adicionais
Visão geral de aplicativos Web (vídeo de visão geral com 5 minutos)
Serviço de Aplicativo do Azure: o melhor lugar para hospedar seus aplicativos .NET (vídeo de visão geral
com 55 minutos)
Azure Friday: experiência de diagnóstico e solução de problemas do Serviço de Aplicativo do Azure (vídeo
com 12 minutos)
Visão geral de diagnóstico do Serviço de Aplicativo do Azure
O Serviço de Aplicativo do Azure no Windows Server usa o IIS (Serviços de Informações da Internet). Os
tópicos a seguir estão relacionados com a tecnologia subjacente do IIS:
Biblioteca Microsoft TechNet: Windows Server
Publicar um aplicativo ASP.NET Core no Azure com
o Visual Studio
Por Rick Anderson, Cesar Blum Silveira e Rachel Appel
IMPORTANT
Versões prévias do ASP.NET Core com o Serviço de Aplicativo do Azure
Versões prévias do ASP.NET Core não são implantadas para o Serviço de Aplicativo do Azure por padrão. Para hospedar
um aplicativo que usa uma versão prévia do ASP.NET Core, veja Implantar versão prévia do ASP.NET Core para o Serviço
de Aplicativo do Azure.
Confira Publicar no Azure do Visual Studio para Mac se você estiver trabalhando no macOS.
Para solucionar um problema de implantação do Serviço de Aplicativo, confira Solucionar erros de inicialização
do ASP.NET Core no Serviço de Aplicativo do Azure.
Configurar
Abra uma conta do Azure gratuita se você não tiver uma.

Na página inicial do Visual Studio, selecione Arquivo > Novo > Projeto...
Faça as configurações necessárias na caixa de diálogo Novo Projeto:

No painel esquerdo, selecione .NET Core.
No painel central, toque em Aplicativo Web ASP.NET Core.
Selecione OK.
Na caixa de diálogo Novo Aplicativo Web ASP.NET Core:

Selecione Aplicativo Web.
Selecione Mudar Autenticação.
A caixa de diálogo Mudar Autenticação é exibida.
Selecione Contas de Usuário Individuais.
Selecione OK para retornar para o Novo Aplicativo Web do ASP.NET Core, em seguida, selecione OK
novamente.
O Visual Studio cria a solução.
Pressione CTRL+F5 para executar o projeto.
Teste os links Sobre e Contato.
Registrar um usuário
Selecione Registrar e registre um novo usuário. Você pode usar um endereço de email fictício. Ao enviar,
a página exibirá o seguinte erro:
"Erro interno do servidor: uma operação de banco de dados falhou ao processar a solicitação. Exceção
SQL: não é possível abrir o banco de dados. A aplicação de migrações existentes ao contexto do BD do
Aplicativo pode resolver esse problema."
Selecione Aplicar Migrações e, depois que a página for atualizada, atualize a página.
O aplicativo exibe o email usado para registrar o novo usuário e um link Fazer logout.
Implantar o aplicativo no Azure
Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Publicar....
Na caixa de diálogo Publicar:
Selecione Serviço de Aplicativo do Microsoft Azure.
Selecione o ícone de engrenagem e, em seguida, Criar Perfil.
Selecione Criar Perfil.
Criar recursos do Azure
A caixa de diálogo Criar Serviço de Aplicativo será exibida:
Insira sua assinatura.
Os campos de entrada Nome do Aplicativo, Grupo de Recursos e Plano do Serviço de Aplicativo serão
populados. Você pode manter esses nomes ou alterá-los.
Selecione a guia Serviços para criar um novo banco de dados.
Selecione o ícone verde + para criar um novo Banco de Dados SQL
Selecione Novo... na caixa de diálogo Configurar Banco de Dados SQL para criar um novo banco de
dados.
A caixa de diálogo Configurar o SQL Server é exibida.

Insira um nome de usuário do administrador e a senha e, em seguida, selecione OK. Você pode manter o
Nome do Servidor padrão.
NOTE
“admin” não é permitido como o nome de usuário administrador.
Selecione OK.
O Visual Studio retorna para a caixa de diálogo Criar Serviço de Aplicativo.
Selecione Criar na caixa de diálogo Criar Serviço de Aplicativo.
O Visual Studio cria o aplicativo Web e o SQL Server no Azure. Esta etapa pode levar alguns minutos. Para obter
informações sobre os recursos criados, confira Recursos adicionais.
Quando a implantação for concluída, selecione Configurações:
Na página Configurações da caixa de diálogo Publicar:

Expanda Bancos de Dados e marque a opção Usar esta cadeia de conexão no tempo de execução.
Expanda Migrações do Entity Framework e marque a opção Aplicar esta migração durante a
publicação.
Selecione Salvar. O Visual Studio retorna para a caixa de diálogo Publicar.
Clique em Publicar. O Visual Studio publica seu aplicativo no Azure. Quando a implantação for concluída, o
aplicativo será aberto em um navegador.
Testar o aplicativo no Azure
Teste os links Sobre e Contato
Registrar um novo usuário
Atualizar o aplicativo
Edite a página do Razor Pages/About.cshtml e altere seu conteúdo. Por exemplo, você pode modificar o
parágrafo para indicar “Olá, ASP.NET Core!”: [!code-htmlAbout]
Clique com o botão direito do mouse no projeto e selecione Publicar... novamente.
Depois que o aplicativo for publicado, verifique se as alterações feitas estão disponíveis no Azure.
Limpar
Quando você concluir o teste do aplicativo, acesse o portal do Azure e exclua o aplicativo.
Selecione Grupos de recursos e, em seguida, selecione o grupo de recursos criado.
Na página Grupos de recursos, selecione Excluir.

Insira o nome do grupo de recursos e selecione Excluir. O aplicativo e todos os outros recursos criados neste
tutorial agora foram excluídos do Azure.
Próximas etapas
Implantação contínua no Azure com o Visual Studio e o GIT com o ASP.NET Core
Recursos adicionais
Grupo de recursos do Azure
Banco de Dados SQL do Azure
Implantação contínua no Azure com o Visual Studio
e o GIT com o ASP.NET Core
Por Erik Reitan
IMPORTANT
Versões prévias do ASP.NET Core não são implantadas para o Serviço de Aplicativo do Azure por padrão. Para hospedar um
aplicativo que usa uma versão prévia do ASP.NET Core, veja Implantar versão prévia do ASP.NET Core para o Serviço de
Aplicativo do Azure.
Este tutorial mostra como criar um aplicativo Web ASP.NET Core usando o Visual Studio e implantá-lo por meio
do Visual Studio no Serviço de Aplicativo do Azure usando a implantação contínua.
Consulte também Criar seu primeiro pipeline com o Azure Pipelines, que mostra como configurar um fluxo de
trabalho de CD (entrega contínua) para o Serviço de Aplicativo do Azure usando o Azure DevOps Services. O
Azure Pipelines (um serviço do Azure DevOps Services) simplifica a configuração de um pipeline de implantação
robusta para publicar atualizações para aplicativos hospedados no Serviço de Aplicativo do Azure. O pipeline
pode ser configurado no portal do Azure para criar, executar testes, implantar em um slot de preparo e, em
seguida, implantar na produção.
NOTE
Para concluir este tutorial, você precisa de uma conta do Microsoft Azure. Para obter uma conta, ative os benefícios do
assinante do MSDN ou inscreva-se em uma avaliação gratuita.
Pré-requisitos
Este tutorial pressupõe que o seguinte software está instalado:
Visual Studio
Git para Windows
Criar um aplicativo Web ASP.NET Core

1. Inicie o Visual Studio.
2. No menu Arquivo, selecione Novo > Projeto.
3. Selecione o modelo de projeto Aplicativo Web ASP.NET Core. Ele será exibido em Instalado >
Modelos > Visual C# > .NET Core. Nomeie o projeto SampleWebAppDemo . Selecione a opção Criar novo
repositório GIT e clique em OK.
4. Na caixa de diálogo Novo Projeto ASP.NET Core, selecione o modelo Vazio do ASP.NET Core e clique
em OK.
NOTE
A versão mais recente do .NET Core é a 2.0.
Executando o aplicativo Web localmente

1. Depois que o Visual Studio concluir a criação do aplicativo, execute o aplicativo selecionando Depurar >
Iniciar Depuração. Como alternativa, pressione F5.
Talvez seja necessário alguns instantes para inicializar o Visual Studio e o novo aplicativo. Quando isso for
concluído, o navegador mostrará o aplicativo em execução.
2. Depois de examinar o aplicativo Web em execução, feche o navegador e selecione o ícone “Parar
Depuração” na barra de ferramentas do Visual Studio para interromper o aplicativo.
Criar um aplicativo Web no Portal do Azure

As etapas a seguir criam um aplicativo Web no portal do Azure:
1. Faça logon no portal do Azure.
2. Selecione NOVO na parte superior esquerda da interface do portal.
3. Selecione Web + Celular > Aplicativo Web.
4. Na folha Aplicativo Web, insira um valor exclusivo para o Nome do Serviço de Aplicativo.
NOTE
O Nome do Serviço de Aplicativo precisa ser exclusivo. O portal impõe essa regra quando o nome é fornecido.
Se você fornecer outro valor, você precisará substituí-lo para cada ocorrência do SampleWebAppDemo neste
tutorial.
Também na folha Aplicativo Web, selecione um Plano do Serviço de Aplicativo/Localização existente

ou crie um novo. Se você criar um novo plano, selecione o tipo de preço, o local e outras opções. Para obter
mais informações sobre os planos do Serviço de Aplicativo, veja Visão geral detalhada dos planos do
Serviço de Aplicativo do Azure.
5. Selecione Criar. O Azure provisionará e iniciará o aplicativo Web.
Habilitar a publicação do Git no novo aplicativo Web
O GIT é um sistema de controle de versão distribuída que pode ser usado para implantar um aplicativo Web do
Serviço de Aplicativo do Azure. O código do aplicativo Web é armazenado em um repositório GIT local e
implantado no Azure por push para um repositório remoto.
1. Faça logon no portal do Azure.
2. Selecione Serviços de Aplicativos para exibir uma lista de serviços de aplicativos associados à assinatura
do Azure.
3. Selecione o aplicativo Web criado na seção anterior deste tutorial.
4. Na folha Implantação, selecione Opções de implantação > Escolher Origem > Repositório Git
Local.
5. Selecione OK.
6. Caso você não tenha configurado anteriormente as credenciais de implantação para publicar um aplicativo
Web ou outro aplicativo do Serviço de Aplicativo, configure-as agora:
Selecione Configurações > Credenciais de implantação. A folha Definir credenciais de
implantação é exibida.
Crie um nome de usuário e uma senha. Salve a senha para uso posterior ao configurar o GIT.
Selecione Salvar.
7. Na folha Aplicativo Web, selecione Configurações > Propriedades. A URL do repositório GIT remoto
no qual você implantará será mostrada em URL do GIT.
8. Copie o valor URL do GIT para uso posterior no tutorial.
Publicar o aplicativo Web no Serviço de Aplicativo do Azure

Nesta seção, você criará um repositório GIT local usando o Visual Studio e efetuará push desse repositório para o
Azure para implantar o aplicativo Web. As etapas envolvidas incluem as seguintes:
Adicione a configuração do repositório remoto usando o valor de URL do GIT, de modo que você possa
implantar seu repositório local no Azure.
Confirme as alterações do projeto.
Envie as alterações do projeto por push do repositório local para o repositório remoto no Azure.
1. No Gerenciador de Soluções, clique com o botão direito do mouse em “SampleWebAppDemo” da
Solução e selecione Confirmar. O Team Explorer é exibido.
2. No Team Explorer, selecione a Página Inicial (ícone da página inicial) > Configurações >
Configurações do Repositório.
3. Na seção Remotos das Configurações do Repositório, selecione Adicionar. A caixa de diálogo
Adicionar Remoto é exibida.
4. Defina o Nome do remoto como Azure-SampleApp.
5. Defina o valor de Buscar como a URL do GIT copiada do Azure anteriormente neste tutorial. Observe que
essa é a URL que termina com .git.
NOTE
Como alternativa, especifique o repositório remoto na Janela Comando abrindo a Janela Comando, alterando
para o diretório do projeto e inserindo o comando. Exemplo:
git remote add Azure-SampleApp https://me@sampleapp.scm.azurewebsites.net:443/SampleApp.git
6. Selecione a Página Inicial (ícone da página inicial) > Configurações > Configurações Globais.
Confirme se o nome e o endereço de email estão definidos. Se necessário, selecione Atualizar.
7. Selecione Página Inicial > Alterações para retornar à exibição Alterações.
8. Escreva uma mensagem de confirmação, como Push Inicial nº 1 e selecione Confirmar. Essa ação cria
uma confirmação localmente.
NOTE
Como alternativa, confirme as alterações na Janela Comando abrindo a Janela Comando, alterando para o
diretório do projeto e inserindo os comandos do GIT. Exemplo:
git add .
git commit -am "Initial Push #1"
9. Selecione Página Inicial > Sincronização > Ações > Abrir Prompt de Comando. O prompt de
comando se abre no diretório do projeto.
10. Insira o seguinte comando na janela de comando:
git push -u Azure-SampleApp master
11. Insira a senha das credenciais de implantação do Azure criada anteriormente no Azure.
Esse comando inicia o processo de envio por push dos arquivos de projeto locais para o Azure. A saída do
comando acima termina com uma mensagem informando que a implantação foi bem-sucedida.
remote: Finished successfully.

remote: Running post deployment command(s)...
remote: Deployment successful.
To https://username@samplewebappdemo01.scm.azurewebsites.net:443/SampleWebAppDemo01.git
* [new branch] master -> master
Branch master set up to track remote branch master from Azure-SampleApp.
NOTE
Se a colaboração no projeto é necessária, considere a possibilidade de enviar por push para o GitHub antes de enviar
por push para o Azure.
Verificar a implantação ativa

Verifique se a transferência do aplicativo Web do ambiente local para o Azure é bem-sucedida.
No portal do Azure, selecione o aplicativo Web. Selecione Implantação > Opções de implantação.
Executar o aplicativo no Azure

Agora que o aplicativo Web é implantado no Azure, execute o aplicativo.
Isso pode ser feito de duas maneiras:
No portal do Azure, localize a folha do aplicativo Web desse aplicativo Web. Selecione Procurar para exibir o
aplicativo no navegador padrão.
Abra um navegador e insira a URL para o aplicativo Web. Exemplo: http://SampleWebAppDemo.azurewebsites.net
Atualize o aplicativo Web e publique-o novamente

Depois de fazer alterações ao código local, republique:
1. No Gerenciador de Soluções do Visual Studio, abra o arquivo Startup.cs.
2. No método Configure , modifique o método Response.WriteAsync para que ele seja exibido da seguinte
maneira:
await context.Response.WriteAsync("Hello World! Deploy to Azure.");
3. Salve as alterações em Startup.cs.

4. No Gerenciador de Soluções, clique com o botão direito do mouse em “SampleWebAppDemo” da
Solução e selecione Confirmar. O Team Explorer é exibido.
5. Escreva uma mensagem de confirmação, tal como Update #2 .
6. Pressione o botão Confirmar para confirmar as alterações do projeto.
7. Selecione Página Inicial > Sincronização > Ações > Enviar por Push.
NOTE
Como alternativa, envie as alterações por push da Janela Comando abrindo a Janela Comando, alterando para o diretório
do projeto e inserindo um comando do GIT. Exemplo:
git push -u Azure-SampleApp master
Exibir o aplicativo Web atualizado no Azure

Exiba o aplicativo Web atualizado selecionando Procurar na folha do aplicativo Web no portal do Azure ou
abrindo um navegador e inserindo a URL do aplicativo Web. Exemplo: http://SampleWebAppDemo.azurewebsites.net
Recursos adicionais
Kudu do projeto
Solucionar problemas no ASP.NET Core no Serviço
de Aplicativo do Azure
Por Luke Latham
IMPORTANT
Este artigo fornece instruções sobre como diagnosticar um problema de inicialização do aplicativo ASP.NET
Core ao usar as ferramentas de diagnóstico do Serviço de Aplicativo do Azure. Para avisos de solução de
problemas adicionais, confira Visão geral de diagnóstico do Serviço de Aplicativo do Azure e Como monitorar
aplicativos no Serviço de Aplicativo do Azure na documentação do Azure.
Erros de inicialização do aplicativo

502.5 – Falha de Processo
O processo de trabalho falha. O aplicativo não foi iniciado.
O Módulo do ASP.NET Core tenta iniciar o processo de trabalho, mas falhar ao iniciar. Examinar o Log de
Eventos do Aplicativo geralmente ajuda a solucionar esse tipo de problema. O acesso ao log é explicado na
seção Log de Eventos do Aplicativo.
A página do erro 502.5 – Falha no Processo é retornada quando um erro de configuração do aplicativo faz com
que o processo de trabalho falhe:
500 – Erro Interno do Servidor

O aplicativo é iniciado, mas um erro impede o servidor de atender à solicitação.
Esse erro ocorre no código do aplicativo durante a inicialização ou durante a criação de uma resposta. A resposta
poderá não conter nenhum conteúdo, ou a resposta poderá ser exibida como um 500 – Erro Interno do Servidor
no navegador. O Log de Eventos do Aplicativo geralmente indica que o aplicativo iniciou normalmente. Da
perspectiva do servidor, isso está correto. O aplicativo foi iniciado, mas não é capaz de gerar uma resposta válida.
Execute o aplicativo no console do Kudu ou habilite o log de stdout do Módulo do ASP.NET Core para
solucionar o problema.
Redefinição de conexão
Se um erro ocorrer após os cabeçalhos serem enviados, será tarde demais para o servidor enviar um 500 – Erro
Interno do Servidor no caso de um erro ocorrer. Isso geralmente acontece quando ocorre um erro durante a
serialização de objetos complexos para uma resposta. Esse tipo de erro é exibida como um erro de redefinição
de conexão no cliente. O Log de aplicativo pode ajudar a solucionar esses tipos de erros.
Limites de inicialização padrão

O Módulo do ASP.NET Core está configurado com um startupTimeLimit padrão de 120 segundos. Quando
deixado no valor padrão, um aplicativo pode levar até dois minutos para iniciar antes que uma falha do processo
seja registrada em log pelo módulo. Para obter informações sobre como configurar o módulo, veja Atributos do
elemento aspNetCore.
Solucionar problemas de inicialização do aplicativo

Log de Eventos do Aplicativo
Para acessar o Log de Eventos do Aplicativo, use a folha Diagnosticar e solucionar problemas no portal do
Azure:
1. No portal do Azure, abra a folha do aplicativo na folha Serviços de Aplicativos.
2. Selecione a folha Diagnosticar e resolver problemas.
3. Em SELECIONAR CATEGORIA DE PROBLEMA, selecione o botão Aplicativo Web Inoperante.
4. Em Soluções Sugeridas, abra o painel para Abrir Logs de Eventos do Aplicativo. Selecione o botão
Abrir Log de Eventos do Aplicativo.
5. Examine o erro mais recente fornecido pelo IIS AspNetCoreModule na coluna Origem.
Uma alternativa ao uso da folha Diagnosticar e resolver problemas é examinar o arquivo de Log de Eventos
do Aplicativo diretamente usando o Kudu:
1. Selecione a folha Ferramentas Avançadas na área FERRAMENTAS DE DESENVOLVIMENTO.
Selecione o botão Ir→. O console do Kudu é aberto em uma nova janela ou guia do navegador.
2. Usando a barra de navegação na parte superior da página, abra Console de depuração e selecione CMD.
3. Abra a pasta LogFiles.
4. Selecione o ícone de lápis ao lado do arquivo eventlog.xml.
5. Examine o log. Role até o final do log para ver os eventos mais recentes.
Execute o aplicativo no console do Kudu
Muitos erros de inicialização não produzem informações úteis no Log de Eventos do Aplicativo. Você pode
executar o aplicativo no Console de Execução Remota do Kudu para descobrir o erro:
1. Selecione a folha Ferramentas Avançadas na área FERRAMENTAS DE DESENVOLVIMENTO.
Selecione o botão Ir→. O console do Kudu é aberto em uma nova janela ou guia do navegador.
3. Abra as pastas no caminho site > wwwroot.
4. No console, executando o assembly do aplicativo, execute o aplicativo propriamente dito.
Se o aplicativo for uma implantação dependente de estrutura, execute o assembly do aplicativo com
dotnet.exe. No comando a seguir, substitua o nome do assembly do aplicativo para <assembly_name> :
dotnet .\<assembly_name>.dll
Se o aplicativo for uma implantação autossuficiente, execute o arquivo executável do aplicativo. No
comando a seguir, substitua o nome do assembly do aplicativo para <assembly_name> :
<assembly_name>.exe
5. A saída do console do aplicativo, mostrando eventuais erros, é conectada ao console do Kudu.
Log de stdout do Módulo do ASP.NET Core
O log de stdout do Módulo do ASP.NET Core geralmente registra mensagens de erro úteis não encontradas no
Log de Eventos do Aplicativo. Para habilitar e exibir logs de stdout:
1. Navegue até a folha Diagnosticar e resolver problemas no portal do Azure.
2. Em SELECIONAR CATEGORIA DE PROBLEMA, selecione o botão Aplicativo Web Inoperante.
3. Em Soluções Sugeridas > Habilitar o Redirecionamento de Log de Stdout, selecione o botão para
Abrir o Console do Kudu para editar o Web.Config.
4. No Console de Diagnóstico do Kudu, abra as pastas no caminho site > wwwroot. Role para baixo para
revelar o arquivo web.config na parte inferior da lista.
5. Clique no ícone de lápis ao lado do arquivo web.config.
6. Defina stdoutLogEnabled para true e altere o caminho stdoutLogFile para \\?\%home%\LogFiles\stdout .
7. Selecione Salvar para salvar o arquivo web.config atualizado.
8. Faça uma solicitação ao aplicativo.
9. Retorne para o portal do Azure. Selecione a folha Ferramentas Avançadas na área FERRAMENTAS DE
DESENVOLVIMENTO. Selecione o botão Ir→. O console do Kudu é aberto em uma nova janela ou guia do
navegador.
11. Selecione a pasta LogFiles.
12. Inspecione a coluna Modificado em e selecione o ícone de lápis para editar o log de stdout com a data da
última modificação.
13. Quando o arquivo de log é aberto, o erro é exibido.
Importante! Desabilite o registro em log de stdout quando a solução de problemas for concluída.
1. No Console de Diagnóstico do Kudu, retorne para o caminho site > wwwroot para revelar o arquivo
web.config. Abra o arquivo web.config novamente, selecionando o ícone de lápis.
2. Defina stdoutLogEnabled para false .
3. Selecione Salvar para salvar o arquivo.
WARNING
Falha ao desabilitar o log de stdout pode levar a falhas de aplicativo ou de servidor. Não há limites para o tamanho do
arquivo de log ou para o número de arquivos de log criados. Somente use o log de stdout para solucionar problemas de
inicialização de aplicativo.
Para registro em log geral em um aplicativo ASP.NET Core após a inicialização, use uma biblioteca de registro em log que
limita o tamanho do arquivo de log e realiza a rotação de logs. Para obter mais informações, veja provedores de log de
terceiros.
Erros de inicialização comuns

Consulte Referência de erros comuns para o Serviço de Aplicativo do Azure e o IIS com o ASP.NET Core. A
maioria dos problemas comuns que impedem a inicialização do aplicativo é abordada no tópico de referência.
Aplicativo lento ou travando
Quando um aplicativo responde lentamente ou trava em uma solicitação, confira Solucionar problemas de
desempenho de aplicativo Web lento no Serviço de Aplicativo do Azure para diretrizes de depuração.
Depuração remota
Confira os seguintes tópicos:
Seção "Depuração remota de aplicativos Web" de "Solucionar problemas de um aplicativo Web no Serviço
de Aplicativo do Azure usando o Visual Studio" (documentação do Azure)
Depuração Remota do ASP.NET Core no IIS no Azure no Visual Studio 2017 (documentação do Visual
Studio)
Informações do aplicativo
O Application Insights fornece telemetria de aplicativos hospedados no Serviço de Aplicativo do Azure,
incluindo recursos de relatório e de registro de erros em log. O Application Insights só pode relatar erros
ocorridos depois que o aplicativo é iniciado quando os recursos de registro em log do aplicativo se tornam
disponíveis. Para obter mais informações, veja Application Insights para ASP.NET Core.
Folhas de monitoramento
As folhas de monitoramento fornecem uma experiência alternativa de solução de problemas para os métodos
descritos anteriormente no tópico. Essas folhas podem ser usadas para diagnosticar erros da série 500.
Verifique se as Extensões do ASP.NET Core estão instaladas. Se as extensões não estiverem instaladas, instale-
as manualmente:
1. Na seção de folha FERRAMENTAS DE DESENVOLVIMENTO, selecione a folha Extensões.
2. As Extensões do ASP.NET Core devem aparecer na lista.
3. Se as extensões não estiverem instaladas, selecione o botão Adicionar.
4. Escolha as Extensões do ASP.NET Core da lista.
5. Selecione OK para aceitar os termos legais.
6. Selecione OK na folha Adicionar extensão.
7. Uma mensagem pop-up informativa indica quando as extensões são instaladas com êxito.
Se o registro em log de stdout não estiver habilitado, siga estas etapas:
1. No portal do Azure, selecione a folha Ferramentas Avançadas na área FERRAMENTAS DE
DESENVOLVIMENTO. Selecione o botão Ir→. O console do Kudu é aberto em uma nova janela ou guia do
navegador.
3. Abra as pastas no caminho site > wwwroot e role para baixo para revelar o arquivo web.config na parte
inferior da lista.
4. Clique no ícone de lápis ao lado do arquivo web.config.
5. Defina stdoutLogEnabled para true e altere o caminho stdoutLogFile para \\?\%home%\LogFiles\stdout .
6. Selecione Salvar para salvar o arquivo web.config atualizado.
Prossiga para ativar o log de diagnóstico:
1. No portal do Azure, selecione a folha Logs de diagnóstico.
2. Selecione a opção Ligado para Log de Aplicativo (Sistema de arquivos) e Mensagens de erro
detalhadas. Selecione o botão Salvar na parte superior da folha.
3. Para incluir o rastreamento de solicitação com falha, também conhecido como FREB (Buffer de Evento de
Solicitação com Falha), selecione a opção Ligado para o Rastreamento de solicitação com falha.
4. Selecione a folha Fluxo de log, que é listada imediatamente sob a folha Logs de diagnóstico no portal.
6. Dentro dos dados de fluxo de log, a causa do erro é indicada.
Importante! Sempre desabilite o registro em log de stdout após concluir a solução de problemas. Veja as
instruções na seção log de stdout do Módulo do ASP.NET Core.
Para exibir os logs de rastreamento de solicitação com falha (logs FREB ):
1. Navegue até a folha Diagnosticar e resolver problemas no portal do Azure.
2. Selecione Logs de Rastreamento de Solicitação com Falha da área FERRAMENTAS DE SUPORTE da
barra lateral.
Confira a seção de Rastreamentos de solicitação com falha no tópico Habilitar o log de diagnósticos para
aplicativos Web no Serviço de Aplicativo do Azure e as Perguntas frequentes do desempenho do aplicativo para
Aplicativos Web no Azure: como ativar o rastreamento de solicitação com falha? para obter mais informações.
Para obter mais informações, veja Habilitar log de diagnósticos para aplicativos Web no Serviço de Aplicativo do
Azure.
WARNING
arquivo de log ou para o número de arquivos de log criados.
Para registro em log de rotina em um aplicativo ASP.NET Core, use uma biblioteca de registro em log que limita o
tamanho do arquivo de log e realiza a rotação de logs. Para obter mais informações, veja provedores de log de terceiros.
Recursos adicionais
Solucionar problemas de um aplicativo Web no Serviço de Aplicativo do Azure usando o Visual Studio
Solucionar problemas de erros HTTP de "502 – gateway incorreto" e "503 – serviço não disponível" em seus
aplicativos Web do Azure
Solucionar problemas de desempenho lento do aplicativo Web no Serviço de Aplicativo do Azure
Perguntas frequentes sobre o desempenho do aplicativo para aplicativos Web no Azure
Área restrita do aplicativo Web do Azure (limitações de execução de tempo de execução do Serviço de
Aplicativo)
Azure Friday: experiência de diagnóstico e solução de problemas do Serviço de Aplicativo do Azure (vídeo
com 12 minutos)
DevOps com ASP.NET Core e Azure
Por Cam Soper e Scott Addie

Este guia está disponível como um e-book em PDF para download.
Bem-vindo
Bem-vindo ao guia de ciclo de vida de desenvolvimento do Azure para .NET. Este guia apresenta os conceitos
básicos da criação de um ciclo de vida de desenvolvimento para o Azure usando processos e ferramentas do .NET.
Depois de concluí-lo, você aproveitará os benefícios de uma cadeia de ferramentas madura do DevOps.
A quem esse guia se destina

Você deve ser um desenvolvedor experiente do ASP.NET Core (nível 200 a 300). Você não precisa saber nada
sobre o Azure, uma vez que abordaremos isso nesta introdução. Esse guia também pode ser útil para engenheiros
de DevOps que estão mais focados nas operações do que no desenvolvimento.
Esse guia destina-se aos desenvolvedores do Windows. No entanto, Linux e macOS são totalmente compatíveis
com .NET Core. Para adaptar esse guia para Linux/macOS, fique atento a textos explicativos para diferenças do
Linux/macOS.
O que este guia não aborda

Esse guia se concentra em uma experiência de implantação contínua de ponta a ponta para desenvolvedores do
.NET. Ele não é um guia completo para tudo relacionado ao Azure e não se concentra extensivamente em APIs
.NET para serviços do Azure. A ênfase está totalmente concentrada na integração contínua, na implantação, no
monitoramento e na depuração. No final do guia, são oferecidas recomendações para as próximas etapas. Serviços
da plataforma do Azure que úteis para desenvolvedores do ASP.NET Core estão incluídos nas sugestões.
O que há neste guia

Saiba onde obter as ferramentas usadas neste guia.
Implantar no Serviço de Aplicativo
Aprenda os vários métodos para implantar um aplicativo ASP.NET Core no Serviço de Aplicativo do Azure.
Crie uma solução de implantação e integração contínua de ponta a ponta para seu aplicativo ASP.NET Core com o
GitHub, o Azure DevOps Services e o Azure.
Monitorar e depurar
Use as ferramentas do Azure para monitorar, solucionar problemas e ajustar seu aplicativo.
Próximas etapas
Outros roteiros de aprendizado para desenvolvedores do ASP.NET Core que estão aprendendo sobre o Azure.
Leitura adicional de introdução

Se esta é sua primeira experiência com a computação em nuvem, estes artigos explicam os conceitos básicos.
O que é a computação em nuvem?
Exemplos de computação em nuvem
O que é IaaS?
O que é PaaS?
O Azure tem várias interfaces para provisionamento e gerenciamento de recursos, como o portal do Azure, CLI do
Azure, Azure PowerShell, nuvem do Azure Shelle o Visual Studio. Este guia usa uma abordagem minimalista e usa
o Azure Cloud Shell sempre que possível para reduzir as etapas necessárias. No entanto, o portal do Azure deve
ser usado para algumas partes.
Pré-requisitos
As assinaturas a seguir são necessárias:
Azure — se você não tiver uma conta Obtenha uma avaliação gratuita.
Os serviços do Azure DevOps — sua assinatura de DevOps do Azure e a organização é criado no capítulo 4.
GitHub — se você não tiver uma conta Inscreva-se gratuitamente.
As ferramentas a seguir são necessárias:
Git — um entendimento fundamental do Git é recomendado para este guia. Examine os documentação do
Git, especificamente git remoto e git push.
SDK do .NET core — versão 2.1.300 ou posterior é necessário para compilar e executar o aplicativo de
exemplo. Se o Visual Studio é instalado com o desenvolvimento de plataforma cruzada do .NET Core
carga de trabalho, o SDK do .NET Core já está instalada.
Verifique se a instalação do SDK do .NET Core. Abra um shell de comando e execute o seguinte comando:
dotnet --version
Ferramentas recomendadas (somente Windows)

Visual Studiodo robustas ferramentas do Azure fornecem uma interface gráfica para a maioria das
funcionalidades descritas neste guia. Qualquer edição do Visual Studio funcionará, incluindo o Visual Studio
Community Edition gratuito. Os tutoriais são gravados para demonstrar o desenvolvimento, implantação e
operações de desenvolvimento com e sem o Visual Studio.
Confirme se o Visual Studio tem o seguinte cargas de trabalho instalado:
Desenvolvimento do ASP.NET e para a Web
Desenvolvimento do Azure
Desenvolvimento de plataforma cruzada do .NET Core
Implantar um aplicativo de serviço de aplicativo
O serviço de aplicativo do Azure é plataforma de hospedagem de web do Azure. Implantar um aplicativo web no
serviço de aplicativo do Azure pode ser feito manualmente ou por um processo automatizado. Esta seção do guia
discute métodos de implantação que podem ser disparados manualmente ou por script usando a linha de
comando ou disparada manualmente usando o Visual Studio.
Nesta seção, você vai realizar as seguintes tarefas:
Baixe e compile o aplicativo de exemplo.
Crie um aplicativo serviço de aplicativo Web usando o Azure Cloud Shell.
Implante o aplicativo de exemplo no Azure usando Git.
Implante uma alteração no aplicativo usando o Visual Studio.
Adicione um slot de preparo para o aplicativo web.
Implante uma atualização para o slot de preparo.
Troca os slots de preparo e produção.
Baixar e testar o aplicativo

O aplicativo usado neste guia é um aplicativo ASP.NET Core pré-criados simples de leitor de Feed. É um aplicativo
páginas Razor que usa o Microsoft.SyndicationFeed.ReaderWriter API para recuperar um feed RSS/Atom e exibir
os itens de notícias em uma lista.
Fique à vontade examinar o código, mas é importante entender que não há nada de especial sobre este aplicativo.
Ele é apenas um aplicativo ASP.NET Core simple para fins ilustrativos.
Em um shell de comando, baixe o código, compile o projeto e executá-lo da seguinte maneira.
Observação: Os usuários do Linux/macOS devem fazer as alterações apropriadas para caminhos, por
exemplo, usando a barra invertida ( / ) em vez de barra invertida ( \ ).
1. Clone o código para uma pasta no seu computador local.
git clone https://github.com/Azure-Samples/simple-feed-reader/
2. Alterar pasta de trabalho para o leitor de feeds simples pasta que foi criada.
cd .\simple-feed-reader\SimpleFeedReader
3. Restaure os pacotes e compile a solução.
dotnet build
4. Execute o aplicativo.
dotnet run
5. Abra um navegador e navegue até http://localhost:5000 . O aplicativo permite que você digite ou cole um
URL de feed de distribuição e exibir uma lista de itens de notícias.
6. Quando estiver satisfeito o aplicativo está funcionando corretamente, desligá-lo pressionando Ctrl+C no
shell de comando.
Criar o aplicativo Web do serviço de aplicativo do Azure

Para implantar o aplicativo, você precisará criar um serviço de aplicativo aplicativo Web. Após a criação do
aplicativo Web, você implantará a ele em seu computador local usando o Git.
1. Entrar para o Azure Cloud Shell. Observação: Quando você entra pela primeira vez, o Cloud Shell solicita a
criação de uma conta de armazenamento para arquivos de configuração. Aceite os padrões ou forneça um
nome exclusivo.
2. Use o Cloud Shell para as etapas a seguir.
a. Declare uma variável para armazenar o nome do seu aplicativo web. O nome deve ser exclusivo a ser
usado na URL padrão. Usando o $RANDOM função Bash para construir o nome garante a exclusividade e
resulta no formato webappname99999 .
webappname=mywebapp$RANDOM
b. Crie um grupo de recursos. Grupos de recursos fornecem um meio para agregar os recursos do Azure
para ser gerenciado como um grupo.
az group create --location centralus --name AzureTutorial
O az comando invoca o CLI do Azure. A CLI pode ser executada localmente, mas usá-lo no Cloud Shell
economiza tempo e configuração.
c. Crie um plano de serviço de aplicativo na camada S1. Um plano do serviço de aplicativo é um
agrupamento de aplicativos web que compartilham o mesmo tipo de preço. A camada S1 não é gratuita,
mas ela é necessária para o recurso de slots de preparo.
az appservice plan create --name $webappname --resource-group AzureTutorial --sku S1
d. Crie recurso de aplicativo web usando o plano de serviço de aplicativo no mesmo grupo de recursos.
az webapp create --name $webappname --resource-group AzureTutorial --plan $webappname
e. Defina as credenciais de implantação. Essas credenciais de implantação se aplicam a todos os aplicativos

web em sua assinatura. Não use caracteres especiais no nome do usuário.
az webapp deployment user set --user-name REPLACE_WITH_USER_NAME --password REPLACE_WITH_PASSWORD
f. Configurar o aplicativo web para aceitar as implantações do Git local e a exibição de URL de implantação
do Git. Anote essa URL para referência posterior.
echo Git deployment URL: $(az webapp deployment source config-local-git --name $webappname --resource-
group AzureTutorial --query url --output tsv)
g. Exibição de URL do aplicativo web. Navegue até essa URL para ver o aplicativo web em branco. Anote
essa URL para referência posterior.
echo Web app URL: http://$webappname.azurewebsites.net
3. Usando um shell de comando no computador local, navegue até a pasta do projeto do aplicativo web (por
exemplo, .\simple-feed-reader\SimpleFeedReader ). Execute os seguintes comandos para configurar o Git
para enviar por push para a URL de implantação:
a. Adicione a URL remota no repositório local.
git remote add azure-prod GIT_DEPLOYMENT_URL
b. Enviar por push o local mestre ramificar para o azure prod do remote mestre branch.
git push azure-prod master
Você será solicitado para as credenciais de implantação que você criou anteriormente. Observe a saída no
shell de comando. Azure cria o aplicativo ASP.NET Core remotamente.
4. Em um navegador, navegue até a URL do aplicativo Web e observe o aplicativo foi compilado e implantado.
Alterações adicionais podem ser confirmadas no repositório Git local com git commit . Essas alterações são
enviadas por push para o Azure com o anterior git push comando.
Implantação com o Visual Studio

Observação: Esta seção aplica -se ao Windows apenas. Os usuários do Linux e macOS devem fazer a alteração
descrita na etapa 2 abaixo. Salve o arquivo e confirmar a alteração no repositório local com git commit . Por
fim, envie por push a alteração com git push , como na primeira seção.
O aplicativo já foi implantado no shell de comando. Vamos usar ferramentas integradas do Visual Studio para
implantar uma atualização para o aplicativo. Nos bastidores, o Visual Studio realiza a mesma coisa, como a
ferramentas de linha de comando, mas dentro da interface de usuário familiar do Visual Studio.
1. Abra SimpleFeedReader.sln no Visual Studio.
2. No Gerenciador de soluções, abra Pages\Index.cshtml. Alteração <h2>Simple Feed Reader</h2> para
<h2>Simple Feed Reader - V2</h2> .
3. Pressione Ctrl+Shift+B para compilar o aplicativo.

4. No Gerenciador de soluções, clique com botão direito no projeto e clique em publicar.
5. Visual Studio pode criar um novo recurso do serviço de aplicativo, mas essa atualização será publicada a
implantação existente. No escolher um destino de publicação caixa de diálogo, selecione serviço de
aplicativo na lista à esquerda e, em seguida, selecione selecionar existente. Clique em Publicar.
6. No serviço de aplicativo caixa de diálogo, confirme que a Microsoft ou conta organizacional usada para
criar sua assinatura do Azure é exibida no canto superior direito. Se não estiver, clique na lista suspensa e
adicioná-lo.
7. Confirme se o Azure correto assinatura está selecionado. Para modo de exibição, selecione grupo de
recursos. Expanda o AzureTutorial grupo de recursos e, em seguida, selecione o aplicativo web existente.
Clique em OK.
Visual Studio compila e implanta o aplicativo do Azure. Navegue até a URL do aplicativo web. Validar que o <h2>
modificação do elemento está ativo.
Slots de implantação
Slots de implantação oferecer suporte a preparação de alterações sem afetar o aplicativo em execução na
produção. Depois que a versão de preparada do aplicativo é validada por uma equipe de garantia de qualidade,
slots de preparo e produção podem ser trocados. O aplicativo no ambiente de preparo é promovido para produção
dessa maneira. As etapas a seguir criar um slot de preparo, implantar algumas alterações nele e trocar o slot de
preparo em produção após a verificação.
1. Entrar para o Azure Cloud Shell, se não estiver conectado.
2. Crie o slot de preparo.
a. Criar um slot de implantação com o nome preparo.
az webapp deployment slot create --name $webappname --resource-group AzureTutorial --slot staging
b. Configurar o slot de preparo para usar a implantação do Git local e obter o preparo URL de implantação.
Anote essa URL para referência posterior.
echo Git deployment URL for staging: $(az webapp deployment source config-local-git --name $webappname -
-resource-group AzureTutorial --slot staging --query url --output tsv)
c. Exiba a URL do slot de preparo. Navegue até a URL para ver o slot de preparo vazio. Anote essa URL
para referência posterior.
echo Staging web app URL: http://$webappname-staging.azurewebsites.net
3. Em um editor de texto ou o Visual Studio, modifique Pages novamente para que o <h2> elemento lê
<h2>Simple Feed Reader - V3</h2> e salve o arquivo.
4. Confirmar o arquivo para o repositório Git local, usando o alterações página no Visual Studio Team
Explorer guia, ou digitando o seguinte usando o shell de comando do computador local:
git commit -a -m "upgraded to V3"
5. Usando o shell de comando do computador local, adicione a URL de implantação de preparo como um Git
remoto e enviar por push as alterações confirmadas:
a. Adicione a URL remota para a preparação para o repositório Git local.
git remote add azure-staging <Git_staging_deployment_URL>
b. Enviar por push o local mestre ramificar para o azure preparo do remote mestre branch.
git push azure-staging master
Aguarde enquanto o Azure cria e implanta o aplicativo.

6. Para verificar se V3 foi implantado para o slot de preparo, abra duas janelas de navegador. Em uma janela,
navegue até a URL do aplicativo web original. Em outra janela, navegue até a URL do aplicativo web
preparo. A URL de produção serve V2 do aplicativo. A URL de preparo serve V3 do aplicativo.
7. No Cloud Shell, troca o slot de preparo verificado/começando-up para produção.
az webapp deployment slot swap --name $webappname --resource-group AzureTutorial --slot staging
8. Verifique se que a troca ocorreu ao atualizar as janelas do navegador de dois.

Resumo
Nesta seção, as tarefas a seguir foram concluídas:
Baixou e compilou o aplicativo de exemplo.
Criado um aplicativo serviço de aplicativo Web usando o Azure Cloud Shell.
Implantou o aplicativo de exemplo para o Azure usando Git.
Implantada uma alteração para o aplicativo usando o Visual Studio.
Adicionado um slot de preparo para o aplicativo web.
Implantasse uma atualização para o slot de preparo.
Trocado os slots de preparo e produção.
Na próxima seção, você aprenderá a criar um pipeline de DevOps com Pipelines do Azure.
Leitura adicional
Visão geral de aplicativos Web
Criar um aplicativo web .NET Core e o banco de dados SQL no serviço de aplicativo do Azure
Configurar as credenciais de implantação do serviço de aplicativo do Azure
Configurar ambientes de preparo no serviço de aplicativo do Azure
No capítulo anterior, você criou um repositório Git local para o aplicativo de leitor de Feed simples. Neste capítulo,
você irá publicar esse código em um repositório do GitHub e construir um pipeline de serviços de DevOps do
Azure usando os Pipelines do Azure. O pipeline permite compilações contínuas e implantações do aplicativo.
Qualquer confirmação para o repositório GitHub dispara uma compilação e uma implantação em slot de preparo
do aplicativo Web do Azure.
Nesta seção, você concluirá as seguintes tarefas:
Publicar o código do aplicativo no GitHub
Desconectar-se a implantação do Git local
Criar uma organização de DevOps do Azure
Criar um projeto de equipe nos serviços de DevOps do Azure
Criar uma definição de compilação
Criar um pipeline de lançamento
Confirmar alterações no GitHub e implantar automaticamente no Azure
Examinar o pipeline de Pipelines do Azure
Publicar o código do aplicativo no GitHub

1. Abra uma janela do navegador e navegue até https://github.com .
2. Clique o + lista suspensa no cabeçalho e selecione novo repositório:
3. Selecione sua conta na proprietário lista suspensa e insira leitor de feeds simples no nome do repositório
caixa de texto.
4. Clique o criar repositório botão.
5. Abra o shell de comando do seu computador local. Navegue até o diretório no qual o leitor de feeds simples
repositório Git é armazenado.
6. Renomear existente origin remoto para upstream. Execute o seguinte comando:
git remote rename origin upstream
7. Adicione um novo origem remoto que aponta para a sua cópia do repositório no GitHub. Execute o
seguinte comando:
git remote add origin https://github.com/<GitHub_username>/simple-feed-reader/
8. Publica seu repositório Git local para o repositório GitHub recém-criado. Execute o seguinte comando:
git push -u origin master
9. Abra uma janela do navegador e navegue até https://github.com/<GitHub_username>/simple-feed-reader/ .

Valide que seu código aparece no repositório do GitHub.
Desconectar-se a implantação do Git local

Remova a implantação Git local com as etapas a seguir. Pipelines do Azure (um serviço de DevOps do Azure)
substitui e amplia essa funcionalidade.
1. Abra o portal do Azuree navegue até a de preparo (mywebapp<unique_number>/de preparo ) aplicativo
Web. O aplicativo Web pode estar localizado rapidamente digitando preparo na caixa de pesquisa do portal:
2. Clique em opções de implantação. Um novo painel é exibido. Clique em desconectar para remover a
configuração de controle de código-fonte Git local que foi adicionada no capítulo anterior. Confirme a
operação de remoção clicando o Sim botão.
3. Navegue até a mywebapp < unique_number > o serviço de aplicativo. Como lembrete, caixa de pesquisa
do portal pode ser usada para localizar rapidamente o serviço de aplicativo.
4. Clique em opções de implantação. Um novo painel é exibido. Clique em desconectar para remover a
configuração de controle de código-fonte Git local que foi adicionada no capítulo anterior. Confirme a
operação de remoção clicando o Sim botão.
Criar uma organização de DevOps do Azure

1. Abra um navegador e navegue até a página de criação de organização de DevOps do Azure.
2. Digite um nome exclusivo para o escolher um nome inesquecível textbox para formar a URL para
acessar a sua organização de DevOps do Azure.
3. Selecione o Git botão de opção, já que o código é hospedado em um repositório GitHub.
4. Clique no botão Continue (Continuar). Após uma breve espera, uma conta e um projeto de equipe,
chamado MyFirstProject, são criados.
5. Abra o email de confirmação indicando que a organização de DevOps do Azure e o projeto estão prontos
para uso. Clique o inicie seu projeto botão:
6. Um navegador é aberto <account_name>. visualstudio.com. Clique o MyFirstProject link para começar a

configurar o pipeline de DevOps do projeto.
Configurar o pipeline de Pipelines do Azure

Há três etapas distintas para ser concluída. As etapas nos resultados em um pipeline de DevOps operacional três
seções a seguir.
DevOps do Azure conceda acesso ao repositório do GitHub
1. Expanda o ou compilar o código de um repositório externo accordion. Clique o instalação compilar
botão:
2. Selecione o GitHub opção a selecionar uma fonte de seção:

3. A autorização é necessária antes de DevOps do Azure pode acessar seu repositório do GitHub. Insira <
GitHub_username > conexão do GitHub na nome de Conexão caixa de texto. Por exemplo:
4. Se a autenticação de dois fatores é ativada em sua conta do GitHub, um token de acesso pessoal é
necessário. Clique nesse caso, o autorizar com um token de acesso pessoal do GitHub link. Consulte a
instruções oficiais de criação de token de acesso pessoal do GitHub para obter ajuda. Somente o repositório
escopo das permissões é necessária. Caso contrário, clique o autorizar usando OAuth botão.
5. Quando solicitado, entre sua conta do GitHub. Em seguida, selecione a autorização para conceder acesso a
sua organização de DevOps do Azure. Se for bem-sucedido, um novo ponto de extremidade de serviço é
criado.
6. Clique no botão de reticências ao lado de repositório botão. Selecione o < GitHub_username > / leitor de
feeds simples repositório na lista. Clique o selecionar botão.
7. Selecione o mestre ramificar a branch padrão para compilações de manuais e programadas lista
suspensa. Clique no botão Continue (Continuar). Página seleção de modelo é exibido.
Criar a definição de compilação
1. Na página seleção do modelo, insira ASP.NET Core na caixa de pesquisa:
2. Os resultados da pesquisa de modelo são exibidos. Passe o mouse sobre o ASP.NET Core modelo e clique
no aplicar botão.
3. O tarefas guia da definição de compilação é exibida. Clique na guia Gatilhos .
4. Verifique as habilitar a integração contínua caixa. Sob o filtros de ramificação seção, confirme se o
tipo lista suspensa é definida como Include. Defina as especificação de Branch lista suspensa para
mestre.
Essas configurações fazem com que uma compilação disparar quando qualquer alteração é enviada por
push para o mestre branch do repositório do GitHub. Integração contínua é testada na confirmar alterações
no GitHub e implantar automaticamente para o Azure seção.
5. Clique o salvar e enfileirar botão e, em seguida, selecione o salvar opção:
6. A seguinte caixa de diálogo modal será exibida:
Usar a pasta padrão de *\*e clique no salvar botão.

Criar o pipeline de lançamento
1. Clique o versões guia de seu projeto de equipe. Clique o novo pipeline botão.
O painel de seleção de modelo é exibido.
2. Na página seleção do modelo, insira serviço de aplicativo na caixa de pesquisa:
3. Os resultados da pesquisa de modelo são exibidos. Passe o mouse sobre o implantação de serviço de
aplicativo do Azure com o Slot modelo e clique no aplicar botão. O Pipeline guia do pipeline de
lançamento é exibida.
4. Clique o Add botão na artefatos caixa. O adicionar um artefato painel é exibido:

5. Selecione o construir lado a lado do tipo de fonte seção. Esse tipo permite a vinculação do pipeline de
lançamento para a definição de compilação.
6. Selecione MyFirstProject da projeto lista suspensa.
7. Selecione o nome de definição de compilação MyFirstProject do ASP.NET Core-CI, da fonte (definição de
compilação) lista suspensa.
8. Selecione mais recente da versão padrão lista suspensa. Essa opção cria os artefatos produzidos pela
execução mais recente da definição de compilação.
9. Substitua o texto na alias de origem caixa de texto com Drop.
10. Clique no botão Adicionar. O artefatos seção será atualizado para exibir as alterações.
11. Clique no ícone de raio para habilitar implantações contínuas:
Com essa opção habilitada, uma implantação ocorre sempre que uma nova compilação está disponível.
12. Um gatilho de implantação contínua painel aparece à direita. Clique no botão de alternância para
habilitar o recurso. Não é necessário habilitar o gatilho de solicitação de Pull.
13. Clique o Add na lista suspensa a criar filtros de ramificação seção. Escolha o ramificação de padrão da
definição de compilação opção. Esse filtro faz com que a versão disparar apenas para uma compilação do
repositório do GitHub mestre branch.
14. Clique no botão Salvar. Clique o Okey botão na resultante salvar caixa de diálogo modal.
15. Clique o ambiente 1 caixa. Uma ambiente painel aparece à direita. Alterar o ambiente 1 texto na nome
do ambiente caixa de texto produção.
16. Clique o 1 fase, 2 tarefas link na produção caixa:
O tarefas guia do ambiente é exibida.

17. Clique o implantar o serviço de aplicativo do Azure ao Slot tarefa. Suas configurações aparecem em
um painel à direita.
18. Selecione a assinatura do Azure associada com o serviço de aplicativo da assinatura do Azure lista
suspensa. Depois de selecionadas, clique o autorizar botão.
19. Selecione aplicativo Web da tipo de aplicativo lista suspensa.
20. Selecione mywebapp / < unique_number / > da nome do serviço de aplicativo lista suspensa.
21. Selecione AzureTutorial da grupo de recursos lista suspensa.
22. Selecione preparo da Slot lista suspensa.
23. Clique no botão Salvar.
24. Passe o mouse sobre o nome do pipeline de versão padrão. Clique no ícone de lápis para editá-lo. Use
MyFirstProject do ASP.NET Core-CD como o nome.
25. Clique no botão Salvar.
Confirmar alterações no GitHub e implantar automaticamente no Azure

1. Abra SimpleFeedReader.sln no Visual Studio.
2. No Gerenciador de soluções, abra Pages\Index.cshtml. Alteração <h2>Simple Feed Reader - V3</h2> para
<h2>Simple Feed Reader - V4</h2> .
3. Pressione Ctrl+Shift+B para compilar o aplicativo.

4. Confirme o arquivo para o repositório GitHub. Use o alterações página no Visual Studio Team Explorer
guia ou execute o seguinte usando o shell de comando do computador local:
git commit -a -m "upgraded to V4"
5. Enviar por push a alteração na mestre ramificar para o origem remoto do seu repositório GitHub:
git push origin master
A confirmação é exibida no repositório do GitHub mestre branch:
A compilação é disparada, como integração contínua está habilitada na definição de build gatilhos guia:
6. Navegue até a enfileirado guia da Pipelines do Azure > compilações página nos serviços de DevOps
do Azure. Compilação enfileirada mostra a ramificação e confirme que disparou a compilação:
7. A compilação for bem-sucedida, ocorre uma implantação do Azure. Navegue até o aplicativo no navegador.
Observe que o texto "V4" é exibido no título:
Examinar o pipeline de Pipelines do Azure
Definição de compilação
Uma definição de compilação foi criada com o nome MyFirstProject do ASP.NET Core-CI. Após a conclusão, a
compilação produz um . zip arquivo, incluindo os ativos a serem publicadas. O pipeline de lançamento implanta
esses ativos do Azure.
A definição de compilação tarefas guia lista as etapas individuais que está sendo usadas. Há cinco tarefas de
compilação.
1. Restaure — executa o dotnet restore comando restaurar pacotes do NuGet do aplicativo. O pacote
padrão feed usado é nuget.org.
2. Crie — executa o comando para compilar o código do aplicativo. Isso
dotnet build --configuration release
--configuration opção é usada para produzir uma versão otimizada do código, que é adequado para
implantação em um ambiente de produção. Modificar a BuildConfiguration variável na definição de
compilação variáveis guia se, por exemplo, uma configuração de depuração é necessária.
3. Teste — executa o
dotnet test --configuration release --logger trx --results-directory <local_path_on_build_agent>
comando para executar testes de unidade do aplicativo. Testes de unidade são executados em qualquer
linguagem c# projeto de correspondência a **/*Tests/*.csproj padrão glob. Resultados de teste são salvos
em um trx arquivo no local especificado pelo --results-directory opção. Se qualquer teste falhar, a
compilação falhará e não será implantada.
NOTE
Para verificar se o trabalho de testes de unidade, modifique SimpleFeedReader.Tests\Services\NewsServiceTests.cs
propositadamente quebrar um dos testes. Por exemplo, altere Assert.True(result.Count > 0); à
Assert.False(result.Count > 0); no Returns_News_Stories_Given_Valid_Uri método. Confirme e envie a
alteração ao GitHub. A compilação é disparada e falha. O status do pipeline de compilação muda para falha. Reverta
a alteração, a confirmação e o envio por push novamente. A compilação for bem-sucedida.
4. Publique — executa o dotnet publish --configuration release --output <local_path_on_build_agent>

comando para produzir uma . zip arquivo com os artefatos a serem implantados. O --output opção
especifica o local de publicação do . zip arquivo. Se o local é especificado passando um variável predefinida
denominado $(build.artifactstagingdirectory) . Essa variável se expande para um caminho local, como
c:\agent_work\1\a, no agente de compilação.
5. Publicar artefato — Publishes as . zip produzido pelo arquivo o publicar tarefa. A tarefa aceita o . zip local
como um parâmetro, que é a variável predefinida do arquivo $(build.artifactstagingdirectory) . O . zip
arquivo é publicado como uma pasta chamada drop.
Clique na definição de compilação resumo link para exibir um histórico das compilações com a definição:
Na página resultante, clique no link correspondente ao número de build exclusivo:
Um resumo dessa compilação específica é exibido. Clique o artefatos guia e observe o drop produzida pela
compilação de pasta é listada:
Use o Baixe e explorar links para inspecionar os artefatos publicados.
Pipeline de lançamento
Um pipeline de lançamento foi criado com o nome MyFirstProject do ASP.NET Core-CD:
Os dois principais componentes do pipeline de lançamento são as artefatos e o ambientes. Clicando na caixa na
artefatos seção revela o seguinte painel:
O fonte (definição de compilação) valor representa a definição de compilação ao qual esse pipeline de versão
está vinculada. O . zip arquivo produzido por uma execução bem-sucedida da definição de compilação é fornecido
para o produção ambiente para implantação no Azure. Clique o 1 fase, 2 tarefas link na produção caixa do
ambiente para exibir as tarefas de pipeline de lançamento:
O pipeline de lançamento consiste em duas tarefas: implantar o serviço de aplicativo do Azure ao Slot e gerenciar
o serviço de aplicativo Azure - Slot de troca. Clicar a primeira tarefa revela a configuração de tarefa a seguir:
A assinatura do Azure, o tipo de serviço, o nome do aplicativo web, o grupo de recursos e o slot de implantação
são definidos na tarefa de implantação. O pacote ou pasta caixa de texto contém o . zip caminho do arquivo a ser
extraído e implantado para o preparo slot do mywebapp<exclusivo número> aplicativo web.
Clicar a tarefa de troca de slot revela a configuração de tarefa a seguir:
A assinatura, grupo de recursos, tipo de serviço, nome do aplicativo web e detalhes do slot de implantação são
fornecidas. O troca com produção caixa de seleção é marcada. Consequentemente, os bits implantados para o
preparo slot são trocadas no ambiente de produção.
Leitura adicional
Projeto de compilação e .NET Core
Implantar um aplicativo web com Pipelines do Azure
Monitorar e depurar
Tendo implantado o aplicativo e criado um pipeline de DevOps, é importante entender como monitorar e
solucionar problemas com o aplicativo.
Nesta seção, você concluirá as seguintes tarefas:
Localizar básicos de monitoramento e solução de problemas de dados no portal do Azure
Saiba como o Azure Monitor fornece uma análise mais profunda das métricas entre todos os serviços do Azure
Conectar o aplicativo web com o Application Insights para a criação de perfil de aplicativo
Ativar o registro em log e saiba onde baixar logs
Stream logs em tempo real
Saiba onde configurar alertas
Saiba mais sobre aplicativos de web do serviço de aplicativo do Azure depuração remotos.
Solução de problemas e monitoramento básico

Com facilidade, aplicativos web do serviço de aplicativo são monitorados em tempo real. O portal do Azure
processa as métricas em gráficos fáceis de entender e.
1. Abra o portal do Azuree, em seguida, navegue até a mywebapp<unique_number> o serviço de aplicativo.
2. O visão geral guia exibe informações úteis de "instantâneo", incluindo gráficos que exibem as métricas
recentes.
Http 5xx: contagem de erros do lado do servidor, geralmente exceções no código do ASP.NET Core.
Dados em: entrada de dados que chegam ao seu aplicativo web.
Saída de dados: dados de saída do seu aplicativo web aos clientes.
Solicitações: contagem de solicitações HTTP.
Tempo médio de resposta: o tempo médio para o aplicativo web responder às solicitações HTTP.
Várias ferramentas de autoatendimento para otimização e solução de problemas também são encontradas
nesta página.
Diagnosticar e resolver problemas é uma solução de problemas de autoatendimento.

Application Insights é para criação de perfil de desempenho e o comportamento do aplicativo e será
discutido posteriormente nesta seção.
Assistente do serviço de aplicativo faz recomendações para ajustar sua experiência de aplicativo.
Monitoramento avançado
O Azure Monitor é o serviço centralizado para todas as métricas de monitoramento e configuração de alertas em
todos os serviços do Azure. Dentro do Azure Monitor, os administradores podem controlar o desempenho
granularmente e identificar tendências. Cada serviço do Azure oferece seu próprio conjunto de métricas para o
Azure Monitor.
Perfil com o Application Insights

Application Insights é um serviço do Azure para analisar o desempenho e estabilidade de aplicativos web e como
os usuários usá-los. Os dados do Application Insights são mais amplos e aprofundados do que o Azure Monitor.
Os dados podem fornecer os desenvolvedores e administradores com informações de chave para aprimorar
aplicativos. Application Insights podem ser adicionados a um recurso de serviço de aplicativo do Azure sem
alterações de código.
1. Abra o portal do Azuree, em seguida, navegue até a mywebapp<unique_number> o serviço de aplicativo.
2. Dos visão geral , clique o Application Insights lado a lado.
3. Selecione o criar novo recurso botão de opção. Use o nome de recurso padrão e selecione o local para o
recurso Application Insights. O local não precisa corresponder ao que um aplicativo web.
4. Para tempo de execução/estrutura, selecione ASP.NET Core. Aceite as configurações padrão.

5. Selecione OK. Se solicitado a confirmar, selecione continuar.
6. Depois que o recurso tiver sido criado, clique no nome do recurso do Application Insights para navegar
diretamente até a página do Application Insights.
Como o aplicativo é usado, os dados acumulam. Selecione Refresh para recarregar a folha com novos dados.
O Application Insights fornece informações úteis do lado do servidor sem nenhuma configuração adicional. Para
obter o máximo valor do Application Insights instrumentar seu aplicativo com o SDK do Application Insights.
Quando configurado corretamente, o serviço fornece monitoramento de ponta a ponta entre o servidor web e o
navegador, incluindo desempenho do lado do cliente. Para obter mais informações, consulte o documentação do
Application Insights.
Registrando em log
Logs de servidor e aplicativo da Web estão desabilitados por padrão no serviço de aplicativo do Azure. Habilite os
logs com as seguintes etapas:
1. Abra o portal do Azuree navegue até a mywebapp<unique_number> o serviço de aplicativo.
2. No menu à esquerda, role para baixo até a monitoramento seção. Selecione logs de diagnóstico.
3. Ative log de aplicativo (Filesystem ). Se solicitado, clique na caixa para instalar as extensões para habilitar
o registro em log no aplicativo web do aplicativo.
4. Definir log do servidor Web à sistema de arquivos.
5. Insira o período de retenção em dias. Por exemplo, 30.
6. Clique em Salvar.
Logs do servidor (serviço de aplicativo) do ASP.NET Core e da web são gerados para o aplicativo web. Eles podem
ser baixados usando as informações de FTP/FTPS exibidas. A senha é o mesmo que as credenciais de implantação
criadas anteriormente neste guia. Os logs podem ser transmitido diretamente ao seu computador local com o
PowerShell ou CLI do Azure. Os logs também podem ser exibidos no Application Insights.
Streaming de log
Logs do servidor web e de aplicativo podem ser transmitidos em tempo real por meio do portal.
1. Abra o portal do Azuree navegue até a mywebapp<unique_number> o serviço de aplicativo.
2. No menu à esquerda, role para baixo até a Monitoring seção e selecione fluxo de Log.
Os logs também podem ser transmitido por meio da CLI do Azure ou o Azure PowerShell, incluindo por meio do
Cloud Shell.
Alertas
O Azure Monitor também fornece alertas em tempo real com base em métricas, eventos administrativos e outros
critérios.
Observação: No momento, alertas em métricas do aplicativo web só está disponível no serviço de alertas
(clássico ).
O alertas de serviço (clássico) pode ser encontrada no Azure Monitor ou sob o monitoramento seção das
configurações de serviço de aplicativo.
Depuração ao vivo
O serviço de aplicativo do Azure pode ser depurado remotamente com o Visual Studio quando os logs não
fornecer informações suficientes. No entanto, a depuração remota exige o aplicativo a ser compilada com símbolos
de depuração. Depuração não deve ser feita em produção, exceto como último recurso.
Conclusão
Nesta seção, você concluiu as seguintes tarefas:
Localizar básicos de monitoramento e solução de problemas de dados no portal do Azure
Saiba como o Azure Monitor fornece uma análise mais profunda das métricas entre todos os serviços do Azure
Conectar o aplicativo web com o Application Insights para a criação de perfil de aplicativo
Ativar o registro em log e saiba onde baixar logs
Stream logs em tempo real
Saiba onde configurar alertas
Saiba mais sobre aplicativos de web do serviço de aplicativo do Azure depuração remotos.
Leitura adicional
Monitorar o desempenho do aplicativo web do Azure com o Application Insights
Habilitar log de diagnósticos para aplicativos Web no Serviço de Aplicativo do Azure
Solucionar problemas de um aplicativo Web no Serviço de Aplicativo do Azure usando o Visual Studio
Criar alertas de métrica clássicos no Azure Monitor para serviços do Azure - portal do Azure
Próximas etapas
Neste guia, você criou um pipeline de DevOps para um aplicativo de exemplo do ASP.NET Core. Parabéns!
Esperamos que você tenha gostado de aprendizado publicar aplicativos web ASP.NET Core no serviço de
aplicativo do Azure e automatizar a integração contínua das alterações.
Além de hospedagem na web e DevOps, o Azure tem uma ampla gama de serviços de plataforma-como um
serviço (PaaS ) útil para desenvolvedores do ASP.NET Core. Esta seção fornece uma visão geral de alguns dos
serviços mais comumente usados.
Armazenamento e bancos de dados

Cache redis está disponível como um serviço de cache de dados de alta taxa de transferência e baixa latência. Ele
pode ser usado para armazenamento em cache de saída de página, reduzindo as solicitações de banco de dados e
fornecendo o estado de sessão do ASP.NET Core em várias instâncias de um aplicativo.
O armazenamento do Azure é armazenamento em nuvem altamente escalonável do Azure. Os desenvolvedores
podem aproveitar armazenamento de filas para enfileiramento de mensagens confiável, e armazenamento de
tabelas é um repositório de chave-valor NoSQL projetado para rápido desenvolvimento usando conjuntos de
dados grandes e semi-estruturados.
Banco de dados SQL do Azure fornece a funcionalidade de banco de dados relacional conhecida como um serviço
usando o mecanismo do Microsoft SQL Server.
O cosmos DB serviço de banco de dados NoSQL multimodelo, distribuído globalmente. Várias APIs estão
disponíveis, incluindo MongoDB, Cassandra e API do SQL (anteriormente chamado de DocumentDB ).
Identidade
O Azure Active Directory e Azure Active Directory B2C são ambos os serviços de identidade. O Azure Active
Directory foi projetado para cenários empresariais e permite a colaboração do Azure AD B2B (business-to-
business), enquanto o Azure Active Directory B2C é pretendidos cenários de negócios para o cliente, incluindo
rede social entrar.
Celular
Os Hubs de notificação é um mecanismo de notificação por push multiplataforma e dimensionável para enviar
rapidamente milhões de mensagens para aplicativos em execução em vários tipos de dispositivos.
Infraestrutura da Web
O serviço de contêiner do Azure gerencia seu ambiente Kubernetes hospedado, tornando rápido e fácil de
implantar e gerenciar aplicativos em contêineres sem conhecimento de orquestração de contêiner.
O Azure Search é usado para criar uma solução de pesquisa empresarial sobre conteúdo privada e heterogênea.
O Service Fabric é uma plataforma de sistemas distribuídos que torna mais fácil empacotar, implantar e gerenciar
escalonável e confiáveis microsserviços e contêineres.
Por Luke Latham

Instalar o pacote de hospedagem do .NET Core
Sistemas operacionais com suporte

Há suporte para os seguintes sistemas operacionais:
O servidor HTTP.sys (anteriormente chamado de WebListener) não funcionará em uma configuração de proxy
reverso com IIS. Use o servidor Kestrel.
Para obter mais informações sobre hospedagem no Azure, consulte Implantar aplicativos ASP.NET Core no
Serviço de Aplicativo do Azure.

O HTTP/2 é compatível com ASP.NET Core nos seguintes cenários de implantação de IIS:
Em processo
Fora do processo
reverso para o servidor Kestrel usa HTTP/1.1.
Estrutura de destino: não se aplica a implantações fora de processo, visto que a conexão HTTP/2 é
manipulada inteiramente pelo IIS.
Para uma implantação em processo quando uma conexão HTTP/2 for estabelecida, o HttpRequest.Protocol
relatará HTTP/2 . Para uma implantação fora de processo quando uma conexão HTTP/2 for estabelecida, o
HttpRequest.Protocol relatará HTTP/1.1 .
Para saber mais sobre os modelos de hospedagem em processo e fora de processo, confira o tópico Módulo
do ASP.NET Core e o Referência de configuração do Módulo do ASP.NET Core.
O HTTP/2 é compatível com implantações fora de processo que cumprem os seguintes requisitos básicos:
Conexões de servidor de borda voltadas para o público usam HTTP/2, mas a conexão de proxy reverso para
o servidor Kestrel usa HTTP/1.1.
Estrutura de destino: não se aplica a implantações fora de processo, visto que a conexão HTTP/2 é
manipulada inteiramente pelo IIS.
Se uma conexão HTTP/2 for estabelecida, HttpRequest.Protocol relatará HTTP/1.1 .
O HTTP/2 está habilitado por padrão. As conexões retornarão para HTTP/1.1 se uma conexão HTTP/2 não for
estabelecida. Para obter mais informações sobre a configuração de HTTP/2 com implantações do IIS, consulte
HTTP/2 no IIS.
Configuração do aplicativo
Habilitar os componentes de IISIntegration
Modelo de hospedagem em processo
Um Program.cs típico chama CreateDefaultBuilder para começar a configurar um host. CreateDefaultBuilder
chama o método UseIIS para inicializar o CoreCLR e hospedar do aplicativo no processo de trabalho do IIS (
w3wp.exe ). Os testes de desempenho indicam que hospedar um aplicativo em processo do .NET Core oferece
uma solicitação de taxa de transferência mais elevada em comparação com hospedar o aplicativo fora do
processo e enviar por proxy as solicitações para o Kestrel.
Modelo de hospedagem de fora do processo
Um Program.cs típico chama CreateDefaultBuilder para começar a configurar um host. Para a hospedagem
fora do processo com o IIS, CreateDefaultBuilder configura Kestrel como servidor Web e habilita a integração
do IIS ao configurar o caminho base e a porta para o Módulo do ASP.NET Core:

...
O Módulo do ASP.NET Core gera uma porta dinâmica a ser atribuída ao processo de back-end.
CreateDefaultBuilder chama o método UseIISIntegration. UseIISIntegration configura o Kestrel para escutar
na porta dinâmica no endereço IP do localhost ( 127.0.0.1 ). Se a porta dinâmica for 1234, o Kestrel escutará
em 127.0.0.1:1234 . Essa configuração substitui outras configurações de URL fornecidas por:
UseUrls
API de escuta do Kestrel
Configuração (ou opção --urls de linha de comando)
As chamadas a UseUrls ou à API Listen do Kestrel não são necessárias ao usar o módulo. Se UseUrls ou
Listen for chamado, o Kestrel escutará nas portas especificadas somente durante a execução do aplicativo
sem o IIS.
Para saber mais sobre os modelos de hospedagem em processo e fora de processo, confira o tópico Módulo
do ASP.NET Core e o Referência de configuração do Módulo do ASP.NET Core.
configura Kestrel como o servidor Web e habilita a integração IIS configurando o caminho base e a porta para
o módulo do ASP.NET Core:

...
na porta dinâmica no endereço IP do localhost ( 127.0.0.1 ). Se a porta dinâmica for 1234, o Kestrel escutará
em 127.0.0.1:1234 . Essa configuração substitui outras configurações de URL fornecidas por:
UseUrls
Listen for chamado, o Kestrel escutará na porta especificada somente durante a execução do aplicativo sem o
IIS.
configura Kestrel como o servidor Web e habilita a integração IIS configurando o caminho base e a porta para
o módulo do ASP.NET Core:

...
na porta dinâmica no endereço IP do localhost ( localhost ). Se a porta dinâmica for 1234, o Kestrel escutará
em localhost:1234 . Essa configuração substitui outras configurações de URL fornecidas por:
UseUrls
Listen for chamado, o Kestrel escutará na porta especificada somente durante a execução do aplicativo sem o
IIS.
Inclua uma dependência no pacote Microsoft.AspNetCore.Server.IISIntegration nas dependências do
aplicativo. Use o middleware Integração do IIS adicionando o método de extensão UseIISIntegration ao
WebHostBuilder:

.UseKestrel()
...
UseKestrel e UseIISIntegration são necessários. A chamada do código a UseIISIntegration não afeta a

portabilidade do código. Se o aplicativo não é executado por trás do IIS (por exemplo, o aplicativo é executado
diretamente em Kestrel), UseIISIntegration não opera.
UseIISIntegration configura o Kestrel para escutar na porta dinâmica no endereço IP do localhost ( localhost
). Se a porta dinâmica for 1234, o Kestrel escutará em localhost:1234 . Essa configuração substitui outras
configurações de URL fornecidas por:
UseUrls
Uma chamada a UseUrls não é necessária ao usar o módulo. Se UseUrls for chamado, o Kestrel escutará na
porta especificada somente durante a execução do aplicativo sem o IIS.
Se UseUrlsfor chamado em um aplicativo do ASP.NET Core 1.0, chame-o antes de chamar
UseIISIntegration para que a porta configurada pelo módulo não seja substituída. Essa ordem de chamada
não é necessária com o ASP.NET Core 1.1, porque a configuração do módulo substitui UseUrls .
Para saber mais sobre hospedagem, confira Host no ASP.NET Core.
Opções do IIS
Para configurar opções de IIS, inclua uma configuração de serviço para IISOptions em ConfigureServices. No
exemplo a seguir, o encaminhamento de certificados do cliente para o aplicativo para preencher
HttpContext.Connection.ClientCertificate está desabilitado:
services.Configure<IISOptions>(options =>
{
options.ForwardClientCertificate = false;
});
OPÇÃO PADRÃO CONFIGURAÇÃO
AutomaticAuthentication true Se true , o middleware de integração

do IIS define o HttpContext.User
autenticado pela Autenticação do
Windows. Se false , o middleware
fornecerá apenas uma identidade para
HttpContext.User e responderá a
desafios quando explicitamente
solicitado pelo
AuthenticationScheme . A
autenticação do Windows deve estar
habilitada no IIS para que o
AutomaticAuthentication funcione.
Saiba mais no tópico Autenticação do
Windows.
AuthenticationDisplayName null Configura o nome de exibição

mostrado aos usuários em páginas de
logon.
ForwardClientCertificate true Se true e o cabeçalho da solicitação

MS-ASPNETCORE-CLIENTCERT
estiverem presentes, o
HttpContext.Connection.ClientCertificate
será populado.

O Middleware de integração do IIS, que configura Middleware de cabeçalhos encaminhados, e o módulo do
ASP.NET Core são configurados para encaminhar o esquema (HTTP/HTTPS ) e o endereço IP remoto de onde
a solicitação foi originada. Configuração adicional pode ser necessária para aplicativos hospedados atrás de
servidores proxy adicionais e balanceadores de carga. Para obter mais informações, veja Configurar o
ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga.
Arquivo web.config
O arquivo web.config configura o Módulo do ASP.NET Core. Criando, transformar e publicar o arquivo
Web.config é tratado por um destino do MSBuild ( _TransformWebConfig ) quando o projeto é publicado. Este
destino está presente nos destinos do SDK da Web ( Microsoft.NET.Sdk.Web ). O SDK é definido na parte
superior do arquivo de projeto:
Se um arquivo web.config não estiver presente no projeto, ele será criado com o processPath e os argumentos
corretos para configurar o Módulo do ASP.NET Core e será transferido para o resultado publicado.
Se um arquivo web.config estiver presente no projeto, ele será transformado com o processPath e os
argumentos corretos para configurar o Módulo do ASP.NET Core e será movido para o resultado publicado. A
transformação não altera as definições de configuração do IIS no arquivo.
O arquivo web.config pode fornecer configurações adicionais do IIS que controlam módulos ativos do IIS. Para
saber mais sobre os módulos do IIS que podem processar solicitações com aplicativos do ASP.NET Core, veja
o tópico Módulos do IIS.
Para impedir que o SDK Web transforme o arquivo web.config, use a propriedade
<IsTransformWebConfigDisabled> no arquivo do projeto:
<PropertyGroup>
<IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>
Ao impedir que o SDK Web transforme o arquivo, o processPath e os argumentos devem ser definidos
manualmente pelo desenvolvedor. Para obter mais informações, consulte Referência de configuração do
módulo do ASP.NET Core.
Local do arquivo web.config
Para criar um proxy reverso entre o IIS e o servidor Kestrel, o arquivo web.config deve estar presente no
caminho raiz do conteúdo (geralmente, o caminho base do aplicativo) do aplicativo implantado. Esse é o
mesmo local que o caminho físico do site fornecido ao IIS. O arquivo web.config é necessário na raiz do
aplicativo para habilitar a publicação de vários aplicativos usando a Implantação da Web.
Existem arquivos confidenciais no caminho físico do aplicativo, como <assembly>.runtimeconfig.json,
<assembly>.xml (comentários da Documentação XML ) e <assembly>.deps.json. Quando o arquivo web.config
estiver presente e o site for iniciado normalmente, o IIS não servirá esses arquivos confidenciais se eles forem
solicitados. Se o arquivo web.config estiver ausente, nomeado incorretamente ou se não for possível configurar
o site para inicialização normal, o IIS poderá servir arquivos confidenciais publicamente.
O arquivo web.config deve estar presente na implantação em todos os momentos, nomeado
corretamente e ser capaz de configurar o site para inicialização normal. Nunca remova o arquivo
web.config de uma implantação de produção.
Configuração do IIS
Sistemas operacionais do Windows Server
Habilite a função Servidor Web (IIS ) e estabeleça serviços de função.
1. Use o assistente Adicionar Funções e Recursos por meio do menu Gerenciar ou do link no
Gerenciador do Servidor. Na etapa Funções de Servidor, marque a caixa de Servidor Web (IIS ).
2. Após a etapa Recursos, a etapa Serviços de função é carregada para o servidor Web (IIS ). Selecione
os serviços de função do IIS desejados ou aceite os serviços de função padrão fornecidos.
Autenticação do Windows (opcional)

Para habilitar a Autenticação do Windows, expanda os nós a seguir: Servidor Web > Segurança.
Selecione o recurso Autenticação do Windows. Saiba mais em Autenticação do Windows
<windowsAuthentication> e Configurar autenticação do Windows.
WebSockets (opcional)
O WebSockets é compatível com o ASP.NET Core 1.1 ou posterior. Para habilitar o WebSockets,
expanda os nós a seguir: Servidor Web > Desenvolvimento de Aplicativos. Selecione o recurso
Protocolo WebSocket. Para obter mais informações, consulte WebSockets.
3. Continue para a etapa Confirmação para instalar os serviços e a função de servidor Web. Um
comando server/IIS restart não será necessário após a instalação da função Servidor Web (IIS ).
Sistemas operacionais Windows de área de trabalho
Habilite o Console de Gerenciamento do IIS e os Serviços na World Wide Web.
1. Navegue para Painel de Controle > Programas > Programas e Recursos > Ativar ou desativar
recursos do Windows (lado esquerdo da tela).
2. Abra o nó Serviços de Informações da Internet. Abra o nó Ferramentas de Gerenciamento da
Web.
3. Marque a caixa de Console de Gerenciamento do IIS.
4. Marque a caixa de Serviços na World Wide Web.
5. Aceite os recursos padrão dos Serviços na World Wide Web ou personalize os recursos do IIS.
Autenticação do Windows (opcional)
Para habilitar a Autenticação do Windows, expanda os nós a seguir: Serviços World Wide Web >
Segurança. Selecione o recurso Autenticação do Windows. Saiba mais em Autenticação do
Windows <windowsAuthentication> e Configurar autenticação do Windows.
WebSockets (opcional)
O WebSockets é compatível com o ASP.NET Core 1.1 ou posterior. Para habilitar o WebSockets,
expanda os nós a seguir: Serviços World Wide Web > Recursos de Desenvolvimento de
Aplicativos. Selecione o recurso Protocolo WebSocket. Para obter mais informações, consulte
WebSockets.
6. Se a instalação do IIS exigir uma reinicialização, reinicie o sistema.
Instalar o pacote de hospedagem do .NET Core

Instale o pacote de hospedagem do .NET Core no sistema de hospedagem. O pacote instala o Tempo de
Execução .NET Core, a Biblioteca do .NET Core e o Módulo do ASP.NET Core. O módulo cria o proxy reverso
entre o IIS e o servidor Kestrel. Se o sistema não tiver uma conexão com a Internet, obtenha e instale os
Pacotes redistribuíveis do Microsoft Visual C++ 2015 antes de instalar o pacote de hospedagem do .NET Core.
IMPORTANT
Se o pacote de hospedagem for instalado antes do IIS, a instalação do pacote deverá ser reparada. Execute o instalador
do pacote de hospedagem novamente depois de instalar o IIS.
Download direto (versão atual)

Baixe o instalador usando o seguinte link:
Instalador de pacote de hospedagem do .NET Core atual (download direto)
Versões anteriores do instalador
Para obter uma versão anterior do instalador:
1. Navegue até os arquivos de downloads do .NET.
2. Em .NET Core, selecione a versão do .NET Core.
3. Na coluna Executar aplicativos – Tempo de execução, localize a linha da versão de tempo de execução
do .NET Core desejada.
4. Baixe o instalador usando o link Pacote de hospedagem e de tempo de execução.
WARNING
Alguns instaladores contêm versões de lançamento que atingiram o EOL (fim da vida útil) e não têm mais suporte da
Microsoft. Para saber mais, confira a política de suporte.
Instalar o pacote de hospedagem

1. Execute o instalador no servidor. As seguintes opções estão disponíveis ao executar o instalador em um
prompt de comando do administrador:
OPT_NO_ANCM=1 – Ignorar a instalação do Módulo do ASP.NET Core.
OPT_NO_RUNTIME=1 – Ignorar a instalação do tempo de execução do .NET Core.
OPT_NO_SHAREDFX=1 – Ignorar a instalação da Estrutura Compartilhada do ASP.NET (tempo de
execução do ASP.NET).
OPT_NO_X86=1 – Ignorar a instalação dos tempos de execução x86. Use essa opção quando você sabe
que não hospedará aplicativos de 32 bits. Se houver uma possibilidade de hospedar aplicativos de 32
bits e 64 bits no futuro, não use essa opção e instale ambos os tempos de execução.
2. Reinicie o sistema ou execute net stop was /y seguido por net start w3svc em um prompt de
comando. A reinicialização do IIS identifica uma alteração no CAMINHO do sistema, que é uma variável
de ambiente, realizada pelo instalador.
Se o instalador do Pacote de Hospedagem do Windows detectar que o IIS requer uma reinicialização para
concluir a instalação, o instalador reiniciará o IIS. Se o instalador disparar uma reinicialização do IIS, todos os
pools de aplicativos do IIS e sites serão reiniciados.
NOTE
Para obter informações sobre a Configuração Compartilhada do IIS, consulte Módulo do ASP.NET Core com a
Configuração Compartilhada do IIS.
Instalar a Implantação da Web durante a publicação com o Visual
Studio
Ao implantar aplicativos para servidores com Implantação da Web, instale a versão mais recente da
Implantação da Web no servidor. Para instalar a Implantação da Web, use o WebPI (Web Platform Installer) ou
obtenha um instalador diretamente no Centro de Download da Microsoft. O método preferencial é usar o
WebPI. O WebPI oferece uma instalação autônoma e uma configuração para provedores de hospedagem.
Criar o site do IIS

1. No sistema de hospedagem, crie uma pasta para conter arquivos e pastas publicados do aplicativo. O
layout de implantação do aplicativo é descrito no tópico Estrutura de Diretórios.
2. Na nova pasta, crie uma pasta logs para armazenar os logs do stdout do Módulo do ASP.NET Core
quando o log do stdout estiver habilitado. Se o aplicativo for implantado com uma pasta logs no
conteúdo, ignore esta etapa. Para obter instruções sobre como habilitar o MSBuild para criar a pasta
logs automaticamente quando o projeto for criado localmente, veja o tópico Estrutura de Diretórios.
IMPORTANT
Somente use o log do stdout para solucionar problemas de falhas de inicialização de aplicativo. Nunca use o log
do stdout para registrar aplicativos de rotina. Não há limites para o tamanho do arquivo de log ou para o
número de arquivos de log criados. O pool de aplicativos deve ter acesso de gravação ao local em que os logs
foram gravados. Todas as pastas no caminho para a localização do log devem existir. Para saber mais sobre o log
do stdout, veja Criação e redirecionamento de logs. Para saber mais sobre o registro em um aplicativo do
ASP.NET Core, veja o tópico Registrar.
3. No Gerenciador do IIS, abra o nó do servidor no painel Conexões. Clique com botão direito do
mouse na pasta Sites. Selecione Adicionar Site no menu contextual.
4. Forneça um Nome do site e defina o Caminho físico como a pasta de implantação do aplicativo.
Forneça a configuração Associação e crie o site ao selecionar OK:
WARNING
Associações de curinga de nível superior ( http://*:80/ e http://+:80 ) não devem ser usadas. Associações
de curinga de nível superior podem abrir o aplicativo para vulnerabilidades de segurança. Isso se aplica a curingas
fortes e fracos. Use nomes de host explícitos em vez de curingas. Associações de curinga de subdomínio (por
exemplo, *.mysub.com ) não têm esse risco de segurança se você controlar o domínio pai completo (em vez de
*.com , o qual é vulnerável). Veja rfc7230 section-5.4 para obter mais informações.
5. No nó do servidor, selecione Pools de Aplicativos.

6. Clique com o botão direito do mouse no pool de aplicativos do site e selecione Configurações Básicas
no menu contextual.
7. Na janela Editar Pool de Aplicativos, defina a versão do CLR do .NET como Sem Código
Gerenciado:
O ASP.NET Core é executado em um processo separado e gerencia o tempo de execução. O ASP.NET

Core não depende do carregamento do CLR de área de trabalho. Definir a versão do CLR do .NET
como Sem Código Gerenciado é opcional.
8. Confirme se a identidade do modelo de processo tem as permissões apropriadas.
Se você alterar a identidade padrão do pool de aplicativos (Modelo de Processo > Identidade) em
ApplicationPoolIdentity para outra, verifique se a nova identidade tem as permissões necessárias
para acessar a pasta do aplicativo, o banco de dados e outros recursos necessários. Por exemplo, o pool
de aplicativos requer acesso de leitura e gravação às pastas nas quais o aplicativo lê e grava os arquivos.
Configuração de Autenticação do Windows (opcional)
Para saber mais, veja Configurar a Autenticação do Windows.
Implantar o aplicativo
Implante o aplicativo na pasta criada no sistema de hospedagem. A Implantação da Web é o mecanismo
recomendado para implantação.
Implantação da Web com o Visual Studio
Consulte o tópico Perfis de publicação do Visual Studio para implantação de aplicativos ASP.NET Core para
saber como criar um perfil de publicação para uso com a Implantação da Web. Se o provedor de hospedagem
fornecer um Perfil de Publicação ou o suporte para a criação de um, baixe o perfil e importe-o usando a caixa
de diálogo Publicar do Visual Studio.
Implantação da Web fora do Visual Studio

Também é possível usar a Implantação da Web fora do Visual Studio na linha de comando. Para obter mais
informações, consulte Ferramenta de Implantação da Web.
Alternativas à Implantação da Web
Use qualquer um dos vários métodos para mover o aplicativo para o sistema host, como cópia manual, Xcopy,
Robocopy ou PowerShell.
Para obter mais informações sobre a implantação do ASP.NET Core no IIS, consulte a seção Recursos de
implantação para administradores do IIS.
Navegar no site
Arquivos de implantação bloqueados
Os arquivos na pasta de implantação são bloqueados quando o aplicativo está em execução. Os arquivos
bloqueados não podem ser substituídos durante a implantação. Para liberar os arquivos bloqueados em uma
implantação, interrompa o pool de aplicativos usando uma das abordagens a seguir:
Use a Implantação da Web e referencie Microsoft.NET.Sdk.Web no arquivo do projeto. Um arquivo
app_offline.htm é colocado na raiz do diretório de aplicativo da Web. Quando o arquivo estiver presente,
o módulo do ASP.NET Core apenas desligará o aplicativo e servirá o arquivo app_offline.htm durante a
implantação. Para obter mais informações, consulte Referência de configuração do módulo do ASP.NET
Core.
Manualmente interrompa o pool de aplicativos no Gerenciador do IIS no servidor.
Use o PowerShell para interromper e reiniciar o pool de aplicativos (requer o PowerShell 5 ou
posterior):
$webAppPoolName = 'APP_POOL_NAME'
# Stop the AppPool

if((Get-WebAppPoolState $webAppPoolName).Value -ne 'Stopped') {
Stop-WebAppPool -Name $webAppPoolName
while((Get-WebAppPoolState $webAppPoolName).Value -ne 'Stopped') {
Start-Sleep -s 1
}
Write-Host `-AppPool Stopped
}
# Provide script commands here to deploy the app
# Restart the AppPool

if((Get-WebAppPoolState $webAppPoolName).Value -ne 'Started') {
Start-WebAppPool -Name $webAppPoolName
while((Get-WebAppPoolState $webAppPoolName).Value -ne 'Started') {
Start-Sleep -s 1
}
Write-Host `-AppPool Started
}
Proteção de dados
A pilha Proteção de Dados do ASP.NET Core é usada por vários middlewares ASP.NET Core, incluindo
aqueles usados na autenticação. Mesmo se as APIs de proteção de dados não forem chamadas pelo código do
usuário, a proteção de dados deverá ser configurada com um script de implantação ou no código do usuário
para criar um repositório de chaves criptográfico persistente. Se a proteção de dados não estiver configurada,
as chaves serão mantidas na memória e descartadas quando o aplicativo for reiniciado.
Se o token de autenticação for armazenado na memória quando o aplicativo for reiniciado:
Todos os tokens de autenticação baseados em cookies serão invalidados.
Os usuários precisam entrar novamente na próxima solicitação deles.
Todos os dados protegidos com o token de autenticação não poderão mais ser descriptografados. Isso pode
incluir os tokens CSRF e cookies TempData do MVC do ASP.NET Core.
Para configurar a proteção de dados no IIS para persistir o token de autenticação, use uma das seguintes
abordagens:
Criar chaves de registro de proteção de dados
As chaves de proteção de dados usadas pelos aplicativos ASP.NET Core são armazenadas no registro
externo aos aplicativos. Para persistir as chaves de determinado aplicativo, crie uma chave de registro
para o pool de aplicativos.
Para instalações autônomas do IIS não Web Farm, você pode usar o script Provision-AutoGenKeys.ps1
de Proteção de Dados do PowerShell para cada pool de aplicativos usado com um aplicativo ASP.NET
Core. Esse script cria uma chave de registro no registro HKLM que é acessível apenas para a conta do
processo de trabalho do pool de aplicativos do aplicativo. As chaves são criptografadas em repouso
usando a DPAPI com uma chave para todo o computador.
Em cenários de web farm, um aplicativo pode ser configurado para usar um caminho UNC para
armazenar seu token de autenticação de proteção de dados. Por padrão, as chaves de proteção de dados
não são criptografadas. Garanta que as permissões de arquivo de o compartilhamento de rede sejam
limitadas à conta do Windows na qual o aplicativo é executado. Um certificado X509 pode ser usado
para proteger chaves em repouso. Considere um mecanismo para permitir aos usuários carregar
certificados: coloque os certificados no repositório de certificados confiáveis do usuário e certifique-se
de que eles estejam disponíveis em todos os computadores nos quais o aplicativo do usuário é
executado. Veja Configurar a proteção de dados do ASP.NET Core para obter detalhes.
Configurar o pool de aplicativos do IIS para carregar o perfil do usuário
Essa configuração está na seção Modelo de processo nas Configurações avançadas do pool de
aplicativos. Defina Carregar perfil do usuário como True . Isso armazena as chaves no diretório do perfil
do usuário e as protege usando a DPAPI com uma chave específica à conta de usuário usada pelo pool
de aplicativos.
Use o sistema de arquivos como um repositório de tokens de autenticação
Ajuste o código do aplicativo para usar o sistema de arquivos como um repositório de tokens de
autenticação. Use um certificado X509 para proteger o token de autenticação e verifique se ele é um
certificado confiável. Se o certificado for autoassinado, você deverá colocá-lo no repositório Raiz
confiável.
Ao usar o IIS em uma web farm:
Use um compartilhamento de arquivos que pode ser acessado por todos os computadores.
Implante um certificado X509 em cada computador. Configure a proteção de dados no código.
Definir uma política para todo o computador para proteção de dados
O sistema de proteção de dados tem suporte limitado para a configuração da política de todo o
computador padrão para todos os aplicativos que consomem as APIs de proteção de dados. Para obter
mais informações, consulte Proteção de dados do ASP.NET Core.
Configuração de subaplicativos
Os subaplicativos adicionados no aplicativo raiz não devem incluir o Módulo do ASP.NET Core como um
manipulador. Se o módulo for adicionado como um manipulador em um arquivo web.config de um
subaplicativo, quando tentar procurar o subaplicativo, você receberá um 500.19 Erro Interno do Servidor que
referenciará o arquivo de configuração com falha.
O seguinte exemplo mostra um arquivo web.config publicado de um subaplicativo ASP.NET Core:
<?xml version="1.0" encoding="utf-8"?>

<configuration>
<system.webServer>
<aspNetCore processPath="dotnet"
arguments=".\<assembly_name>.dll"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout" />
</system.webServer>
</configuration>
Ao hospedar um subaplicativo não ASP.NET Core abaixo de um aplicativo ASP.NET Core, remova
explicitamente o manipulador herdado no arquivo web.config do subaplicativo:
<configuration>
<system.webServer>
<handlers>
<remove name="aspNetCore" />
</handlers>
arguments=".\<assembly_name>.dll"
</system.webServer>
</configuration>
Para obter mais informações sobre como configurar o Módulo do ASP.NET Core, consulte o tópico Introdução
ao Módulo do ASP.NET Core e a Referência de configuração do Módulo do ASP.NET Core.
Configuração do IIS com web.config

A configuração do IIS é influenciada pela seção <system.webServer> de web.config para os recursos do IIS
que se aplicam a uma configuração de proxy reverso. Se o IIS é configurado no nível do servidor para usar a
compactação dinâmica, o elemento <urlCompression> no arquivo web.config do aplicativo pode desabilitá-
la.
Para saber mais, veja a referência de configuração do <system.webServer>, a referência de configuração do
Módulo do ASP.NET Core e Módulos do IIS com o ASP.NET Core. Para definir variáveis de ambiente para
aplicativos individuais executados em pools de aplicativos isolados (compatível com o IIS 10.0+ ou posterior),
veja a seção comando AppCmd.exe do tópico Variáveis de ambiente <environmentVariables> na
documentação de referência do IIS.
Seções de configuração de web.config

As seções de configuração de aplicativos ASP.NET 4.x em web.config não são usadas por aplicativos ASP.NET
Core para configuração:
<system.web>
<appSettings>
<connectionStrings>
<location>
Aplicativos ASP.NET Core são configurados para usar outros provedores de configuração. Para obter mais
informações, consulte Configuração.
Pools de aplicativos
Ao hospedar vários sites em um servidor, é recomendável isolar os aplicativos uns dos outros, executando cada
aplicativo em seu próprio pool de aplicativo. A caixa de diálogo Adicionar Site do IIS usa como padrão essa
configuração. Quando você fornece um Nome do site, o texto é transferido automaticamente para a caixa de
texto Pool de aplicativos. Um novo pool de aplicativos é criado usando o nome do site quando você
adicionar o site.
Identidade do pool de aplicativos

Uma conta de identidade do pool de aplicativos permite executar um aplicativo em uma conta exclusiva sem a
necessidade de criar e gerenciar domínios ou contas locais. No IIS 8.0 ou posterior, o WAS (Processo de
trabalho do administrador) do IIS cria uma conta virtual com o nome do novo pool de aplicativos e executa os
processos de trabalho do pool de aplicativos nesta conta por padrão. No Console de Gerenciamento do IIS, em
Configurações avançadas do pool de aplicativos, verifique se a Identidade é definida para usar
ApplicationPoolIdentity:
O processo de gerenciamento do IIS cria um identificador seguro com o nome do pool de aplicativos no
Sistema de segurança do Windows. Os recursos podem ser protegidos usando essa identidade. No entanto,
essa identidade não é uma conta de usuário real e não será mostrada no Console de Gerenciamento de
Usuários do Windows.
Se o processo de trabalho do IIS requerer acesso elevado ao aplicativo, modifique a ACL (lista de controle de
acesso) do diretório que contém o aplicativo:
1. Abra o Windows Explorer e navegue para o diretório.
2. Clique com o botão direito do mouse no diretório e selecione Propriedades.
3. Na guia Segurança, selecione o botão Editar e, em seguida, no botão Adicionar.
4. Clique no botão Locais e verifique se o sistema está selecionado.
5. Insira IIS AppPool\<nome_pool_aplicativos> na área Inserir os nomes de objeto a serem
selecionados. Selecione o botão Verificar Nomes. Para o DefaultAppPool, verifique os nomes usando
IIS AppPool\DefaultAppPool. Quando o botão Verificar Nomes é selecionado, um valor de
DefaultAppPool é indicado na área de nomes de objeto. Não é possível inserir o nome do pool de
aplicativos diretamente na área de nomes de objeto. Use o formato IIS AppPool\
<nome_pool_aplicativos> ao verificar o nome do objeto.
6. Selecione OK.
7. As permissões de leitura & execução devem ser concedidas por padrão. Forneça permissões adicionais
conforme necessário.
O acesso também pode ser concedido por meio de um prompt de comando usando a ferramenta ICACLS.
Usando o DefaultAppPool como exemplo, o comando a seguir é usado:
ICACLS C:\sites\MyWebApp /grant "IIS AppPool\DefaultAppPool":F
Para saber mais, veja o tópico icacls.
Recursos de implantação para administradores do IIS

Conheça o ISS detalhadamente na documentação do IIS.
Documentação do ISS
Saiba mais sobre os modelos de implantação de aplicativos do .NET Core.
Implantação de aplicativos do .NET Core
Saiba como o módulo do ASP.NET Core permite que o servidor Web Kestrel use o IIS ou o IIS Express como
um servidor proxy reverso.
Saiba como configurar o módulo do ASP.NET Core para hospedar aplicativos do ASP.NET Core.
Saiba mais sobre a estrutura do diretório de aplicativos publicados do ASP.NET Core.
Estrutura de diretórios
Descubra módulos ativos e inativos do IIS para aplicativos do ASP.NET Core e como gerenciar os módulos do
IIS.
Módulos do IIS
Saiba como diagnosticar problemas com as implantações do ISS dos aplicativos do ASP.NET Core.
Distinga erros comuns ao hospedar aplicativos do ASP.NET Core no IIS.
Referência de erros comuns para o Serviço de Aplicativo do Azure e o IIS
Recursos adicionais
O site oficial da IIS da Microsoft
Biblioteca de conteúdo técnico do Windows Server
HTTP/2 no IIS
Por Luke Latham

Este artigo fornece instruções sobre como diagnosticar um problema de inicialização do aplicativo ASP.NET
Core ao hospedar com IIS (Serviços de Informações da Internet). As informações neste artigo se aplicam à
hospedagem em IIS no Windows Server e Windows Desktop.
No Visual Studio, um projeto do ASP.NET Core usa por padrão a hospedagem do IIS Express durante a
depuração. Uma 502.5 – Falha de Processo que ocorre ao depurar localmente pode ser solucionada usando as
recomendações presentes neste tópico.
Tópicos adicionais de solução de problemas:
Embora o Serviço de Aplicativo use o Módulo do ASP.NET Core e o IIS para hospedar aplicativos, veja o tópico
dedicado para obter instruções específicas para o Serviço de Aplicativo.
Descubra como tratar erros em aplicativos do ASP.NET Core durante o desenvolvimento em um sistema local.
Aprenda a depurar usando o Visual Studio
Este tópico apresenta os recursos do depurador do Visual Studio.
Depurar com o Visual Studio Code
Saiba mais sobre o suporte de depuração interno do Visual Studio Code.
Erros de inicialização do aplicativo

502.5 – Falha de Processo
O processo de trabalho falha. O aplicativo não foi iniciado.
O Módulo do ASP.NET Core tenta iniciar o processo de trabalho, mas falhar ao iniciar. A causa de uma falha de
inicialização do processo geralmente pode ser determinada com base em entradas no Log de Eventos do
Aplicativo e no log de stdout do Módulo do ASP.NET Core.
A página do erro 502.5 – Falha no Processo é retornada quando um erro de configuração de hospedagem ou
do aplicativo faz com que o processo de trabalho falhe:
500 – Erro Interno do Servidor
O aplicativo é iniciado, mas um erro impede o servidor de atender à solicitação.
Esse erro ocorre no código do aplicativo durante a inicialização ou durante a criação de uma resposta. A
resposta poderá não conter nenhum conteúdo, ou a resposta poderá ser exibida como um 500 – Erro Interno do
Servidor no navegador. O Log de Eventos do Aplicativo geralmente indica que o aplicativo iniciou normalmente.
Da perspectiva do servidor, isso está correto. O aplicativo foi iniciado, mas não é capaz de gerar uma resposta
válida. Execute o aplicativo em um prompt de comando no servidor ou habilite o log de stdout do Módulo do
ASP.NET Core para solucionar o problema.
Redefinição de conexão
Se um erro ocorrer após os cabeçalhos serem enviados, será tarde demais para o servidor enviar um 500 – Erro
Interno do Servidor no caso de um erro ocorrer. Isso geralmente acontece quando ocorre um erro durante a
serialização de objetos complexos para uma resposta. Esse tipo de erro é exibida como um erro de redefinição
de conexão no cliente. O Log de aplicativo pode ajudar a solucionar esses tipos de erros.
Limites de inicialização padrão

O Módulo do ASP.NET Core está configurado com um startupTimeLimit padrão de 120 segundos. Quando
deixado no valor padrão, um aplicativo pode levar até dois minutos para iniciar antes que uma falha do processo
seja registrada em log pelo módulo. Para obter informações sobre como configurar o módulo, veja Atributos do
elemento aspNetCore.
Solucionar problemas de inicialização do aplicativo

Log de Eventos do Aplicativo
Acesse o Log de Eventos do Aplicativo:
1. Abra o menu Iniciar, procure Visualizador de Eventos e, em seguida, selecione o aplicativo Visualizador
de Eventos.
2. No Visualizador de Eventos, abra o nó Logs do Windows.
3. Selecione Aplicativo para abrir o Log de Eventos do Aplicativo.
4. Procure erros associados ao aplicativo com falha. Os erros têm um valor Módulo AspNetCore do IIS ou
Módulo AspNetCore do IIS Express na coluna Origem.
Execute o aplicativo em um prompt de comando
Muitos erros de inicialização não produzem informações úteis no Log de Eventos do Aplicativo. Você pode
encontrar a causa de alguns erros ao executar o aplicativo em um prompt de comando no sistema de
hospedagem.
Implantação dependente de estrutura
Se o aplicativo é uma implantação dependente de estrutura:
1. Em um prompt de comando, navegue até a pasta de implantação e execute o aplicativo, executando o
assembly do aplicativo com dotnet.exe. No comando a seguir, substitua o nome do assembly do aplicativo
por <assembly_name>: dotnet .\<assembly_name>.dll .
2. A saída do console do aplicativo, mostrando eventuais erros, é gravada na janela do console.
3. Se os erros ocorrerem ao fazer uma solicitação para o aplicativo, faça uma solicitação para o host e a porta
em que o Kestrel escuta. Usando o host e a porta padrão, faça uma solicitação para http://localhost:5000/ .
Se o aplicativo responder normalmente no endereço do ponto de extremidade do Kestrel, mais
provavelmente, o problema estará relacionado à configuração do proxy reverso e, menos provavelmente,
dentro do aplicativo.
Implantação autossuficiente
Se o aplicativo é uma implantação autossuficiente:
1. Em um prompt de comando, navegue até a pasta de implantação e execute o arquivo executável do
aplicativo. No comando a seguir, substitua o nome do assembly do aplicativo por <assembly_name>:
<assembly_name>.exe .
2. A saída do console do aplicativo, mostrando eventuais erros, é gravada na janela do console.
3. Se os erros ocorrerem ao fazer uma solicitação para o aplicativo, faça uma solicitação para o host e a porta
em que o Kestrel escuta. Usando o host e a porta padrão, faça uma solicitação para http://localhost:5000/ .
Se o aplicativo responder normalmente no endereço do ponto de extremidade do Kestrel, mais
provavelmente, o problema estará relacionado à configuração do proxy reverso e, menos provavelmente,
dentro do aplicativo.
Log de stdout do Módulo do ASP.NET Core
Para habilitar e exibir logs de stdout:
1. Navegue até a pasta de implantação do site no sistema de hospedagem.
2. Se a pasta logs não estiver presente, crie-a. Para obter instruções sobre como habilitar o MSBuild para criar a
pasta logs na implantação automaticamente, veja o tópico Estrutura de diretórios.
3. Edite o arquivo web.config. Defina stdoutLogEnabled para true e altere o caminho stdoutLogFile para
apontar para a pasta logs (por exemplo, .\logs\stdout ). stdout no caminho é o prefixo do nome do arquivo
de log. Uma extensão de arquivo, uma ID do processo e um carimbo de data/hora são adicionados
automaticamente quando o log é criado. Usando stdout como o prefixo do nome do arquivo, um arquivo
de log típico é nomeado stdout_20180205184032_5412.log.
4. Verifique se a identidade do pool de aplicativos tem permissões de gravação para a pasta logs.
5. Salve o arquivo web.config atualizado.
7. Navegue até a pasta logs. Localize e abra o log de stdout mais recente.
8. Estude o log em busca de erros.
Importante! Desabilite o registro em log de stdout quando a solução de problemas for concluída.
1. Edite o arquivo web.config.
2. Defina stdoutLogEnabled para false .
3. Salve o arquivo.
WARNING
arquivo de log ou para o número de arquivos de log criados.
Para registro em log de rotina em um aplicativo ASP.NET Core, use uma biblioteca de registro em log que limita o
tamanho do arquivo de log e realiza a rotação de logs. Para obter mais informações, veja provedores de log de terceiros.
Habilitar a Página de Exceções do Desenvolvedor

A variável de ambiente ASPNETCORE_ENVIRONMENT pode ser adicionada ao web.config para executar o aplicativo no
ambiente de desenvolvimento. Desde que o ambiente não seja substituído na inicialização do aplicativo por
UseEnvironment no compilador do host, definir a variável de ambiente permite que a Página de Exceções do
Desenvolvedor apareça quando o aplicativo é executado.
arguments=".\MyApp.dll"
stdoutLogFile=".\logs\stdout">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
</environmentVariables>
</aspNetCore>
Configurar a variável de ambiente para ASPNETCORE_ENVIRONMENT só é recomendado para servidores de preparo e

de teste que não estejam expostos à Internet. Remova a variável de ambiente do arquivo web.config após a
solução de problemas. Para obter informações sobre como definir variáveis de ambiente no web.config, confira
Elemento filho environmentVariables de aspNetCore.
Erros de inicialização comuns

Consulte Referência de erros comuns para o Serviço de Aplicativo do Azure e o IIS com o ASP.NET Core. A
maioria dos problemas comuns que impedem a inicialização do aplicativo é abordada no tópico de referência.
Aplicativo lento ou travando

Quando um aplicativo responde lentamente ou trava em uma solicitação, obtenha e analise um arquivo de
despejo. Arquivos de despejo podem ser obtidos usando qualquer uma das ferramentas a seguir:
ProcDump
DebugDiag
WinDbg: Baixar as ferramentas de depuração para Windows, Depuração usando o WinDbg
Depuração remota
Veja Depuração remota do ASP.NET Core em um computador de IIS remoto no Visual Studio 2017 na
documentação do Visual Studio.
Informações do aplicativo
O Application Insights fornece telemetria de aplicativos hospedados pelo IIS, incluindo recursos de relatório e
de registro de erros em log. O Application Insights só pode relatar erros ocorridos depois que o aplicativo é
iniciado quando os recursos de registro em log do aplicativo se tornam disponíveis. Para obter mais
informações, veja Application Insights para ASP.NET Core.
Avisos adicionais para solução de problemas
Algumas vezes um aplicativo em funcionamento falha imediatamente após atualizar o SDK do .NET Core nas
versões de pacote ou de computador de desenvolvimento no aplicativo. Em alguns casos, pacotes incoerentes
podem interromper um aplicativo ao executar atualizações principais. A maioria desses problemas pode ser
corrigida seguindo estas instruções:
1. Exclua as pastas bin e obj.
2. Limpe os caches de pacote em %UserProfile%\.nuget\packages e %LocalAppData%\Nuget\v3 -cache.
3. Restaure e recompile o projeto.
4. Confirme que a implantação anterior no servidor foi completamente excluída antes de reimplantar o
aplicativo.
TIP
Uma maneira prática de se limpar caches do pacote é executar dotnet nuget locals all --clear de um prompt de
comando.
Também é possível limpar os caches de pacote usando a ferramenta nuget.exe e executando o comando
nuget locals all -clear . nuget.exe não é uma instalação fornecida com o sistema operacional Windows Desktop e
devem ser obtidos separadamente do site do NuGet.
Recursos adicionais
Referência de configuração do Módulo do
ASP.NET Core
Por Luke Latham, Rick Anderson e Sourabh Shirhatti

Este documento fornece instruções sobre como configurar o Módulo do ASP.NET Core para hospedar
aplicativos do ASP.NET Core. Para obter uma introdução ao Módulo do ASP.NET Core e instruções de
instalação, veja a visão geral do Módulo do ASP.NET Core.
Modelo de hospedagem
Para aplicativos em execução no .NET Core 2.2 ou posterior, o módulo dá suporte a um modelo de
hospedagem em processo para melhorar o desempenho em comparação com hospedagem do proxy reverso
(fora de processo). Para obter mais informações, consulte Módulo do ASP.NET Core.
A hospedagem em processo é uma aceitação para os aplicativos existentes, mas o padrão dos modelos dotnet
new é o modelo de hospedagem em processo para todos os cenários do IIS e IIS Express.
Para configurar um aplicativo para hospedagem em processo, adicione a propriedade
<AspNetCoreModuleHostingModel> ao arquivo de projeto do aplicativo com um valor de inprocess (a
hospedagem de fora do processo é definida com outofprocess ):
<PropertyGroup>
<AspNetCoreModuleHostingModel>inprocess</AspNetCoreModuleHostingModel>
</PropertyGroup>
As seguintes características se aplicam ao hospedar em processo:

O servidor Kestrel não é usado. Uma implementação personalizada do IServer, IISHttpServer
funciona como o servidor do aplicativo.
O requestTimeout atributo não se aplica à hospedagem em processo.
Não há suporte para o compartilhamento do pool de aplicativos entre aplicativos. Use um pool de
aplicativos por aplicativo.
Ao usar a Implantação da Web ou inserir manualmente um arquivo app_offline.htm na implantação, o
aplicativo talvez não seja desligado imediatamente se houver uma conexão aberta. Por exemplo, uma
conexão websocket pode atrasar o desligamento do aplicativo.
A arquitetura (número de bit) do aplicativo e o tempo de execução instalado (x64 ou x86) devem
corresponder à arquitetura do pool de aplicativos.
Se a configuração manual do host do aplicativo com WebHostBuilder (não usando
CreateDefaultBuilder) e o aplicativo não forem executados diretamente no servidor Kestrel (auto-
hospedado), chame UseKestrel antes de chamar UseIISIntegration . Se a ordem for invertida, a
inicialização do host falhará.
As desconexões do cliente são detectadas. O token de cancelamento HttpContext.RequestAborted é
cancelado quando o cliente se desconecta.
Alterações no modelo de hospedagem
Se a configuração hostingModel for alterada no arquivo web.config (explicado na seção Configuração a
Web.config), o módulo reciclará o processo de trabalho do IIS.
Para o IIS Express, o módulo não recicla o processo de trabalho, mas em vez disso, dispara um desligamento
normal do processo atual do IIS Express. A próxima solicitação para o aplicativo gera um novo processo do
IIS Express.
Nome do processo
Process.GetCurrentProcess().ProcessName relata w3wp (em processo) ou dotnet (fora do processo).
Configuração com web.config

O Módulo do ASP.NET Core está configurado com a seção aspNetCore do nó system.webServer no arquivo
web.config do site.
O seguinte arquivo web.config é publicado para uma implantação dependente de estrutura e configura o
Módulo do ASP.NET Core para manipular solicitações de site:

<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
</handlers>
stdoutLogFile=".\logs\stdout"
hostingModel="inprocess" />
</system.webServer>
</configuration>

<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
</handlers>
</system.webServer>
</configuration>
O seguinte web.config é publicado para uma implantação autossuficiente:

<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
</handlers>
<aspNetCore processPath=".\MyApp.exe"
stdoutLogFile=".\logs\stdout"
hostingModel="inprocess" />
</system.webServer>
</configuration>
<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
</handlers>
<aspNetCore processPath=".\MyApp.exe"
</system.webServer>
</configuration>
Quando um aplicativo é implantado no Serviço de Aplicativo do Azure, o caminho stdoutLogFile é definido

para \\?\%home%\LogFiles\stdout . O caminho salva logs de stdout para a pasta LogFiles, que é um local criado
automaticamente pelo serviço.
Confira Configuração de subaplicativos para uma nota importante relativa à configuração de arquivos
web.config em subaplicativos.
Atributos do elemento aspNetCore
ATRIBUTO DESCRIÇÃO PADRÃO
arguments Atributo de cadeia de caracteres

opcional.
Argumentos para o executável
especificado em processPath.
disableStartUpErrorPage Atributo booliano opcional. false
Se for true, a página 502.5 –

Falha do Processo será
suprimida e a página de código de
status 502, configurada no
web.config, terá precedência.
forwardWindowsAuthToken Atributo booliano opcional. true
Se for true, o token será

encaminhado para o processo
filho escutando em
%ASPNETCORE_PORT% como um
cabeçalho 'MS-ASPNETCORE-
WINAUTHTOKEN' por solicitação.
É responsabilidade desse processo
chamar CloseHandle nesse token
por solicitação.
hostingModel Atributo de cadeia de caracteres outofprocess

opcional.
Especifica o modelo de
hospedagem como em processo (
inprocess ) ou de fora do
processo ( outofprocess ).
processesPerApplication Atributo inteiro opcional. Padrão: 1

Mín.: 1
Especifica o número de instâncias Máx.: 100 †
do processo especificado na
configuração processPath que
pode ser ativada por aplicativo.
†Para hospedagem em processo,
o valor está limitado a 1 .
processPath Atributo de cadeia de caracteres

obrigatório.
Caminho para o executável que
inicia um processo que escuta
solicitações HTTP. Caminhos
relativos são compatíveis. Se o
caminho começa com . , o
caminho é considerado relativo à
raiz do site.
rapidFailsPerMinute Atributo inteiro opcional. Padrão: 10

Mín.: 0
Especifica o número de vezes que Máx.: 100
o processo especificado em
processPath pode falhar por
minuto. Se esse limite for
excedido, o módulo interromperá
a inicialização do processo pelo
restante do minuto.
Sem suporte com hospedagem
padrão.
requestTimeout Atributo de intervalo de tempo Padrão: 00:02:00

opcional. Mín.: 00:00:00
Máx.: 360:00:00
Especifica a duração para a qual o
Módulo do ASP.NET Core aguarda
uma resposta do processo que
escuta em
%ASPNETCORE_PORT%.
Em versões do Módulo do
ASP.NET Core que acompanham a
versão do ASP.NET Core 2.1 ou
posterior, o requestTimeout é
especificado em horas, minutos e
segundos.
Não se aplica à hospedagem em
processo. Para a hospedagem em
processo, o módulo aguarda o
aplicativo processar a solicitação.
shutdownTimeLimit Atributo inteiro opcional. Padrão: 10

Mín.: 0
Duração em segundos que o Máx.: 600
módulo espera para o executável
desligar normalmente quando o
arquivo app_offline.htm é
detectado.
startupTimeLimit Atributo inteiro opcional. Padrão: 120

Mín.: 0
módulo espera para o arquivo
executável iniciar um processo
escutando na porta. Se esse
tempo limite é excedido, o
módulo encerra o processo. O
módulo tentará reiniciar o
processo quando ele receber uma
nova solicitação e continuará a
tentar reiniciar o processo em
solicitações subsequentes de
entrada, a menos que o aplicativo
falhe em iniciar um número de
vezes igual a
rapidFailsPerMinute no último
minuto sem interrupção.
Um valor de 0 (zero) não é
considerado um tempo limite
infinito.
stdoutLogEnabled Atributo booliano opcional. false
Se for true, stdout e stderr para

processPath serão
redirecionados para o arquivo
especificado em stdoutLogFile.
stdoutLogFile Atributo de cadeia de caracteres aspnetcore-stdout

opcional.
Especifica o caminho relativo ou
absoluto para o qual stdout e
stderr do processo especificado
em processPath são registrados
em log. Os caminhos relativos são
relativos à raiz do site. Qualquer
caminho começando com . é
relativo à raiz do site e todos os
outros caminhos são tratados
como caminhos absolutos. As
pastas fornecidas no caminho
devem existir para que o módulo
crie o arquivo de log. Usando
delimitadores de sublinhado, um
carimbo de data/hora, uma ID de
processo e a extensão de arquivo
(.log) são adicionados ao último
segmento do caminho
stdoutLogFile. Se
.\logs\stdout é fornecido
como um valor, um log de
exemplo stdout é salvo como
stdout_20180205194132_1934.l
og na pasta logs quando salvos
em 5/2/2018, às 19:41:32, com
uma ID de processo de 1934.

opcional.


filho escutando em
por solicitação.

Mín.: 1
Especifica o número de instâncias Máx.: 100

obrigatório.
raiz do site.

Mín.: 0
restante do minuto.

Máx.: 360:00:00
escuta em
%ASPNETCORE_PORT%.
Em versões do Módulo do
ASP.NET Core que acompanham a
versão do ASP.NET Core 2.1 ou
posterior, o requestTimeout é
especificado em horas, minutos e
segundos.

Mín.: 0
detectado.

Mín.: 0
vezes igual a
Um valor de 0 (zero) não é
considerado um tempo limite
infinito.

processPath serão

opcional.
segmento do caminho
stdoutLogFile. Se
stdout_20180205194132_1934.l
em 5/2/2018, às 19:41:32, com

opcional.


filho escutando em
por solicitação.

Mín.: 1
Especifica o número de instâncias Máx.: 100

obrigatório.
raiz do site.

Mín.: 0
restante do minuto.

Máx.: 360:00:00
escuta em
%ASPNETCORE_PORT%.
Em versões do Módulo ASP.NET
Core que acompanham a versão
do ASP.NET Core 2.0 ou anterior,
o requestTimeout deve ser
especificado somente em minutos
inteiros, caso contrário, ele
assume o valor padrão de 2
minutos.

Mín.: 0
detectado.

Mín.: 0
vezes igual a

processPath serão

opcional.
segmento do caminho
stdoutLogFile. Se
stdout_20180205194132_1934.l
em 5/2/2018, às 19:41:32, com
Definindo variáveis de ambiente

Variáveis de ambiente podem ser especificadas para o processo no atributo processPath . Especificar uma
variável de ambiente com o elemento filho environmentVariable de um elemento de coleção
environmentVariables . Variáveis de ambiente definidas nesta seção têm precedência sobre variáveis de
ambiente do sistema.
O exemplo a seguir define duas variáveis de ambiente. ASPNETCORE_ENVIRONMENT configura o ambiente do
aplicativo para Development . Um desenvolvedor pode definir esse valor temporariamente no arquivo
web.config para forçar o carregamento da Página de Exceções do Desenvolvedor ao depurar uma exceção de
aplicativo. CONFIG_DIR é um exemplo de uma variável de ambiente definida pelo usuário, em que o
desenvolvedor escreveu código que lê o valor de inicialização para formar um caminho no qual carregar o
arquivo de configuração do aplicativo.
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="inprocess">
<environmentVariable name="CONFIG_DIR" value="f:\application_config" />
</aspNetCore>
stdoutLogFile="\\?\%home%\LogFiles\stdout">
<environmentVariable name="CONFIG_DIR" value="f:\application_config" />
</aspNetCore>
WARNING
Defina a variável de ambiente apenas ASPNETCORE_ENVIRONMENT para Development em servidores de preparo e de
teste que não estão acessíveis a redes não confiáveis, tais como a Internet.
app_offline.htm
Se um arquivo com o nome app_offline.htm é detectado no diretório raiz de um aplicativo, o Módulo do
ASP.NET Core tenta desligar normalmente o aplicativo e parar o processamento de solicitações de entrada.
Se o aplicativo ainda está em execução após o número de segundos definido em shutdownTimeLimit , o
Módulo do ASP.NET Core encerra o processo em execução.
Enquanto o arquivo app_offline.htm estiver presente, o Módulo do ASP.NET Core responderá às solicitações
enviando o conteúdo do arquivo app_offline.htm. Quando o arquivo app_offline.htm é removido, a próxima
solicitação inicia o aplicativo.
Ao usar o modelo de hospedagem de fora do processo, talvez o aplicativo não desligue imediatamente se
houver uma conexão aberta. Por exemplo, uma conexão websocket pode atrasar o desligamento do aplicativo.
Página de erro de inicialização

Só se aplica à hospedagem de fora do processo.
Se o Módulo do ASP.NET Core falhar ao iniciar o processo de back-end ou se o processo de back-end iniciar
mas falhar em escutar na porta configurada, uma página de código de status 502.5 – Falha no Processo será
exibida. Para omitir esta página e reverter para a página de código de status 502 padrão do IIS, use o atributo
disableStartUpErrorPage . Para obter mais informações sobre como configurar mensagens de erro
personalizadas, veja Erros HTTP <httpErrors> .
Criação de log e redirecionamento

O Módulo do ASP.NET Core redireciona as saídas de console stdout e stderr para o disco se os atributos
stdoutLogEnabled e stdoutLogFile do elemento aspNetCore forem definidos. As pastas no caminho
stdoutLogFile devem existir para que o módulo crie o arquivo de log. O pool de aplicativos deve ter acesso
de gravação ao local em que os logs foram gravados (use IIS AppPool\<app_pool_name> para fornecer
permissão de gravação).
Logs não sofrem rotação, a menos que ocorra a reciclagem/reinicialização do processo. É responsabilidade do
hoster limitar o espaço em disco consumido pelos logs.
Usar o log de stdout é recomendado apenas para solucionar problemas de inicialização do aplicativo. Não use
o log de stdout para fins gerais de registro em log do aplicativo. Para registro em log de rotina em um
aplicativo ASP.NET Core, use uma biblioteca de registro em log que limita o tamanho do arquivo de log e
realiza a rotação de logs. Para obter mais informações, veja provedores de log de terceiros.
Uma extensão de arquivo e um carimbo de data/hora são adicionados automaticamente quando o arquivo de
log é criado. O nome do arquivo de log é composto por meio do acréscimo do carimbo de data/hora, da ID do
processo e da extensão de arquivo (.log) para o último segmento do caminho stdoutLogFile (normalmente
stdout), delimitados por sublinhados. Se o caminho stdoutLogFile termina com stdout, um log para um
aplicativo com um PID de 1934, criado em 5/2/2018 às 19:42:32, tem o nome de arquivo
stdout_20180205194132_1934.log.
O elemento aspNetCore de exemplo a seguir configura o registro em log de stdout para um aplicativo
hospedado no Serviço de Aplicativo do Azure. Um caminho local ou um caminho de compartilhamento de
rede é aceitável para o registro em log local. Confirme se a identidade do usuário AppPool tem permissão
para gravar no caminho fornecido.
stdoutLogEnabled="true"
</aspNetCore>
stdoutLogEnabled="true"
stdoutLogFile="\\?\%home%\LogFiles\stdout">
</aspNetCore>
Logs de diagnóstico avançados

O Módulo do ASP.NET Core pode ser configurado para fornecer logs de diagnóstico avançados. Adicione o
elemento <handlerSettings> ao elemento <aspNetCore> no web.config. A definição de debugLevel como
TRACE expõe uma fidelidade maior de informações de diagnóstico:
<handlerSettings>
<handlerSetting name="debugFile" value="aspnetcore-debug.log" />
<handlerSetting name="debugLevel" value="FILE,TRACE" />
</handlerSettings>
</aspNetCore>
Os valores do nível de depuração ( debugLevel ) podem incluir o nível e a localização.

Níveis (na ordem do menos para o mais detalhado):
ERROR
WARNING
INFO
TRACE
Locais (vários locais são permitidos):
CONSOLE
EVENTLOG
FILE
As configurações do manipulador também podem ser fornecidas por meio de variáveis de ambiente:
ASPNETCORE_MODULE_DEBUG_FILE – caminho para o arquivo de log de depuração. (Padrão: aspnetcore-
debug.log)
ASPNETCORE_MODULE_DEBUG – configuração do nível de depuração.
WARNING
Não deixe o log de depuração habilitado na implantação por mais tempo que o necessário para solucionar um
problema. O tamanho do log não é limitado. Deixar o log de depuração habilitado pode esgotar o espaço em disco
disponível e causar falha no servidor ou no serviço de aplicativo.
Veja Configuração com web.config para obter um exemplo do elemento aspNetCore no arquivo web.config.
A configuração de proxy usa o protocolo HTTP e um token de

emparelhamento
Só se aplica à hospedagem de fora do processo.
O proxy criado entre o Módulo do ASP.NET Core e o Kestrel usa o protocolo HTTP. O uso de HTTP é uma
otimização de desempenho na qual o tráfego entre o módulo e o Kestrel ocorre em um endereço de loopback
fora do adaptador de rede. Não há nenhum risco de interceptação do tráfego entre o módulo e o Kestrel em
um local fora do servidor.
Um token de emparelhamento é usado para assegurar que as solicitações recebidas pelo Kestrel foram
transmitidas por proxy pelo IIS e que não são provenientes de outra origem. O token de emparelhamento é
criado e definido em uma variável de ambiente ( ASPNETCORE_TOKEN ) pelo módulo. O token de emparelhamento
também é definido em um cabeçalho ( MSAspNetCoreToken ) em cada solicitação com proxy. O Middleware do
IIS verifica cada solicitação recebida para confirmar se o valor de cabeçalho do token de emparelhamento
corresponde ao valor da variável de ambiente. Se os valores do token forem incompatíveis, a solicitação será
registrada em log e rejeitada. A variável de ambiente do token de emparelhamento e o tráfego entre o módulo
e o Kestrel não são acessíveis em um local fora do servidor. Sem saber o valor do token de emparelhamento,
um invasor não pode enviar solicitações que ignoram a verificação no Middleware do IIS.
Módulo do ASP.NET Core com uma configuração do IIS

compartilhada
O instalador do módulo do ASP.NET Core é executado com os privilégios da conta de SISTEMA. Já que a
conta de sistema local não tem permissão para modificar o caminho do compartilhamento usado pela
configuração compartilhada de IIS, o instalador experimenta um erro de acesso negado ao tentar definir as
configurações de módulo em applicationHost.config no compartilhamento. Ao usar uma configuração
compartilhada de IIS, siga estas etapas:
1. Desabilite a configuração compartilhada de IIS.
2. Execute o instalador.
3. Exportar o arquivo applicationHost.config atualizado para o compartilhamento.
4. Reabilite a Configuração Compartilhada do IIS.
Versão do módulo e logs do instalador do pacote de hospedagem

Para determinar a versão do Módulo do ASP.NET Core instalado:
1. No sistema de hospedagem, navegue até %windir%\System32\inetsrv.
2. Localize o arquivo aspnetcore.dll.
3. Clique com o botão direito do mouse no arquivo e selecione Propriedades no menu contextual.
4. Selecione a guia Detalhes. A Versão do arquivo e a Versão do produto representam a versão instalada
do módulo.
Os logs de instalador do pacote de hospedagem para o módulo são encontrados em
C:\Usuários\%UserName%\AppData\Local\Temp. O arquivo é nomeado
dd_DotNetCoreWinSvrHosting__<carimbo de data/hora>_000_AspNetCoreModule_x64.log.
Locais dos arquivos de módulo, de esquema e de configuração

Módulo
IIS (x86/amd64):
%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll
IIS Express (x86/amd64):
%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
Esquema
IIS
%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
IIS Express
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
Configuração
IIS
%windir%\System32\inetsrv\config\applicationHost.config
IIS Express
.vs\config\applicationHost.config
Os arquivos podem ser encontrados pesquisando por aspnetcore.dll no arquivo applicationHost.config. Para o
IIS Express, o arquivo applicationHost.config não existirá por padrão. O arquivo é criado em
<application_root>\.vs\config ao iniciar qualquer projeto de aplicativo Web na solução do Visual Studio.
Suporte ao IIS no tempo de desenvolvimento no
Visual Studio para ASP.NET Core
Por Sourabh Shirhatti e Luke Latham

Este artigo descreve o suporte do Visual Studio a depuração de aplicativos do ASP.NET Core em execução por trás
do IIS no Windows Server. Este tópico orienta você sobre como habilitar esse recurso e configurar um projeto.
Pré-requisitos
Visual Studio para Windows
Certificado de segurança X.509
Habilitar o IIS
1. Navegue para Painel de Controle > Programas > Programas e Recursos > Ativar ou desativar recursos
do Windows (lado esquerdo da tela).
2. Selecione a caixa de seleção Serviços de Informações da Internet.
A instalação do IIS pode exigir uma reinicialização do sistema.
Configurar o IIS
O IIS deve ter um site configurado com o seguinte:
Um nome do host que corresponda ao nome do host da URL do perfil de inicialização do aplicativo.
Associação para a porta 443, com um certificado atribuído.
Por exemplo, o Nome do host para um site adicionado é definido como "localhost" (o perfil de inicialização
também usará "localhost" posteriormente neste tópico). A porta é definida para "443" (HTTPS ). O Certificado de
Desenvolvimento do IIS Express é atribuído ao site, mas nenhum certificado válido funciona:
Se a instalação do IIS já tiver um site da Web padrão com um nome do host que corresponde ao nome do host
da URL do perfil de inicialização do aplicativo:
Adicione uma associação de porta para a porta 443 (HTTPS ).
Atribua um certificado válido para o site.
Habilitar o suporte ao IIS no tempo de desenvolvimento no Visual

Studio
1. Inicie o Instalador do Visual Studio.
2. Selecione o componente Suporte ao IIS no tempo de desenvolvimento. O componente está listado como
opcional no painel Resumo para a carga de trabalho Desenvolvimento Web e ASP.NET. O componente
instala o Módulo do ASP.NET Core, que é um módulo nativo do IIS necessário para executar aplicativos do
ASP.NET Core por trás de IIS em uma configuração de proxy reverso.
Configurar o projeto
Redirecionamento para HTTPS
Para um novo projeto, selecione a caixa de seleção para Configurar para HTTPS na janela Novo Aplicativo
Web ASP.NET Core:
Em um projeto existente, use o middleware de redirecionamento para HTTPS no Startup.Configure chamando o

método de extensão UseHttpsRedirection:
{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
Perfil de inicialização do IIS

Crie um novo perfil de inicialização para adicionar suporte ao IIS no tempo de desenvolvimento:
1. Para Perfil, selecione o botão Novo. Nomeie o perfil "IIS" na janela pop-up. Selecione OK para criar o perfil.
2. Para a configuração Iniciar, selecione IIS da lista.
3. Selecione a caixa de seleção Iniciar navegador e forneça a URL de ponto de extremidade. Use o protocolo
HTTPS. Este exemplo usa https://localhost/WebApplication1 .
4. Na seção Variáveis de ambiente, selecione o botão Adicionar. Fornecer uma variável de ambiente com uma
chave ASPNETCORE_ENVIRONMENT e um valor Development .
5. Na área Configurações do Servidor Web, defina a URL do Aplicativo. Este exemplo usa
https://localhost/WebApplication1 .
6. Salve o perfil.
Como alternativa, adicione manualmente um perfil de inicialização para o arquivo launchSettings.json no
aplicativo:
{
"iisSettings": {
"iis": {
"applicationUrl": "https://localhost/WebApplication1",
"sslPort": 0
}
},
"profiles": {
"IIS": {
"commandName": "IIS",
"launchUrl": "https://localhost/WebApplication1",
}
}
}
}
Executar o projeto
Na interface do usuário do VS, definido no botão executar o IIS perfil e selecione o botão para iniciar o aplicativo:
O Visual Studio poderá solicitar uma reinicialização se não estiver executando como administrador. Se solicitado,
reinicie o Visual Studio.
Se for usado um certificado de desenvolvimento não confiável, o navegador poderá exigir a criação de uma
exceção para o certificado não confiável.
Recursos adicionais
Introdução ao Módulo do ASP.NET Core
Impor o HTTPS
Por Luke Latham

Alguns dos módulos nativos do IIS e todos os módulos gerenciados do IIS não são capazes de processar
solicitações para aplicativos do ASP.NET Core. Em muitos casos, o ASP.NET Core oferece uma alternativa aos
cenários abordados pelos módulos gerenciados e nativos do IIS.
Módulos nativos
A tabela indica módulos nativos do IIS que estão funcionando em solicitações de proxy reverso para aplicativos
do ASP.NET Core.
FUNCIONAL COM OS APLICATIVOS DO

MÓDULO ASP.NET CORE OPÇÃO DO ASP.NET CORE
Autenticação anônima Sim

AnonymousAuthenticationModule
Autenticação básica Sim

BasicAuthenticationModule
Autenticação de mapeamento de Sim

certificação de cliente
CertificateMappingAuthenticationModule
CGI Não
CgiModule
Validação da configuração Sim

ConfigurationValidationModule
Erros HTTP Não Middleware de páginas de código de

CustomErrorModule status
Registro em log personalizado Sim

CustomLoggingModule
Documento padrão Não Middleware de arquivos padrão

DefaultDocumentModule
Autenticação Digest Sim

DigestAuthenticationModule
Pesquisa no Diretório Não Middleware de navegação no diretório

DirectoryListingModule
Compactação dinâmica Sim Middleware de compactação de

DynamicCompressionModule resposta
Rastreamento Sim Registro em log do ASP.NET Core

FailedRequestsTracingModule
Cache de arquivo Não Middleware de Cache de Resposta

FileCacheModule
Cache HTTP Não Middleware de Cache de Resposta

HttpCacheModule
Log HTTP Sim Registro em log do ASP.NET Core

HttpLoggingModule
Redirecionamento de HTTP Sim Middleware de regravação de URL

HttpRedirectionModule
Autenticação de mapeamento de Sim

certificado do cliente IIS
IISCertificateMappingAuthenticationModule
Restrições de IP e domínio Sim

IpRestrictionModule
Filtros ISAPI Sim Middleware

IsapiFilterModule
ISAPI Sim Middleware

IsapiModule
Suporte de protocolo Sim

ProtocolSupportModule
Filtragem de Solicitações Sim Middleware de regravação de URL

RequestFilteringModule IRule
Monitor de Solicitações Sim

RequestMonitorModule
Regravação de URL† Sim Middleware de regravação de URL

RewriteModule
Inclusões do lado do servidor Não

ServerSideIncludeModule
Compactação estática Não Middleware de compactação de

StaticCompressionModule resposta
Conteúdo Estático Não Middleware de arquivos estáticos

StaticFileModule
Cache de token Sim

TokenCacheModule
Cache de URI Sim

UriCacheModule
Autorização de URL Sim Identidade do ASP.NET Core

UrlAuthorizationModule
Autenticação do Windows Sim

WindowsAuthenticationModule
†Os tipos de correspondência isFile e isDirectory do módulo de regravação da URL não funcionam com
aplicativos do ASP.NET Core, devido a alterações na estrutura de diretórios.
Módulos gerenciados
Os módulos gerenciados não funcionam com aplicativos do ASP.NET Core hospedados quando a versão do
.NET CLR do pool de aplicativos está definido como Sem Código Gerenciado. O ASP.NET Core oferece
alternativas de middleware em vários casos.
MÓDULO OPÇÃO DO ASP.NET CORE
AnonymousIdentification
DefaultAuthentication
FileAuthorization
FormsAuthentication Middleware de autenticação de cookie
OutputCache Middleware de Cache de Resposta
Perfil
RoleManager
ScriptModule-4.0
Session Middleware de sessão
UrlAuthorization
UrlMappingsModule Middleware de regravação de URL
UrlRoutingModule-4.0 Identidade do ASP.NET Core
WindowsAuthentication
Alterações de aplicativo do Gerenciador do IIS

Ao usar o Gerenciador do IIS para definir as configurações, o arquivo web.config do aplicativo é alterado. Ao
implantar um aplicativo e incluir web.config, todas as alterações feitas com o Gerenciador do IIS são substituídas
pelo arquivo web.config implantado. Se forem feitas alterações para o arquivo web.config do servidor, copie o
arquivo web.config atualizado no servidor para o projeto local imediatamente.
Desabilitando módulos do IIS

Se um módulo do IIS é configurado no nível do servidor que deve ser desabilitado para um aplicativo, uma
adição ao arquivo web.config do aplicativo pode desabilitar o módulo. Deixe o módulo no lugar e desative-o
usando uma definição de configuração (se disponível) ou remova o módulo do aplicativo.
Desativação do módulo
Muitos módulos oferecem uma configuração que permite que eles sejam desabilitados sem remover o módulo
do aplicativo. Essa é a maneira mais simples e rápida de desativar um módulo. Por exemplo, o módulo de
redirecionamento de HTTP pode ser desabilitado com o elemento <httpRedirect> em web.config:
<configuration>
<system.webServer>
<httpRedirect enabled="false" />
</system.webServer>
</configuration>
Para obter mais informações sobre como desabilitar módulos com definições de configuração, siga os links na
seção Elementos Filho de IIS <system.webServer>.
Remoção do módulo
Se optar pela remoção de um módulo com uma configuração em web.config, desbloqueie o módulo e
desbloqueie a seção <modules> de web.config primeiro:
1. Desbloqueie o módulo no nível do servidor. Selecione o servidor do IIS na barra lateral Conexões do
Gerenciador do IIS. Abra os Módulos na área IIS. Selecione o módulo na lista. Na barra lateral Ações à
direita, selecione Desbloquear. Desbloqueie todos os módulos que você planeja remover de web.config
posteriormente.
2. Implantar o aplicativo sem uma seção <modules> em web.config. Se um aplicativo é implantado com um
web.config que contém a seção <modules> sem ter desbloqueado a seção primeiro no Gerenciador do IIS,
o Configuration Manager gera uma exceção ao tentar desbloquear a seção. Portanto, implante o
aplicativo sem uma seção <modules> .
3. Desbloqueie a seção <modules> de web.config. Na barra lateral Conexões, selecione o site em Sites. Na
área Gerenciamento, abra o Editor de Configuração. Use os controles de navegação para selecionar a
seção system.webServer/modules . Na barra lateral Ações à direita, selecione para Desbloquear a seção.
4. Neste ponto, uma seção <modules> pode ser adicionada ao arquivo web.config com um elemento
<remove> para remover o módulo de o aplicativo. Vários elementos <remove> podem ser adicionados
para remover vários módulos. Se alterações a web.config forem feitas no servidor, faça imediatamente as
mesmas alterações no arquivo web.config do projeto localmente. Remover um módulo dessa maneira
não afetará o uso do módulo com outros aplicativos no servidor.
<configuration>
<system.webServer>
<modules>
<remove name="MODULE_NAME" />
</modules>
</system.webServer>
</configuration>
Um módulo do IIS também pode ser removido com Appcmd.exe. Forneça o MODULE_NAME e APPLICATION_NAME
no comando:
Appcmd.exe delete module MODULE_NAME /app.name:APPLICATION_NAME
Por exemplo, remova o DynamicCompressionModule do site da Web padrão:
%windir%\system32\inetsrv\appcmd.exe delete module DynamicCompressionModule /app.name:"Default Web Site"
Configuração do módulo mínimo

Os únicos módulos necessários para executar um aplicativo ASP.NET Core são o módulo de Autenticação
Anônima e o Módulo do ASP.NET Core.
O módulo de cache de URI ( UriCacheModule ) permite configuração de site, do IIS para o cache, no nível da URL.
Sem esse módulo, o IIS deve ler e analisar a configuração em cada solicitação, mesmo quando a mesma URL é
solicitada repetidamente. Analisar a configuração em cada solicitação resulta em uma perda de desempenho
significativa. Embora o módulo de cache de URI não seja estritamente necessário para que um aplicativo
ASP.NET Core hospedado seja executado, é recomendável que o módulo de cache de URI seja habilitado para
todas as implantações do ASP.NET Core.
O módulo de cache HTTP ( HttpCacheModule ) implementa o cache de saída do IIS e também a lógica para gravar
itens no cache do HTTP.sys. Sem esse módulo, o conteúdo não é mais armazenado em cache no modo kernel e
perfis de cache são ignorados. Remover o módulo de cache HTTP geralmente tem um efeito adverso sobre o
desempenho e o uso de recursos. Embora o módulo de cache HTTP não seja estritamente necessário para que
um aplicativo ASP.NET Core hospedado seja executado, é recomendável que o módulo de cache de HTTP seja
habilitado para todas as implantações do ASP.NET Core.
Recursos adicionais
Introdução às arquiteturas do IIS: módulos no IIS
Visão geral de módulos do IIS
Personalizando funções e módulos do IIS 7.0
IIS <system.webServer>
Hospedar o ASP.NET Core em um serviço Windows
Por Luke Latham e Tom Dykstra

Um aplicativo ASP.NET Core pode ser hospedado no Windows sem usar o IIS como um Serviço Windows.
Quando hospedado como um Serviço Windows, o aplicativo é iniciado automaticamente após a reinicialização.
Converter um projeto em um serviço Windows

As alterações mínimas a seguir são necessárias para configurar um projeto existente do ASP.NET Core a ser
executado como um serviço:
1. No arquivo de projeto:
Confirme a presença de um RID (Identificador de Tempo de Execução) do Windows ou adicione-a ao
<PropertyGroup> que contém a estrutura de destino:
<PropertyGroup>
<RuntimeIdentifier>win7-x64</RuntimeIdentifier>
</PropertyGroup>
<PropertyGroup>
</PropertyGroup>
<PropertyGroup>
</PropertyGroup>
Para publicar para vários RIDs:

Forneça os RIDs em uma lista delimitada por ponto e vírgula.
Use o nome da propriedade <RuntimeIdentifiers> (plural).
Para obter mais informações, consulte Catálogo de RID do .NET Core.
Adicionar uma referência de pacote para Microsoft.AspNetCore.Hosting.WindowsServices.
2. Faça as seguintes alterações em Program.Main :
Chame host. RunAsService, em vez de host.Run .
Chame UseContentRoot e use um caminho para o local publicado do aplicativo, em vez de
Directory.GetCurrentDirectory() .
{
CreateWebHostBuilder(args).Build().RunAsService();
}

{
var pathToExe = Process.GetCurrentProcess().MainModule.FileName;
var pathToContentRoot = Path.GetDirectoryName(pathToExe);
.ConfigureAppConfiguration((context, config) =>
{
// Configure the app here.
})
.UseContentRoot(pathToContentRoot)
}

{

.UseKestrel()
.Build();
host.RunAsService();
}
3. Publique o aplicativo. Use dotnet publish ou um perfil de publicação do Visual Studio. Ao usar o Visual
Studio, selecione FolderProfile.
Para publicar o aplicativo de exemplo usando as ferramentas da CLI (interface de linha de comando),
execute o comando dotnet publish em um prompt de comando da pasta do projeto. O RID deve ser
especificado na propriedade <RuntimeIdenfifier> (ou <RuntimeIdentifiers> ) do arquivo de projeto. No
exemplo a seguir, o aplicativo é publicado na Configuração de versão para o tempo de execução win7-x64 :
dotnet publish --configuration Release --runtime win7-x64
4. Use a ferramenta de linha de comando sc.exe para criar o serviço. O valor binPath é o caminho para o
executável do aplicativo, que inclui o nome do arquivo executável. O espaço entre o sinal de igual e o
caractere de aspas no início do caminho é necessário.
sc create <SERVICE_NAME> binPath= "<PATH_TO_SERVICE_EXECUTABLE>"
Para um serviço publicado na pasta do projeto, use o caminho para a pasta publish para criar o serviço. No
exemplo a seguir:
O projeto reside na pasta c:\my_services\AspNetCoreService.
O projeto é publicado na configuração Release .
O TFM (Moniker da Estrutura de Destino) é netcoreapp2.1 .
O RID (Identificador de Tempo de Execução) é win7-x64 .
O nome do executável de aplicativo é AspNetCoreService.exe.
O nome do serviço é MyService.
Exemplo:
sc create MyService binPath= "c:\my_services\AspNetCoreService\bin\Release\netcoreapp2.1\win7-

x64\publish\AspNetCoreService.exe"
IMPORTANT
Verifique se existe o espaço entre o argumento binPath= e seu valor.
Para publicar e iniciar o serviço de uma pasta diferente:

Use a opção --output <OUTPUT_DIRECTORY> no comando dotnet publish . Se você usar o Visual
Studio, configure o Local de Destino na página de propriedades da publicação FolderProfile antes de
selecionar o botão Publicar.
Crie o serviço com o comando sc.exe usando o caminho da pasta de saída. Inclua o nome do
executável do serviço no caminho fornecido para binPath .
5. Inicie o serviço com o comando sc start <SERVICE_NAME> .
Para iniciar o serviço de aplicativo de exemplo, use o seguinte comando:
sc start MyService
O comando leva alguns segundos para iniciar o serviço.

6. Para verificar o status do serviço, use o comando sc query <SERVICE_NAME> . O status é relatado como um
dos seguintes valores:
START_PENDING
RUNNING
STOP_PENDING
STOPPED
Use o seguinte comando para verificar o status do serviço de aplicativo de exemplo:
sc query MyService
7. Quando o serviço estiver no estado RUNNING e se o serviço for um aplicativo Web, procure o aplicativo em
seu caminho (por padrão, http://localhost:5000 , que redireciona para https://localhost:5001 ao usar
Middleware de Redirecionamento HTTPS ).
Para o serviço de aplicativo de exemplo, procure o aplicativo em http://localhost:5000 .
8. Interrompa o serviço com o comando sc stop <SERVICE_NAME> .
O comando a seguir interrompe o serviço de aplicativo de exemplo:
sc stop MyService
9. Após um pequeno atraso para interromper um serviço, desinstale o serviço com o comando
sc delete <SERVICE_NAME> .
Verifique o status do serviço de aplicativo de exemplo:
sc query MyService
Quando o serviço de aplicativo de exemplo estiver no estado STOPPED , use o seguinte comando para
desinstalar o serviço de aplicativo de exemplo:
sc delete MyService
Execute o aplicativo fora de um serviço

É mais fácil testar e depurar ao executar fora de um serviço, então é comum adicionar código que chama
RunAsService apenas em determinadas condições. Por exemplo, o aplicativo pode ser executado como um
aplicativo de console com um argumento de linha de comando --console ou se o depurador está anexado:

{
var isService = !(Debugger.IsAttached || args.Contains("--console"));
var builder = CreateWebHostBuilder(args.Where(arg => arg != "--console").ToArray());
if (isService)
{
builder.UseContentRoot(pathToContentRoot);
}
if (isService)
{
}
else
{
host.Run();
}
}

{
})
Porque a configuração do ASP.NET Core requer pares nome-valor para argumentos de linha de comando, a
opção --console é removida antes que os argumentos sejam passados para CreateDefaultBuilder.
NOTE
isService não é passado do Main para o CreateWebHostBuilder , porque a assinatura do CreateWebHostBuilder
deve ser CreateWebHostBuilder(string[]) para que o teste de integração funcione corretamente.
{
var isService = true;
if (Debugger.IsAttached || args.Contains("--console"))
{
isService = false;
}
var pathToContentRoot = Directory.GetCurrentDirectory();
if (isService)
{
pathToContentRoot = Path.GetDirectoryName(pathToExe);
}

.UseKestrel()
.Build();
if (isService)
{
}
else
{
host.Run();
}
}
Manipular eventos de início e de parada

Para tratar eventos OnStarting, OnStarted e OnStopping, faça as seguintes alterações adicionais:
1. Crie uma classe que derive de WebHostService:
internal class CustomWebHostService : WebHostService

{
public CustomWebHostService(IWebHost host) : base(host)
{
}
protected override void OnStarting(string[] args)

{
base.OnStarting(args);
}
protected override void OnStarted()

{
base.OnStarted();
}
protected override void OnStopping()

{
base.OnStopping();
}
}
2. Crie um método de extensão para IWebHost que passe o WebHostService personalizado para
ServiceBase.Run:
public static class WebHostServiceExtensions

{
public static void RunAsCustomService(this IWebHost host)
{
var webHostService = new CustomWebHostService(host);
ServiceBase.Run(webHostService);
}
}
3. Em Program.Main , chame o novo método de extensão, RunAsCustomService , em vez de RunAsService:

{
var isService = !(Debugger.IsAttached || args.Contains("--console"));
var builder = CreateWebHostBuilder(args.Where(arg => arg != "--console").ToArray());
if (isService)
{
builder.UseContentRoot(pathToContentRoot);
}
if (isService)
{
host.RunAsCustomService();
}
else
{
host.Run();
}
}

{
})
NOTE
isService não é passado do Main para o CreateWebHostBuilder , porque a assinatura do
CreateWebHostBuilder deve ser CreateWebHostBuilder(string[]) para que o teste de integração funcione
corretamente.
{
var isService = true;
if (Debugger.IsAttached || args.Contains("--console"))
{
isService = false;
}
var pathToContentRoot = Directory.GetCurrentDirectory();
if (isService)
{
pathToContentRoot = Path.GetDirectoryName(pathToExe);
}

.UseKestrel()
.Build();
if (isService)
{
host.RunAsCustomService();
}
else
{
host.Run();
}
}
Se o código WebHostService personalizado exigir um serviço de injeção de dependência (como um agente),

obtenha-o da propriedade IWebHost.Services:
internal class CustomWebHostService : WebHostService
{
private ILogger _logger;
public CustomWebHostService(IWebHost host) : base(host)

{
_logger = host.Services
.GetRequiredService<ILogger<CustomWebHostService>>();
}
protected override void OnStarting(string[] args)

{
_logger.LogDebug("OnStarting method called.");
base.OnStarting(args);
}
protected override void OnStarted()

{
_logger.LogDebug("OnStarted method called.");
base.OnStarted();
}
protected override void OnStopping()

{
_logger.LogDebug("OnStopping method called.");
base.OnStopping();
}
}

Serviços que interagem com solicitações da Internet ou de uma rede corporativa e estão atrás de um proxy ou de
um balanceador de carga podem exigir configuração adicional. Para obter mais informações, consulte Configure o
ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga.
Configurar o HTTPS
Especifique uma configuração do ponto de extremidade HTTPS do servidor Kestrel.
Diretório atual e a raiz do conteúdo

O diretório de trabalho atual retornado ao chamar Directory.GetCurrentDirectory() de um serviço Windows é a
pasta C:\WINDOWS\system32. A pasta system32 não é um local adequado para armazenar os arquivos de um
serviço (por exemplo, os arquivos de configurações). Use uma das seguintes abordagens para manter e acessar os
arquivos de ativos e de configurações de um serviço com FileConfigurationExtensions.SetBasePath ao usar um
IConfigurationBuilder:
Use o caminho raiz do conteúdo. O IHostingEnvironment.ContentRootPath é o mesmo caminho fornecido para o
argumento binPath quando o serviço é criado. Em vez de usar Directory.GetCurrentDirectory() para criar
caminhos para arquivos de configurações, use o caminho raiz do conteúdo e mantenha os arquivos na raiz do
conteúdo do aplicativo.
Armazene os arquivos em um local adequado no disco. Especifique um caminho absoluto com SetBasePath
para a pasta que contém os arquivos.
Recursos adicionais
Configuração do ponto de extremidade Kestrel (inclui a configuração HTTPS e suporte à SNI)
Host da Web do ASP.NET Core
Por Sourabh Shirhatti

Este guia explica como configurar um ambiente ASP.NET Core pronto para produção em um servidor Ubuntu
16.04. Essas instruções provavelmente funcionarão com versões mais recentes do Ubuntu, mas as instruções
não foram testadas com versões mais recentes.
Para saber mais sobre outras distribuições do Linux compatíveis com o ASP.NET Core, veja Pré-requisitos para
o .NET Core no Linux.
NOTE
Para Ubuntu 14.04, o supervisord é recomendado como uma solução para monitorar o processo do Kestrel. O systemd
não está disponível no Ubuntu 14.04. Para obter instruções Ubuntu 14.04, veja a versão anterior deste tópico.
Este guia:
Coloca um aplicativo ASP.NET Core existente em um servidor proxy reverso.
Configura o servidor proxy reverso para encaminhar solicitações ao servidor Web do Kestrel.
Assegura que o aplicativo Web seja executado na inicialização como um daemon.
Configura uma ferramenta de gerenciamento de processo para ajudar a reiniciar o aplicativo Web.
Pré-requisitos
1. Acesso a um servidor Ubuntu 16.04 com uma conta de usuário padrão com privilégio sudo.
2. Instale o tempo de execução do .NET Core no servidor.
a. Acesse a página Todos os Downloads do .NET Core.
b. Selecione o tempo de execução não de versão prévia mais recente da lista em Tempo de Execução.
c. Selecione e siga as instruções para Ubuntu que correspondem à versão Ubuntu do servidor.
3. Um aplicativo ASP.NET Core existente.
Publicar e copiar o aplicativo

Configurar o aplicativo para um implantação dependente de estrutura.
Execute dotnet publish do ambiente de desenvolvimento para empacotar um aplicativo em um diretório (por
exemplo, bin/Release/<target_framework_moniker>/publish) que pode ser executado no servidor:
dotnet publish --configuration Release
O aplicativo também poderá ser publicado como uma implantação autossuficiente se você preferir não manter
o tempo de execução do .NET Core no servidor.
Copie o aplicativo ASP.NET Core para o servidor usando uma ferramenta que se integre ao fluxo de trabalho
da organização (por exemplo, SCP, SFTP ). É comum para localizar os aplicativos Web no diretório var (por
exemplo, var/www/helloapp).
NOTE
Em um cenário de implantação de produção, um fluxo de trabalho de integração contínua faz o trabalho de publicar o
aplicativo e copiar os ativos para o servidor.
Teste o aplicativo:
1. Na linha de comando, execute o aplicativo: dotnet <app_assembly>.dll .
2. Em um navegador, vá para http://<serveraddress>:<port> para verificar se o aplicativo funciona no Linux
localmente.
Configurar um servidor proxy reverso

Um proxy reverso é uma configuração comum para atender a aplicativos Web dinâmicos. Um proxy reverso
encerra a solicitação HTTP e a encaminha para o aplicativo ASP.NET Core.
Usar um servidor proxy reverso
O Kestrel é excelente para servir conteúdo dinâmico do ASP.NET Core. No entanto, as funcionalidades de
servidor Web não têm tantos recursos quanto servidores como IIS, Apache ou Nginx. Um servidor proxy
reverso pode descarregar trabalho como servir conteúdo estático, armazenar solicitações em cache, compactar
solicitações e terminar SSL do servidor HTTP. Um servidor proxy reverso pode residir em um computador
dedicado ou pode ser implantado junto com um servidor HTTP.
Para os fins deste guia, uma única instância de Nginx é usada. Ela é executada no mesmo servidor, junto com o
servidor HTTP. Com base nos requisitos, uma configuração diferente pode ser escolhida.
Uma vez que as solicitações são encaminhadas pelo proxy reverso, use o Middleware de Cabeçalhos
Encaminhados do pacote Microsoft.AspNetCore.HttpOverrides. O middleware atualiza o Request.Scheme
usando o cabeçalho X-Forwarded-Proto , de forma que URIs de redirecionamento e outras políticas de
segurança funcionam corretamente.
Qualquer componente que dependa do esquema, como autenticação, geração de link, redirecionamentos e
localização geográfica, deverá ser colocado depois de invocar o Middleware de Cabeçalhos Encaminhados.
Como regra geral, o Middleware de Cabeçalhos Encaminhados deve ser executado antes de outro middleware,
exceto middleware de tratamento de erro e de diagnóstico. Essa ordenação garantirá que o middleware conte
com informações de cabeçalhos encaminhadas que podem consumir os valores de cabeçalho para
processamento.
Invoque o método UseForwardedHeaders em Startup.Configure antes de chamar UseAuthentication ou um
middleware de esquema de autenticação semelhante. Configure o middleware para encaminhar os cabeçalhos
X-Forwarded-For e X-Forwarded-Proto :
app.UseForwardedHeaders(new ForwardedHeadersOptions
{
ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
});
Invoque o método UseForwardedHeaders em Startup.Configure antes de chamar UseIdentity e

UseFacebookAuthentication ou um middleware de esquema de autenticação semelhante. Configure o
middleware para encaminhar os cabeçalhos X-Forwarded-For e X-Forwarded-Proto :
{
});
app.UseIdentity();
app.UseFacebookAuthentication(new FacebookOptions()
{
AppId = Configuration["Authentication:Facebook:AppId"],
AppSecret = Configuration["Authentication:Facebook:AppSecret"]
});
Se nenhum ForwardedHeadersOptions for especificado para o middleware, os cabeçalhos padrão para

encaminhar serão None .
Somente os proxies em execução no localhost (127.0.0.1, [::1]) são confiáveis por padrão. Se outros proxies ou
redes confiáveis em que a organização trata solicitações entre a Internet e o servidor Web, adicione-os à lista de
KnownProxies ou KnownNetworks com ForwardedHeadersOptions. O exemplo a seguir adiciona um servidor
proxy confiável no endereço IP 10.0.0.100 ao Middleware de cabeçalhos encaminhados KnownProxies em
services.Configure<ForwardedHeadersOptions>(options =>
{
options.KnownProxies.Add(IPAddress.Parse("10.0.0.100"));
});
Para obter mais informações, consulte Configure o ASP.NET Core para trabalhar com servidores proxy e
balanceadores de carga.
Instalar o Nginx
Use apt-get para instalar o Nginx. O instalador cria um script de inicialização systemd que executa o Nginx
como daemon na inicialização do sistema. Siga as instruções de instalação para o Ubuntu em Nginx: pacotes
Debian/Ubuntu oficiais.
NOTE
Se módulos Nginx opcionais forem exigidos, poderá haver necessidade de criar o Nginx da origem.
Já que Nginx foi instalado pela primeira vez, inicie-o explicitamente executando:
sudo service nginx start
Verifique se um navegador exibe a página de aterrissagem padrão do Nginx. A página de aterrissagem é

acessível em http://<server_IP_address>/index.nginx-debian.html .
Configurar o Nginx
Para configurar o Nginx como um proxy inverso para encaminhar solicitações para o nosso aplicativo ASP.NET
Core, modifique /etc/nginx/sites-available/default. Abra-o em um editor de texto arquivo e substitua o
conteúdo pelo mostrado a seguir:
server {
listen 80;
server_name example.com *.example.com;
location / {
proxy_pass http://localhost:5000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection keep-alive;
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
Quando nenhum server_name corresponde, o Nginx usa o servidor padrão. Se nenhum servidor padrão é
definido, o primeiro servidor no arquivo de configuração é o servidor padrão. Como prática recomendada,
adicione um servidor padrão específico que retorna um código de status 444 no arquivo de configuração. Um
exemplo de configuração de servidor padrão é:
server {
listen 80 default_server;
# listen [::]:80 default_server deferred;
return 444;
}
Com o servidor padrão e o arquivo de configuração anterior, o Nginx aceita tráfego público na porta 80 com
um cabeçalho de host example.com ou *.example.com . Solicitações que não correspondam a esses hosts não
serão encaminhadas para o Kestrel. O Nginx encaminha as solicitações correspondentes para o Kestrel em
http://localhost:5000 . Veja Como o nginx processa uma solicitação para obter mais informações. Para alterar
o IP/porta do Kestrel, veja Kestrel: configuração de ponto de extremidade.
WARNING
Falha ao especificar uma diretiva server_name expõe seu aplicativo para vulnerabilidades de segurança. Associações de
curinga de subdomínio (por exemplo, *.example.com ) não oferecerão esse risco de segurança se você controlar o
domínio pai completo (em vez de *.com , o qual é vulnerável). Veja rfc7230 section-5.4 para obter mais informações.
Quando a configuração Nginx é estabelecida, execute sudo nginx -t para verificar a sintaxe dos arquivos de
configuração. Se o teste do arquivo de configuração for bem-sucedido, você poderá forçar o Nginx a
acompanhar as alterações executando sudo nginx -s reload .
Para executar o aplicativo diretamente no servidor:
1. Navegue até o diretório do aplicativo.
2. Execute o aplicativo: dotnet <app_assembly.dll> , em que app_assembly.dll é o nome do arquivo do
assembly do aplicativo.
Se o aplicativo for executado no servidor, mas não responder pela Internet, verifique o firewall do servidor e
confirme que a porta 80 está aberta. Se você estiver usando uma VM do Azure Ubuntu, adicione uma regra
NSG (Grupo de Segurança de Rede) que permite tráfego de entrada na porta 80. Não é necessário habilitar
uma regra de saída da porta 80, uma vez que o tráfego de saída é concedido automaticamente quando a regra
de entrada é habilitada.
Quando terminar de testar o aplicativo, encerre o aplicativo com Ctrl+C no prompt de comando.
Monitoramento o aplicativo
O servidor agora está configurado para encaminhar solicitações feitas a http://<serveraddress>:80 ao
aplicativo ASP.NET Core em execução no Kestrel em http://127.0.0.1:5000 . No entanto, o Nginx não está
configurado para gerenciar o processo do Kestrel. É possível usar o systemd para criar um arquivo de serviço
para iniciar e monitorar o aplicativo Web subjacente. systemd é um sistema de inicialização que fornece muitos
recursos poderosos para iniciar, parar e gerenciar processos.
Criar o arquivo de serviço
Crie o arquivo de definição de serviço:
sudo nano /etc/systemd/system/kestrel-helloapp.service
A seguir, um exemplo de arquivo de serviço para o aplicativo:
[Unit]
Description=Example .NET Web API App running on Ubuntu
[Service]
WorkingDirectory=/var/www/helloapp
ExecStart=/usr/bin/dotnet /var/www/helloapp/helloapp.dll
Restart=always
# Restart service after 10 seconds if the dotnet service crashes:
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=dotnet-example
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false
[Install]
WantedBy=multi-user.target
Se o usuário www -data não é usado pela configuração, o usuário definido aqui deve ser criado primeiro e a
propriedade adequada dos arquivos deve ser concedida a ele.
Use TimeoutStopSec para configurar a duração do tempo de espera para o aplicativo desligar depois de receber
o sinal de interrupção inicial. Se o aplicativo não desligar nesse período, o SIGKILL será emitido para encerrá-
lo. Forneça o valor como segundos sem unidade (por exemplo, 150 ), um valor de duração (por exemplo,
2min 30s ) ou infinity para desabilitar o tempo limite. TimeoutStopSec é revertido para o valor padrão de
DefaultTimeoutStopSec no arquivo de configuração do gerenciador (systemd -system.conf, system.conf.d,
systemd -user.conf e user.conf.d). O tempo limite padrão para a maioria das distribuições é de 90 segundos.
# The default value is 90 seconds for most distributions.

TimeoutStopSec=90
O Linux tem um sistema de arquivos que diferencia maiúsculas de minúsculas. Definir

ASPNETCORE_ENVIRONMENT para "Production" resulta em uma pesquisa pelo arquivo de configuração
appsettings.Production.json, e não appsettings.production.json.
Alguns valores (por exemplo, cadeias de conexão de SQL ) devem ser escapadas para que os provedores de
configuração leiam as variáveis de ambiente. Use o seguinte comando para gerar um valor corretamente com
caracteres de escape para uso no arquivo de configuração:
systemd-escape "<value-to-escape>"
Salve o arquivo e habilite o serviço.
sudo systemctl enable kestrel-helloapp.service
Inicie o serviço e verifique se ele está em execução.
sudo systemctl start kestrel-helloapp.service

sudo systemctl status kestrel-helloapp.service
● kestrel-helloapp.service - Example .NET Web API App running on Ubuntu

Loaded: loaded (/etc/systemd/system/kestrel-helloapp.service; enabled)
Active: active (running) since Thu 2016-10-18 04:09:35 NZDT; 35s ago
Main PID: 9021 (dotnet)
CGroup: /system.slice/kestrel-helloapp.service
└─9021 /usr/local/bin/dotnet /var/www/helloapp/helloapp.dll
Com o proxy reverso configurado e o Kestrel gerenciado por meio de systemd, o aplicativo Web está
totalmente configurado e pode ser acessado em um navegador no computador local em http://localhost . Ele
também é acessível por meio de um computador remoto, bloqueando qualquer firewall que o possa estar
bloqueando. Inspecionando os cabeçalhos de resposta, o cabeçalho Server mostra o aplicativo ASP.NET Core
sendo servido pelo Kestrel.
HTTP/1.1 200 OK
Date: Tue, 11 Oct 2016 16:22:23 GMT
Server: Kestrel
Keep-Alive: timeout=5, max=98
Connection: Keep-Alive
Transfer-Encoding: chunked
Exibindo logs
Já que o aplicativo Web usando Kestrel é gerenciado usando systemd , todos os eventos e os processos são
registrados em um diário centralizado. No entanto, esse diário contém todas as entradas para todos os serviços
e processos gerenciados pelo systemd . Para exibir os itens específicos de kestrel-helloapp.service , use o
seguinte comando:
sudo journalctl -fu kestrel-helloapp.service
Para obter mais filtragem, opções de hora como --since today , --until 1 hour ago ou uma combinação delas,
pode reduzir a quantidade de entradas retornadas.
sudo journalctl -fu kestrel-helloapp.service --since "2016-10-18" --until "2016-10-18 04:00"
Proteção de dados
A pilha de proteção de dados do ASP.NET Core é usada por vários middlewares do ASP.NET Core, incluindo o
middleware de autenticação (por exemplo, o middleware de cookie) e as proteções de CSRF (solicitação
intersite forjada). Mesmo se as APIs de Proteção de Dados não forem chamadas pelo código do usuário, a
proteção de dados deverá ser configurada para criar um repositório de chaves criptográfico persistente. Se a
proteção de dados não estiver configurada, as chaves serão mantidas na memória e descartadas quando o
aplicativo for reiniciado.
Para configurar a proteção de dados de modo que ela mantenha e criptografe o token de autenticação, consulte:
Provedores de armazenamento de chaves no ASP.NET Core
Chave de criptografia em repouso no ASP.NET Core
Protegendo o aplicativo
Habilitar AppArmor
O LSM (Módulos de Segurança do Linux) é uma estrutura que é parte do kernel do Linux desde o Linux 2.6. O
LSM dá suporte a diferentes implementações de módulos de segurança. O AppArmor é um LSM que
implementa um sistema de controle de acesso obrigatório que permite restringir o programa a um conjunto
limitado de recursos. Verifique se o AppArmor está habilitado e configurado corretamente.
Configurando o firewall
Feche todas as portas externas que não estão em uso. Firewall descomplicado (ufw ) fornece um front-end para
iptables fornecendo uma interface de linha de comando para configurar o firewall.
WARNING
Um firewall impedirá o acesso a todo o sistema se não ele estiver configurado corretamente. Se houver falha ao
especificar a porta SSH correta, você será bloqueado do sistema se estiver usando o SSH para se conectar a ele. A porta
padrão é a 22. Para obter mais informações, consulte a introdução ao ufw e o manual.
Instale o ufw e configure-o para permitir o tráfego em todas as portas necessárias.
sudo apt-get install ufw
sudo ufw allow 22/tcp

sudo ufw enable
Protegendo o Nginx
Alterar o nome da resposta do Nginx
Edite src/http/ngx_http_header_filter_module.c:
static char ngx_http_server_string[] = "Server: Web Server" CRLF;

static char ngx_http_server_full_string[] = "Server: Web Server" CRLF;
Configurar opções
Configure o servidor com os módulos adicionais necessários. Considere usar um firewall de aplicativo Web
como ModSecurity para fortalecer o aplicativo.
Configurar o SSL
Configure o servidor para escutar tráfego HTTPS na porta 443 especificando um certificado válido
emitido por uma AC (autoridade de certificação) confiável.
Aprimore a segurança, empregando algumas das práticas descritas no arquivo /etc/nginx/nginx.conf a
seguir. Exemplos incluem a escolha de uma criptografia mais forte e o redirecionamento de todo o
tráfego por meio de HTTP para HTTPS.
A adição de um cabeçalho HTTP Strict-Transport-Security (HSTS ) garante que todas as próximas
solicitações feitas pelo cliente sejam por HTTPS.
Não adicione o cabeçalho HSTS ou escolha um max-age apropriado se desejar desabilitar o SSL
futuramente.
Adicione o arquivo de configuração /etc/nginx/proxy.conf:
proxy_redirect off;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 10m;
client_body_buffer_size 128k;
proxy_connect_timeout 90;
proxy_send_timeout 90;
proxy_read_timeout 90;
proxy_buffers 32 4k;
Edite o arquivo de configuração /etc/nginx/nginx.conf. O exemplo contém ambas as seções http e server em
um arquivo de configuração.
http {
include /etc/nginx/proxy.conf;
limit_req_zone $binary_remote_addr zone=one:10m rate=5r/s;
server_tokens off;
sendfile on;
keepalive_timeout 29; # Adjust to the lowest possible value that makes sense for your use case.
client_body_timeout 10; client_header_timeout 10; send_timeout 10;
upstream hellomvc{
server localhost:5000;
}
server {
listen *:80;
add_header Strict-Transport-Security max-age=15768000;
return 301 https://$host$request_uri;
}
server {
listen *:443 ssl;
server_name example.com;
ssl_certificate /etc/ssl/certs/testCert.crt;
ssl_certificate_key /etc/ssl/certs/testCert.key;
ssl_protocols TLSv1.1 TLSv1.2;
ssl_prefer_server_ciphers on;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_ecdh_curve secp384r1;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
ssl_stapling on; #ensure your cert is capable
ssl_stapling_verify on; #ensure your cert is capable
add_header Strict-Transport-Security "max-age=63072000; includeSubdomains; preload";

add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
#Redirects all traffic

location / {
proxy_pass http://hellomvc;
limit_req zone=one burst=10 nodelay;
}
}
}
Proteger o Nginx de clickjacking

Clickjacking, também conhecido como um ataque por inferência na interface do usuário, é um ataque mal-
intencionado em que o visitante do site é levado a clicar em um link ou botão em uma página diferente daquela
que está visitando atualmente. Use X-FRAME-OPTIONS para proteger o site.
Para atenuar ataques de clickjacking:
1. Edite o arquivo nginx.conf:
sudo nano /etc/nginx/nginx.conf
Adicione a linha add_header X-Frame-Options "SAMEORIGIN"; .

2. Salve o arquivo.
3. Reinicie o Nginx.
Detecção de tipo MIME
Esse cabeçalho evita que a maioria dos navegadores faça detecção MIME de uma resposta distante do tipo de
conteúdo declarado, visto que o cabeçalho instrui o navegador para não substituir o tipo de conteúdo de
resposta. Com a opção nosniff , se o servidor informa que o conteúdo é "text/html", o navegador renderiza-a
como "text/html".
Edite o arquivo nginx.conf:
sudo nano /etc/nginx/nginx.conf
Adicione a linha add_header X-Content-Type-Options "nosniff"; e salve o arquivo, depois reinicie o Nginx.
Recursos adicionais
Pré-requisitos para o .NET Core no Linux
Nginx: versões binárias: pacotes Debian/Ubuntu oficiais
NGINX: usando o cabeçalho Encaminhado
Por Shayne Boyer

Usando este guia, aprenda como configurar o Apache como um servidor proxy reverso no CentOS 7 para
redirecionar o tráfego HTTP para um aplicativo Web ASP.NET Core em execução no Kestrel. A extensão
mod_proxy e os módulos relacionados criam o proxy reverso do servidor.
Pré-requisitos
1. Servidor que executa o CentOS 7 com uma conta de usuário padrão com privilégio sudo.
2. Instale o tempo de execução do .NET Core no servidor.
a. Acesse a página Todos os Downloads do .NET Core.
b. Selecione o tempo de execução não de versão prévia mais recente da lista em Tempo de Execução.
c. Selecione e siga as instruções para CentOS/Oracle.
3. Um aplicativo ASP.NET Core existente.
Publicar e copiar o aplicativo

Configurar o aplicativo para um implantação dependente de estrutura.
Execute dotnet publish do ambiente de desenvolvimento para empacotar um aplicativo em um diretório (por
exemplo, bin/Release/<target_framework_moniker>/publish) que pode ser executado no servidor:
dotnet publish --configuration Release
O aplicativo também poderá ser publicado como uma implantação autossuficiente se você preferir não manter
o tempo de execução do .NET Core no servidor.
Copie o aplicativo ASP.NET Core para o servidor usando uma ferramenta que se integre ao fluxo de trabalho
da organização (por exemplo, SCP, SFTP ). É comum para localizar os aplicativos Web no diretório var (por
exemplo, var/www/helloapp).
NOTE
Em um cenário de implantação de produção, um fluxo de trabalho de integração contínua faz o trabalho de publicar o
aplicativo e copiar os ativos para o servidor.
Configurar um servidor proxy

Um proxy reverso é uma configuração comum para atender a aplicativos Web dinâmicos. O proxy reverso
encerra a solicitação HTTP e a encaminha para o aplicativo ASP.NET.
Um servidor proxy é aquele que encaminha as solicitações de cliente para outro servidor, em vez de atendê-las
por conta própria. Um proxy reverso encaminha para um destino fixo, normalmente, em nome de clientes
arbitrários. Neste guia, o Apache é configurado como o proxy reverso em execução no mesmo servidor em que
o Kestrel está servindo o aplicativo ASP.NET Core.
Uma vez que as solicitações são encaminhadas pelo proxy reverso, use o Middleware de Cabeçalhos
Encaminhados do pacote Microsoft.AspNetCore.HttpOverrides. O middleware atualiza o Request.Scheme
usando o cabeçalho X-Forwarded-Proto , de forma que URIs de redirecionamento e outras políticas de
segurança funcionam corretamente.
Qualquer componente que dependa do esquema, como autenticação, geração de link, redirecionamentos e
localização geográfica, deverá ser colocado depois de invocar o Middleware de Cabeçalhos Encaminhados.
Como regra geral, o Middleware de Cabeçalhos Encaminhados deve ser executado antes de outro middleware,
exceto middleware de tratamento de erro e de diagnóstico. Essa ordenação garantirá que o middleware conte
com informações de cabeçalhos encaminhadas que podem consumir os valores de cabeçalho para
processamento.
Invoque o método UseForwardedHeaders em Startup.Configure antes de chamar UseAuthentication ou um
middleware de esquema de autenticação semelhante. Configure o middleware para encaminhar os cabeçalhos
X-Forwarded-For e X-Forwarded-Proto :
{
});
Invoque o método UseForwardedHeaders em Startup.Configure antes de chamar UseIdentity e

UseFacebookAuthentication ou um middleware de esquema de autenticação semelhante. Configure o
middleware para encaminhar os cabeçalhos X-Forwarded-For e X-Forwarded-Proto :
{
});
app.UseIdentity();
app.UseFacebookAuthentication(new FacebookOptions()
{
AppId = Configuration["Authentication:Facebook:AppId"],
AppSecret = Configuration["Authentication:Facebook:AppSecret"]
});
Se nenhum ForwardedHeadersOptions for especificado para o middleware, os cabeçalhos padrão para

encaminhar serão None .
Somente os proxies em execução no localhost (127.0.0.1, [::1]) são confiáveis por padrão. Se outros proxies ou
redes confiáveis em que a organização trata solicitações entre a Internet e o servidor Web, adicione-os à lista de
KnownProxies ou KnownNetworks com ForwardedHeadersOptions. O exemplo a seguir adiciona um servidor
proxy confiável no endereço IP 10.0.0.100 ao Middleware de cabeçalhos encaminhados KnownProxies em
{
});
Para obter mais informações, consulte Configure o ASP.NET Core para trabalhar com servidores proxy e
balanceadores de carga.
Instalar o Apache
Atualize os pacotes CentOS para as respectivas versões estáveis mais recentes:
sudo yum update -y
Instale o servidor Web do Apache no CentOS com um único comando yum :
sudo yum -y install httpd mod_ssl
Saída de exemplo depois de executar o comando:
Downloading packages:
httpd-2.4.6-40.el7.centos.4.x86_64.rpm | 2.7 MB 00:00:01
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction
Installing : httpd-2.4.6-40.el7.centos.4.x86_64 1/1
Verifying : httpd-2.4.6-40.el7.centos.4.x86_64 1/1
Installed:
httpd.x86_64 0:2.4.6-40.el7.centos.4
Complete!
NOTE
Neste exemplo, o resultado reflete httpd.86_64, pois a versão do CentOS 7 é de 64 bits. Para verificar o local em que o
Apache está instalado, execute whereis httpd em um prompt de comando.
Configurar o Apache
Os arquivos de configuração do Apache estão localizados no diretório /etc/httpd/conf.d/ . Qualquer arquivo
com a extensão .conf é processado em ordem alfabética, além dos arquivos de configuração do módulo em
/etc/httpd/conf.modules.d/ , que contém todos os arquivos de configuração necessários para carregar os
módulos.
Crie um arquivo de configuração chamado helloapp.conf para o aplicativo:
<VirtualHost *:*>
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
<VirtualHost *:80>
ProxyPreserveHost On
ProxyPass / http://127.0.0.1:5000/
ProxyPassReverse / http://127.0.0.1:5000/
ServerName www.example.com
ServerAlias *.example.com
ErrorLog ${APACHE_LOG_DIR}helloapp-error.log
CustomLog ${APACHE_LOG_DIR}helloapp-access.log common
</VirtualHost>
O bloco VirtualHost pode aparecer várias vezes, em um ou mais arquivos em um servidor. No arquivo de
configuração anterior, o Apache aceita tráfego público na porta 80. O domínio www.example.com está sendo
atendido e o alias *.example.com é resolvido para o mesmo site. Veja Suporte a host virtual baseado em nome
para obter mais informações. As solicitações passadas por proxy na raiz para a porta 5000 do servidor em
127.0.0.1. Para a comunicação bidirecional, ProxyPass e ProxyPassReverse são necessários. Para alterar o
IP/porta do Kestrel, veja Kestrel: configuração de ponto de extremidade.
WARNING
Falha ao especificar uma diretiva ServerName no bloco VirtualHost expõe seu aplicativo para vulnerabilidades de
segurança. Associações de curinga de subdomínio (por exemplo, *.example.com ) não oferecerão esse risco de
segurança se você controlar o domínio pai completo (em vez de *.com , o qual é vulnerável). Veja rfc7230 section-5.4
para obter mais informações.
O registro em log pode ser configurado por VirtualHost usando diretivas ErrorLog e CustomLog . ErrorLog é
o local em que o servidor registrará em log os erros, enquanto CustomLog define o nome de arquivo e o
formato do arquivo de log. Nesse caso, esse é o local em que as informações de solicitação são registradas em
log. Há uma linha para cada solicitação.
Salve o arquivo e teste a configuração. Se tudo passar, a resposta deverá ser Syntax [OK] .
sudo service httpd configtest
Reinicie o Apache:
sudo systemctl restart httpd

sudo systemctl enable httpd
Monitoramento o aplicativo
O Apache agora está configurado para encaminhar solicitações feitas a http://localhost:80 para o aplicativo
ASP.NET Core em execução no Kestrel em http://127.0.0.1:5000 . No entanto, o Apache não está configurado
para gerenciar o processo do Kestrel. Use systemd e crie um arquivo de serviço para iniciar e monitorar o
aplicativo Web subjacente. systemd é um sistema de inicialização que fornece muitos recursos poderosos para
iniciar, parar e gerenciar processos.
Criar o arquivo de serviço
Crie o arquivo de definição de serviço:
sudo nano /etc/systemd/system/kestrel-helloapp.service
Eis um exemplo de arquivo de serviço para o aplicativo:

[Unit]
Description=Example .NET Web API App running on CentOS 7
[Service]
WorkingDirectory=/var/www/helloapp
ExecStart=/usr/local/bin/dotnet /var/www/helloapp/helloapp.dll
Restart=always
# Restart service after 10 seconds if the dotnet service crashes:
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=dotnet-example
User=apache
Environment=ASPNETCORE_ENVIRONMENT=Production
[Install]
WantedBy=multi-user.target
Se o usuário apache não for usado pela configuração, o usuário precisará ser criado primeiro e a propriedade
adequada dos arquivos precisará ser concedida a ele.
Use TimeoutStopSec para configurar a duração do tempo de espera para o aplicativo desligar depois de receber
o sinal de interrupção inicial. Se o aplicativo não desligar nesse período, o SIGKILL será emitido para encerrá-
lo. Forneça o valor como segundos sem unidade (por exemplo, 150 ), um valor de duração (por exemplo,
2min 30s ) ou infinity para desabilitar o tempo limite. TimeoutStopSec é revertido para o valor padrão de
DefaultTimeoutStopSec no arquivo de configuração do gerenciador (systemd -system.conf, system.conf.d,
systemd -user.conf e user.conf.d). O tempo limite padrão para a maioria das distribuições é de 90 segundos.
# The default value is 90 seconds for most distributions.

TimeoutStopSec=90
Alguns valores (por exemplo, cadeias de conexão de SQL ) devem ser escapadas para que os provedores de
configuração leiam as variáveis de ambiente. Use o seguinte comando para gerar um valor corretamente com
caracteres de escape para uso no arquivo de configuração:
systemd-escape "<value-to-escape>"
Salve o arquivo e habilite o serviço:
sudo systemctl enable kestrel-helloapp.service
Inicie o serviço e verifique se ele está em execução:
sudo systemctl start kestrel-helloapp.service

sudo systemctl status kestrel-helloapp.service
● kestrel-helloapp.service - Example .NET Web API App running on CentOS 7

Loaded: loaded (/etc/systemd/system/kestrel-helloapp.service; enabled)
Active: active (running) since Thu 2016-10-18 04:09:35 NZDT; 35s ago
Main PID: 9021 (dotnet)
CGroup: /system.slice/kestrel-helloapp.service
└─9021 /usr/local/bin/dotnet /var/www/helloapp/helloapp.dll
Com o proxy reverso configurado e o Kestrel gerenciado por meio de systemd, o aplicativo Web está totalmente
configurado e pode ser acessado em um navegador no computador local em http://localhost . Inspecionando
os cabeçalhos de resposta, o cabeçalho Server indica que o aplicativo ASP.NET Core é servido pelo Kestrel:
HTTP/1.1 200 OK
Date: Tue, 11 Oct 2016 16:22:23 GMT
Server: Kestrel
Keep-Alive: timeout=5, max=98
Connection: Keep-Alive
Transfer-Encoding: chunked
Exibindo logs
Já que o aplicativo Web usando Kestrel é gerenciado usando systemd, os eventos e os processos são
registrados em um diário centralizado. No entanto, esse diário contém todas as entradas para todos os serviços
e processos gerenciados por systemd. Para exibir os itens específicos de kestrel-helloapp.service , use o
seguinte comando:
sudo journalctl -fu kestrel-helloapp.service
Para filtragem de hora, especifique opções de tempo com o comando. Por exemplo, use --since today para
filtrar o dia atual ou --until 1 hour ago para ver as entradas da hora anterior. Para obter mais informações,
confira a página de manual para journalctl.
sudo journalctl -fu kestrel-helloapp.service --since "2016-10-18" --until "2016-10-18 04:00"
Proteção de dados
A pilha de proteção de dados do ASP.NET Core é usada por vários middlewares do ASP.NET Core, incluindo o
middleware de autenticação (por exemplo, o middleware de cookie) e as proteções de CSRF (solicitação
intersite forjada). Mesmo se as APIs de Proteção de Dados não forem chamadas pelo código do usuário, a
proteção de dados deverá ser configurada para criar um repositório de chaves criptográfico persistente. Se a
proteção de dados não estiver configurada, as chaves serão mantidas na memória e descartadas quando o
aplicativo for reiniciado.
Para configurar a proteção de dados de modo que ela mantenha e criptografe o token de autenticação, consulte:
Protegendo o aplicativo
Configurar o firewall
Firewalld é um daemon dinâmico para gerenciar o firewall com suporte para zonas de rede. Portas e filtragem
de pacote ainda podem ser gerenciados pelo iptables. Firewalld deve ser instalado por padrão. yum pode ser
usado para instalar o pacote ou verificar se ele está instalado.
sudo yum install firewalld -y

Use firewalld para abrir somente as portas necessárias para o aplicativo. Nesse caso, as portas 80 e 443 são
usadas. Os comandos a seguir definem permanentemente as portas 80 e 443 para estarem abertas:
sudo firewall-cmd --add-port=80/tcp --permanent

sudo firewall-cmd --add-port=443/tcp --permanent
Recarregue as configurações de firewall. Verifique os serviços e as portas disponíveis na zona padrão. As

opções estão disponíveis por meio da inspeção de firewall-cmd -h .
sudo firewall-cmd --reload

sudo firewall-cmd --list-all
public (default, active)

interfaces: eth0
sources:
services: dhcpv6-client
ports: 443/tcp 80/tcp
masquerade: no
forward-ports:
icmp-blocks:
rich rules:
Configuração do SSL
Para configurar o Apache para SSL, o módulo mod_ssl é usado. Quando o módulo httpd foi instalado, o
módulo mod_ssl também foi instalado. Se ele não foi instalado, use yum para adicioná-lo à configuração.
sudo yum install mod_ssl
Para impor o SSL, instale o módulo mod_rewrite para habilitar a regravação de URL:
sudo yum install mod_rewrite
Modifique o arquivo helloapp.conf para habilitar a regravação de URL e proteger a comunicação na porta 443:
<VirtualHost *:*>
</VirtualHost>
<VirtualHost *:80>
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
</VirtualHost>
<VirtualHost *:443>
ProxyPreserveHost On
ProxyPass / http://127.0.0.1:5000/
ErrorLog /var/log/httpd/helloapp-error.log
CustomLog /var/log/httpd/helloapp-access.log common
SSLEngine on
SSLProtocol all -SSLv2
SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:!RC4+RSA:+HIGH:+MEDIUM:!LOW:!RC4
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
</VirtualHost>
NOTE
Este exemplo usa um certificado gerado localmente. SSLCertificateFile deve ser o arquivo de certificado primário para o
nome de domínio. SSLCertificateKeyFile deve ser o arquivo de chave gerado quando o CSR é criado.
SSLCertificateChainFile deve ser o arquivo de certificado intermediário (se houver) fornecido pela autoridade de
certificação.
Salve o arquivo e teste a configuração:
sudo service httpd configtest
Reinicie o Apache:
sudo systemctl restart httpd
Sugestões adicionais do Apache

Cabeçalhos adicionais
Para proteção contra ataques mal-intencionados, há alguns cabeçalhos que devem ser modificados ou
adicionados. Verifique se o módulo mod_headers está instalado:
sudo yum install mod_headers
Proteger o Apache contra ataques de clickjacking

Clickjacking, também conhecido como um ataque por inferência na interface do usuário, é um ataque mal-
intencionado em que o visitante do site é levado a clicar em um link ou botão em uma página diferente daquela
que está visitando atualmente. Use X-FRAME-OPTIONS para proteger o site.
Para atenuar ataques de clickjacking:
1. Edite o arquivo httpd.conf:
sudo nano /etc/httpd/conf/httpd.conf
Adicione a linha Header append X-FRAME-OPTIONS "SAMEORIGIN" .

2. Salve o arquivo.
3. Reinicie o Apache.
Detecção de tipo MIME
O cabeçalho impedirá o Internet Explorer de farejar por MIME (determinar o
X-Content-Type-Options
Content-Type de um arquivo com base no conteúdo do arquivo). Se o servidor define o cabeçalho
Content-Type para text/html com a opção nosniff definida, o Internet Explorer renderiza o conteúdo como
text/html , independentemente do conteúdo do arquivo.
Edite o arquivo httpd.conf:
sudo nano /etc/httpd/conf/httpd.conf
Adicione a linha Header set X-Content-Type-Options "nosniff" . Salve o arquivo. Reinicie o Apache.
Balanceamento de carga
Este exemplo mostra como instalar e configurar o Apache no CentOS 7 e no Kestrel no mesmo computador da
instância. Para não ter um ponto único de falha, o uso de mod_proxy_balancer e a modificação do VirtualHost
permitiriam o gerenciamento de várias instâncias dos aplicativos Web protegidos pelo servidor proxy do
Apache.
sudo yum install mod_proxy_balancer
No arquivo de configuração mostrado abaixo, uma instância adicional do helloapp é configurada para ser
executada na porta 5001. A seção Proxy é definida com uma configuração de balanceador com dois membros
para balancear carga de byrequests.
<VirtualHost *:*>
</VirtualHost>
<VirtualHost *:80>
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
</VirtualHost>
<VirtualHost *:443>
ProxyPass / balancer://mycluster/
<Proxy balancer://mycluster>
BalancerMember http://127.0.0.1:5000
BalancerMember http://127.0.0.1:5001
ProxySet lbmethod=byrequests
</Proxy>
<Location />
SetHandler balancer
</Location>
ErrorLog /var/log/httpd/helloapp-error.log
CustomLog /var/log/httpd/helloapp-access.log common
SSLEngine on
SSLProtocol all -SSLv2
SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:!RC4+RSA:+HIGH:+MEDIUM:!LOW:!RC4
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
</VirtualHost>
Limites de taxa
Usando mod_ratelimit, que está incluído no módulo httpd, a largura de banda de clientes pode ser limitada:
sudo nano /etc/httpd/conf.d/ratelimit.conf
O arquivo de exemplo limita a largura de banda a 600 KB/s no local raiz:
<IfModule mod_ratelimit.c>
<Location />
SetOutputFilter RATE_LIMIT
SetEnv rate-limit 600
</Location>
</IfModule>
Recursos adicionais
Pré-requisitos para o .NET Core no Linux
Hospedar o ASP.NET Core em contêineres do
Docker
Os artigos a seguir estão disponíveis para saber mais sobre como hospedar aplicativos ASP.NET Core no
Docker:
Introdução aos contêineres e ao Docker
Veja como o uso de contêineres é uma abordagem de desenvolvimento de software na qual um aplicativo ou
serviço, suas dependências e sua configuração são empacotados juntos como uma imagem de contêiner. A
imagem pode ser testada e, em seguida, implantada em um host.
O que é o Docker?
Descubra como o Docker é um projeto de software livre para automatizar a implantação de aplicativos como
contêineres autossuficientes portáteis que podem ser executados na nuvem ou localmente.
Terminologia do Docker
Aprenda termos e definições para a tecnologia do Docker.
Registros, imagens e contêineres do Docker
Descubra como imagens de contêiner do Docker são armazenadas em um registro de imagem para implantação
consistente entre ambientes.
Compilar imagens do Docker para Aplicativos .NET Core
Saiba como criar um aplicativo ASP.NET Core e colocá-lo no Docker. Explore imagens do Docker mantidas pela
Microsoft e examine os casos de uso.
Ferramentas do Visual Studio para Docker
Descubra como o Visual Studio 2017 permite a criação, depuração e execução de aplicativos ASP.NET Core
direcionados ao .NET Framework ou ao .NET Core no Docker para Windows. Contêineres do Windows e do
Linux são compatíveis.
Publicar em uma imagem do Docker
Saiba como usar a extensão Ferramentas do Visual Studio para Docker para implantar um aplicativo do ASP.NET
Core para um host Docker no Azure usando o PowerShell.
Configuração adicional pode ser necessária para aplicativos hospedados atrás de servidores proxy e
balanceadores de carga. Passar solicitações por meio de um proxy geralmente oculta informações sobre a
solicitação original, como o esquema e o IP de cliente. Talvez seja necessário encaminhar manualmente algumas
informações sobre a solicitação para o aplicativo.
Ferramentas do Visual Studio para Docker com
ASP.NET Core
O Visual Studio 2017 é compatível com a criação, depuração e execução de aplicativos do ASP.NET Core em
contêineres direcionados ao .Net Core. Contêineres do Windows e do Linux são compatíveis.
Pré-requisitos
Docker para Windows
O Visual Studio 2017 com a carga de trabalho Desenvolvimento de multiplataforma do .NET Core
Instalação e configuração
Para a instalação do Docker, primeiro examine as informações em Docker for Windows: What to know before you
install (Docker para Windows: o que saber antes de instalar). Em seguida, instale o Docker for Windows.
As Unidades Compartilhadas do Docker para Windows devem ser configuradas para dar suporte ao
mapeamento do volume e à depuração. Clique com o botão direito do mouse no ícone do Docker na Bandeja do
Sistema, selecione Configurações e selecione Unidades Compartilhadas. Selecione a unidade em que o Docker
armazena arquivos. Clique em Aplicar.
TIP
A versão 15.6 e as versões posteriores do Visual Studio 2017 exibem um aviso quando as Unidades Compartilhadas não
estão configuradas.
Adicionar um projeto a um contêiner do Docker
Para colocar um projeto do ASP.NET Core em contêineres, o projeto deve ser destinado ao .Net Core. Contêineres
do Linux e Windows são ambos compatíveis.
Ao adicionar o suporte do Docker a um projeto, escolha um contêiner do Windows ou Linux. O host do Docker
deve estar executando o mesmo tipo de contêiner. Para alterar o tipo de contêiner na instância do Docker em
execução, clique com o botão direito do mouse no ícone do Docker na Bandeja do Sistema e escolha Alternar
para contêineres do Windows... ou Alternar para contêineres do Linux....
Novo aplicativo
Ao criar um novo aplicativo com os modelos de projeto do Aplicativo Web ASP.NET Core, marque a caixa de
seleção Habilitar Suporte do Docker:
Se a estrutura de destino for o .NET Core, a lista suspensa SO permitirá a seleção de um tipo de contêiner.
Aplicativo existente
Para projetos do ASP.NET Core direcionados ao .NET Core, há duas opções para adicionar o suporte do Docker
por meio das ferramentas. Abra o projeto no Visual Studio e escolha uma das seguintes opções:
Selecione Suporte do Docker no menu Projeto.
Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Adicionar >
Suporte do Docker.
As Ferramentas do Visual Studio para Docker não dão suporte à adição do Docker a um projeto ASP.NET Core
existente direcionado ao .NET Framework.
Visão geral do Dockerfile

Um Dockerfile, a receita para criar uma imagem final do Docker, é adicionado à raiz do projeto. Consulte
Referência do Dockerfile para compreender seus comandos. Esse Dockerfile específico usa um build de vários
estágios, com quatro estágios de build nomeados distintos:
FROM microsoft/dotnet:2.1-aspnetcore-runtime AS base
WORKDIR /app
EXPOSE 59518
EXPOSE 44364
FROM microsoft/dotnet:2.1-sdk AS build

WORKDIR /src
COPY HelloDockerTools/HelloDockerTools.csproj HelloDockerTools/
RUN dotnet restore HelloDockerTools/HelloDockerTools.csproj
COPY . .
WORKDIR /src/HelloDockerTools
RUN dotnet build HelloDockerTools.csproj -c Release -o /app
FROM build AS publish

RUN dotnet publish HelloDockerTools.csproj -c Release -o /app
FROM base AS final

WORKDIR /app
COPY --from=publish /app .
ENTRYPOINT ["dotnet", "HelloDockerTools.dll"]
O Dockerfile precedente se baseia na imagem microsoft/dotnet. Essa imagem base inclui o tempo de execução do
ASP.NET Core e os pacotes NuGet. Os pacotes são compilados JIT (Just-In-Time) para melhorar o desempenho
de inicialização.
Quando a caixa de seleção Configurar para HTTPS do novo projeto estiver marcada, o Dockerfile exibirá duas
portas. Uma porta é usada para o tráfego HTTP; a outra porta é usada para o HTTPS. Se a caixa de seleção não
estiver marcada, uma única porta (80) será exposta para o tráfego HTTP.
FROM microsoft/aspnetcore:2.0 AS base

WORKDIR /app
EXPOSE 80
FROM microsoft/aspnetcore-build:2.0 AS build

WORKDIR /src
COPY HelloDockerTools/HelloDockerTools.csproj HelloDockerTools/
RUN dotnet restore HelloDockerTools/HelloDockerTools.csproj
COPY . .
WORKDIR /src/HelloDockerTools
RUN dotnet build HelloDockerTools.csproj -c Release -o /app
FROM build AS publish

RUN dotnet publish HelloDockerTools.csproj -c Release -o /app
FROM base AS final

WORKDIR /app
COPY --from=publish /app .
O Dockerfile precedente se baseia na imagem microsoft/aspnetcore. Essa imagem base inclui os pacotes NuGet
do ASP.NET Core, que são compilados JIT (Just-In-Time) para melhorar o desempenho de inicialização.
Adicionar o suporte de orquestrador de contêineres a um aplicativo

As versões 15.7 ou posteriores do Visual Studio 2017 são compatíveis com o Docker Compose como a única
solução de orquestração de contêineres. Os artefatos do Docker Compose são adicionados por meio da opção
Adicionar > Suporte ao Docker.
As versões 15.8 ou posteriores do Visual Studio 2017 adicionam uma solução de orquestração apenas quando
instruído. Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Adicionar >
Suporte do orquestrador de contêineres. Duas opções diferentes são oferecidas: Docker Compose e Service
Fabric.
Docker Compose
As Ferramentas do Visual Studio para Docker adicionam um projeto docker-compose à solução com os seguintes
arquivos:
docker-compose.dcproj – O arquivo que representa o projeto. Inclui um elemento <DockerTargetOS> que
especifica o sistema operacional a ser utilizado.
.dockerignore – Lista os padrões de arquivo e diretório a serem excluídos ao gerar um contexto de build.
docker-compose.yml – O arquivo base do Docker Compose usado para definir a coleção de imagens
compiladas e executadas com o docker-compose build e docker-compose run , respectivamente.
docker-compose.override.yml – Um arquivo opcional, lido pelo Docker Compose, com substituições de
configuração para os serviços. O Visual Studio executa
docker-compose -f "docker-compose.yml" -f "docker-compose.override.yml" para mesclar esses arquivos.
O arquivo docker-compose.yml faz referência ao nome da imagem que é criada quando o projeto é executado:
version: '3.4'
services:
hellodockertools:
image: ${DOCKER_REGISTRY}hellodockertools
build:
context: .
dockerfile: HelloDockerTools/Dockerfile
No exemplo anterior, image: hellodockertools gera a imagem hellodockertools:dev quando o aplicativo é

executado no modo Depuração. A imagem hellodockertools:latest é gerada quando o aplicativo é executado no
modo Versão.
Prefixe o nome da imagem com o nome de usuário do hub do Docker (por exemplo,
dockerhubusername/hellodockertools ) se a imagem for enviada por push para o registro. Como alternativa, altere o
nome da imagem para incluir a URL do registro privado (por exemplo,
privateregistry.domain.com/hellodockertools ), dependendo da configuração.
Se você desejar um comportamento diferente com base na configuração de build (por exemplo, Depuração ou
Versão), adicione arquivos docker-compose específicos para a configuração. Os arquivos precisam ser nomeados
de acordo com a configuração de build (por exemplo, docker-compose.vs.debug.yml e docker-
compose.vs.release.yml) e colocado no mesmo local que o arquivo docker-compose-override.yml.
Usando os arquivos de substituição específicos da configuração, é possível especificar definições de configuração
diferentes (como variáveis de ambiente ou pontos de entrada) para as configurações de build de Depuração e
Versão.
Service Fabric
Além dos pré-requisitos básicos, a solução de orquestração do Service Fabric exige os seguintes pré-requisitos:
SDK do Microsoft Azure Service Fabric versão 2.6 ou posterior
Carga de trabalho de desenvolvimento do Azure no Visual Studio 2017
O Service Fabric não é compatível com a execução de contêineres do Linux no cluster de desenvolvimento local no
Windows. Se o projeto já estiver usando um contêiner do Linux, o Visual Studio pedirá para alternar para os
contêineres do Windows.
As Ferramentas do Visual Studio para Docker realizam as seguintes tarefas:
Adiciona um projeto <project_name>do***Aplicativo do Service Fabric* à solução.
Adiciona um Dockerfile e um arquivo .dockerignore ao projeto ASP.NET Core. Se um Dockerfile já existir
no projeto do ASP.NET Core, ele já terá sido renomeado para Dockerfile.original. Um novo Dockerfile,
semelhante ao seguinte, foi criado:
# See https://aka.ms/containerimagehelp for information on how to use Windows Server 1709 containers
with Service Fabric.
# FROM microsoft/aspnetcore:2.0-nanoserver-1709
FROM microsoft/aspnetcore:2.0-nanoserver-sac2016
ARG source
WORKDIR /app
COPY ${source:-obj/Docker/publish} .
Adiciona um elemento <IsServiceFabricServiceProject> ao arquivo .csproj do projeto do ASP.NET Core:
<IsServiceFabricServiceProject>True</IsServiceFabricServiceProject>
Adiciona uma pasta PackageRoot ao projeto ASP.NET Core. A pasta inclui o manifesto do serviço e as
configurações para o novo serviço.
Para obter mais informações, consulte Implantar um aplicativo .NET em um contêiner do Windows no Azure
Service Fabric.
Depurar
Selecione Docker no menu suspenso de depuração na barra de ferramentas e inicie a depuração do aplicativo. A
exibição Docker da janela Saída mostra as seguintes ações em andamento:
A marcação 2.1 -aspnetcore-runtime da imagem do tempo de execução microsoft/dotnet foi adquirida (se ainda
não estiver no cache). A imagem instala os tempos de execução do ASP.NET Core e do .Net Core e bibliotecas
associadas. Ela é otimizada para executar aplicativos do ASP.NET Core em produção.
A variável de ambiente ASPNETCORE_ENVIRONMENT é definida como Development dentro do contêiner.
Duas portas atribuídas dinamicamente são expostas: uma para HTTP e outra para HTTPS. A porta atribuída ao
localhost pode ser consultada com o comando docker ps .
O aplicativo é copiado para o contêiner.
O navegador padrão é iniciado com o depurador anexado ao contêiner, usando a porta atribuída
dinamicamente.
A imagem resultante do Docker do aplicativo é marcada como dev. A imagem é baseada na marcação 2.1 -
aspnetcore-runtime da imagem base microsoft/dotnet. Execute o comando docker images na janela do PMC
(Console do Gerenciador de Pacotes). As imagens no computador são exibidas:
REPOSITORY TAG IMAGE ID CREATED SIZE

hellodockertools dev d72ce0f1dfe7 30 seconds ago 255MB
microsoft/dotnet 2.1-aspnetcore-runtime fcc3887985bb 6 days ago 255MB
A imagem em tempo de execução microsoft/aspnetcore é adquirida (se ainda não está no cache).
A variável de ambiente ASPNETCORE_ENVIRONMENT é definida como Development dentro do contêiner.
A porta 80 é exposta e mapeada para uma porta atribuída dinamicamente para o localhost. A porta é
determinada pelo host do Docker e pode ser consultada com o comando docker ps .
O aplicativo é copiado para o contêiner.
O navegador padrão é iniciado com o depurador anexado ao contêiner, usando a porta atribuída
dinamicamente.
A imagem resultante do Docker do aplicativo é marcada como dev. A imagem é baseada na imagem base
microsoft/aspnetcore. Execute o comando docker images na janela do PMC (Console do Gerenciador de
Pacotes). As imagens no computador são exibidas:

hellodockertools dev 5fafe5d1ad5b 4 minutes ago 347MB
microsoft/aspnetcore 2.0 c69d39472da9 13 days ago 347MB
NOTE
A imagem dev não inclui o conteúdo do aplicativo, pois as configurações de Depuração usam a montagem de volume para
fornecer uma experiência iterativa. Para enviar uma imagem por push, use a configuração Versão.
Execute o comando docker ps no PMC. Observe que o aplicativo está em execução usando o contêiner:
CONTAINER ID IMAGE COMMAND CREATED STATUS

PORTS NAMES
baf9a678c88d hellodockertools:dev "C:\\remote_debugge..." 21 seconds ago Up 19 seconds
0.0.0.0:37630->80/tcp dockercompose4642749010770307127_hellodockertools_1
Editar e continuar
As alterações em arquivos estáticos e exibições do Razor são atualizadas automaticamente sem a necessidade de
uma etapa de compilação. Faça a alteração, salve e atualize o navegador para exibir a atualização.
As modificações nos arquivos de código exigem a compilação e a reinicialização do Kestrel dentro do contêiner.
Depois de fazer a alteração, use CTRL+F5 para executar o processo e iniciar o aplicativo dentro do contêiner. O
contêiner do Docker não é recompilado nem interrompido. Execute o comando docker ps no PMC. Observe que
o contêiner original ainda está em execução como há 10 minutos:
CONTAINER ID IMAGE COMMAND CREATED STATUS

PORTS NAMES
baf9a678c88d hellodockertools:dev "C:\\remote_debugge..." 10 minutes ago Up 10 minutes
0.0.0.0:37630->80/tcp dockercompose4642749010770307127_hellodockertools_1
Publicar imagens do Docker

Depois de concluir o ciclo de desenvolvimento e depuração de seu aplicativo, as Ferramentas do Visual Studio
para Docker ajudarão você a criar a imagem de produção do aplicativo. Altere a lista suspensa de configuração
para Versão e compile o aplicativo. O conjunto de ferramentas adquire a imagem de compilação/publicação do
hub do Docker (se ainda não estiver no cache). Uma imagem é produzida com a marcação latest, que você pode
enviar por push para seu registro privado ou para o hub do Docker.
Execute o comando docker images no PMC para ver a lista de imagens. Uma saída semelhante à apresentada a
seguir será exibida:

hellodockertools latest e3984a64230c About a minute ago 258MB
hellodockertools dev d72ce0f1dfe7 4 minutes ago 255MB
microsoft/dotnet 2.1-sdk 9e243db15f91 6 days ago 1.7GB
microsoft/dotnet 2.1-aspnetcore-runtime fcc3887985bb 6 days ago 255MB
hellodockertools latest cd28f0d4abbd 12 seconds ago 349MB
hellodockertools dev 5fafe5d1ad5b 23 minutes ago 347MB
microsoft/aspnetcore-build 2.0 7fed40fbb647 13 days ago 2.02GB
microsoft/aspnetcore 2.0 c69d39472da9 13 days ago 347MB
As imagens microsoft/aspnetcore-build e microsoft/aspnetcore listadas na saída anterior são substituídas pelas

imagens microsoft/dotnet com o .Net Core 2.1. Para obter mais informações, consulte o comunicado de migração
de repositórios do Docker.
NOTE
O comando docker images retorna imagens intermediárias com nomes de repositório e marcas identificadas como
<none> (não listadas acima). Essas imagens sem nome são produzidas pelo Dockerfile no build de vários estágios. Elas
melhoram a eficiência da compilação da imagem final — apenas as camadas necessárias são recompiladas quando ocorrem
alterações. Quando você não precisar mais das imagens intermediárias, exclua-as usando o comando docker rmi.
Pode haver uma expectativa de que a imagem de produção ou versão seja menor em comparação com a imagem
dev. Devido ao mapeamento do volume, o depurador e o aplicativo estavam em execução no computador local e
não dentro do contêiner. A última imagem empacotou o código do aplicativo necessário para executar o aplicativo
em um computador host. Portanto, o delta é o tamanho do código do aplicativo.
Recursos adicionais
Desenvolvimento de contêiner com o Visual Studio
Azure Service Fabric: prepare seu ambiente de desenvolvimento
Implantar um aplicativo .NET em um contêiner do Windows no Azure Service Fabric
Solucionar problemas de desenvolvimento do Visual Studio 2017 com o Docker
Repositório do GitHub para Ferramentas do Visual Studio para Docker
Configure o ASP.NET Core para trabalhar com
servidores proxy e balanceadores de carga
Por Luke Latham e Chris Ross

Na configuração recomendada para o ASP.NET Core, o aplicativo é hospedado usando IIS/Módulo do
ASP.NET Core, Nginx ou Apache. Servidores proxy, balanceadores de carga e outros dispositivos de rede
geralmente ocultam informações sobre a solicitação antes de ela alcançar o aplicativo:
Quando solicitações HTTPS são passadas por proxy por HTTP, o esquema original (HTTPS ) é perdido e
deve ser encaminhado em um cabeçalho.
Devido a um aplicativo receber uma solicitação do proxy e não de sua origem verdadeira na Internet ou
rede corporativa, o endereço IP do cliente originador também deve ser encaminhado em um cabeçalho.
Essas informações podem ser importantes no processamento de solicitações, por exemplo, em
redirecionamentos, autenticação, geração de link, avaliação de política e localização geográfica do cliente.
Cabeçalhos encaminhados
Por convenção, os proxies encaminham informações em cabeçalhos HTTP.
CABEÇALHO DESCRIÇÃO
X-Forwarded-For Contém informações sobre o cliente que iniciou a

solicitação e os proxies subsequentes em uma cadeia de
proxies. Esse parâmetro pode conter endereços IP (e,
opcionalmente, os números de porta). Em uma cadeia de
servidores proxy, o primeiro parâmetro indica o cliente em
que a solicitação foi feita pela primeira vez. Depois, vêm os
identificadores de proxy subsequentes. O último proxy na
cadeia não está na lista de parâmetros. O endereço IP do
último proxy (e opcionalmente um número da porta)
estão disponíveis como o endereço IP remoto na camada
de transporte.
X-Forwarded-Proto O valor do esquema de origem (HTTP/HTTPS). O valor

também pode ser uma lista de esquemas se a solicitação
percorreu vários proxies.
X-Forwarded-Host O valor original do campo de cabeçalho do host.

Normalmente, os proxies não modificam o cabeçalho do
host. Veja Microsoft Security Advisory CVE-2018-0787
para obter informações sobre uma vulnerabilidade de
elevação de privilégios que afeta os sistemas em que o
proxy não valida ou restringe cabeçalhos de Host a
valores válidos conhecidos.
O middleware de cabeçalhos encaminhados, do pacote Microsoft.AspNetCore.HttpOverrides, lê esses

cabeçalhos e preenche os campos associados em HttpContext.
As atualizações de middleware:
HttpContext.Connection.RemoteIpAddress – Definido usando o valor do cabeçalho X-Forwarded-For .
Configurações adicionais influenciam o modo como o middleware define RemoteIpAddress . Para obter
detalhes, veja as Opções de middleware de cabeçalhos encaminhados.
HttpContext.Request.Scheme – Definido usando o valor do cabeçalho X-Forwarded-Proto .
HttpContext.Request.Host – Definido usando o valor do cabeçalho X-Forwarded-Host .
As configurações padrão de middleware de cabeçalhos encaminhados podem ser definidas. As
configurações padrão são:
Há apenas um proxy entre o aplicativo e a origem das solicitações.
Somente os endereços de loopback são configurados para proxies conhecidos e redes conhecidas.
Os cabeçalhos encaminhados são nomeados X-Forwarded-For e X-Forwarded-Proto .
Nem todos os dispositivos de rede adicionam os cabeçalhos X-Forwarded-For e X-Forwarded-Proto sem

configuração adicional. Consulte as diretrizes do fabricante do dispositivo se as solicitações de proxies não
contiverem esses cabeçalhos quando atingirem o aplicativo. Se o dispositivo usar nomes de cabeçalho
diferentes de X-Forwarded-For e de X-Forwarded-Proto , defina as opções ForwardedForHeaderName e
ForwardedProtoHeaderName para corresponderem aos nomes de cabeçalho usados pelo dispositivo. Para
obter mais informações, consulte Forwarded Headers Middleware options (Opções de middleware de
cabeçalhos encaminhados) e Configuration for a proxy that uses different header names (Configuração de
um proxy que usa diferentes nomes de cabeçalho).
O IIS/IIS Express e o Módulo do ASP.NET Core

O middleware de cabeçalhos encaminhados é habilitado por padrão pelo middleware de integração do IIS
quando o aplicativo é executado por trás do IIS e do Módulo do ASP.NET Core. O middleware de
cabeçalhos encaminhados é ativado para ser executado primeiro no pipeline de middleware, com uma
configuração restrita específica para o Módulo do ASP.NET Core devido a questões de confiança com
cabeçalhos encaminhados (por exemplo, falsificação de IP ). O middleware está configurado para
encaminhar os cabeçalhos X-Forwarded-For e X-Forwarded-Proto e é restrito a um proxy de localhost único.
Se configuração adicional for necessária, veja as Opções de middleware de cabeçalhos encaminhados.
Outros cenários de servidor proxy e balanceador de carga

Exceto pelo uso de middleware de integração do IIS, o middleware de cabeçalhos encaminhados não é
habilitado por padrão. O middleware de cabeçalhos encaminhados deve ser habilitado para um aplicativo
para processar cabeçalhos encaminhados com UseForwardedHeaders. Após a habilitação do middleware,
se nenhum ForwardedHeadersOptions for especificado para o middleware, o
ForwardedHeadersOptions.ForwardedHeaders padrão será ForwardedHeaders.None.
Configure o middleware com ForwardedHeadersOptions para encaminhar os cabeçalhos X-Forwarded-For
e X-Forwarded-Proto em Startup.ConfigureServices . Invoque o método UseForwardedHeaders em
Startup.Configure antes de chamar outro middleware:
{
services.AddMvc();
{
options.ForwardedHeaders =
ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
});
}

{
app.UseForwardedHeaders();
{
}
else
{
}
// In ASP.NET Core 1.x, replace the following line with: app.UseIdentity();
app.UseMvc();
}
NOTE
Se nenhuma ForwardedHeadersOptions é especificada em Startup.ConfigureServices ou diretamente para o
método de extensão com UseForwardedHeaders(IApplicationBuilder, ForwardedHeadersOptions), os cabeçalhos
padrão para encaminhar são ForwardedHeaders.None. A propriedade ForwardedHeadersOptions.ForwardedHeaders
deve ser configurada com os cabeçalhos para encaminhar.
Configuração de Nginx
Para encaminhar os cabeçalhos X-Forwarded-For e X-Forwarded-Proto , consulte Host ASP.NET Core no
Linux com Nginx. Para obter mais informações, veja NGINX: usando o cabeçalho encaminhado.
Configuração do Apache
X-Forwarded-For é adicionado automaticamente (veja mod_proxy do módulo do Apache: cabeçalhos de
solicitação de proxy reverso). Para obter informações sobre como encaminhar o cabeçalho
X-Forwarded-Proto , consulte Hospedar o ASP.NET Core no Linux com o Apache.
Opções de middleware de cabeçalhos encaminhados

ForwardedHeadersOptions controlam o comportamento do middleware de cabeçalhos encaminhados. O
seguinte exemplo altera os valores padrão:
Limite o número de entradas nos cabeçalhos encaminhados a 2 .
Adicione um endereço de proxy conhecido de 127.0.10.1 .
Altere o nome do cabeçalho encaminhado do padrão X-Forwarded-For para
X-Forwarded-For-My-Custom-Header-Name .
{
options.ForwardLimit = 2;
options.ForwardedForHeaderName = "X-Forwarded-For-My-Custom-Header-Name";
});
OPÇÃO DESCRIÇÃO
AllowedHosts Restringe os hosts com o cabeçalho X-Forwarded-Host

para os valores fornecidos.
Os valores são comparados usando ordinal-
ignore-case.
Os número de porta devem ser excluídos.
Se a lista estiver vazia, todos os hosts serão
permitidos.
Um curinga de nível superior * permite todos os
hosts não vazios.
Curingas de subdomínio são permitidos, mas não
correspondem ao domínio raiz. Por exemplo,
*.contoso.com corresponde o subdomínio
foo.contoso.com , mas não ao domínio raiz
contoso.com .
Nomes do host Unicode são permitidos, mas são
convertidos em Punycode para correspondência.
Endereços IPv6 devem incluir colchetes
delimitadores e estar no formato convencional (por
exemplo,
[ABCD:EF01:2345:6789:ABCD:EF01:2345:6789] ).
Endereços IPv6 não têm caso especial para verificar
se há igualdade lógica entre formatos diferentes, e
nenhuma canonicalização é executada.
Falha ao restringir os hosts permitidos pode
permitir que um atacante falsifique links gerados
pelo serviço.
O valor padrão é uma IList<cadeia de caracteres> vazia.
ForwardedForHeaderName Use o cabeçalho especificado por essa propriedade, em

vez de um especificado por
ForwardedHeadersDefaults.XForwardedForHeaderName.
Esta opção é usada quando o proxy/encaminhador não
usa o cabeçalho X-Forwarded-For , mas usa algum outro
cabeçalho para encaminhar as informações.
O padrão é X-Forwarded-For .
ForwardedHeaders Identifica quais encaminhadores devem ser processados.

Veja o ForwardedHeaders Enum para a lista de campos
aplicáveis. Os valores típicos atribuídos a essa propriedade
são
ForwardedHeaders.XForwardedFor |
ForwardedHeaders.XForwardedProto
.
O valor padrão é ForwardedHeaders.None.

OPÇÃO DESCRIÇÃO
ForwardedHostHeaderName Use o cabeçalho especificado por essa propriedade, em

ForwardedHeadersDefaults.XForwardedHostHeaderName.
usa o cabeçalho X-Forwarded-Host , mas usa algum
outro cabeçalho para encaminhar as informações.
O padrão é X-Forwarded-Host .
ForwardedProtoHeaderName Use o cabeçalho especificado por essa propriedade, em

ForwardedHeadersDefaults.XForwardedProtoHeaderName
. Esta opção é usada quando o proxy/encaminhador não
usa o cabeçalho X-Forwarded-Proto , mas usa algum
O padrão é X-Forwarded-Proto .
ForwardLimit Limita o número de entradas nos cabeçalhos que são

processados. Defina para null para desabilitar o limite,
mas isso só deve ser feito se KnownProxies ou
KnownNetworks estão configurados.
O padrão é 1.
KnownNetworks Intervalos de endereços de redes conhecidas dos quais

aceitar cabeçalhos encaminhados. Forneça os intervalos
de IP usando notação de CIDR (Roteamento entre
Domínios sem Classificação).
O servidor usa soquetes de modo duplo e os endereços

IPv4 são fornecidos em um formato IPv6 (por exemplo,
10.0.0.1 no formato IPv4 representado no formato
IPv6 como ::ffff:10.0.0.1 ). Confira
IPAddress.MapToIPv6. Para determinar se este formato é
obrigatório, veja
HttpContext.Connection.RemoteIpAddress. Para saber
mais, veja a seção Configuração de endereços IPv4
representados como endereços IPv6.
O padrão é um IList<IPNetwork> contendo uma única

entrada para IPAddress.Loopback .
OPÇÃO DESCRIÇÃO
KnownProxies Endereços de proxies conhecidos dos quais aceitar

cabeçalhos encaminhados. Use KnownProxies especificar
correspondências exatas de endereço IP.

obrigatório, veja
O padrão é um IList<IPAddress> contendo uma única

entrada para IPAddress.IPv6Loopback .
OriginalForHeaderName Use o cabeçalho especificado por essa propriedade, em

ForwardedHeadersDefaults.XOriginalForHeaderName.
O padrão é X-Original-For .
OriginalHostHeaderName Use o cabeçalho especificado por essa propriedade, em

ForwardedHeadersDefaults.XOriginalHostHeaderName.
O padrão é X-Original-Host .
OriginalProtoHeaderName Use o cabeçalho especificado por essa propriedade, em

ForwardedHeadersDefaults.XOriginalProtoHeaderName.
O padrão é X-Original-Proto .
RequireHeaderSymmetry Exigem o número de valores de cabeçalho a serem

sincronizados entre os
ForwardedHeadersOptions.ForwardedHeaders sendo
processados.
O padrão no ASP.NET Core 1.x é true . O padrão no

ASP.NET Core 2.0 ou posterior é false .
OPÇÃO DESCRIÇÃO
ForwardedForHeaderName Use o cabeçalho especificado por essa propriedade, em

ForwardedHeadersDefaults.XForwardedForHeaderName.
usa o cabeçalho X-Forwarded-For , mas usa algum outro
cabeçalho para encaminhar as informações.
O padrão é X-Forwarded-For .
OPÇÃO DESCRIÇÃO
ForwardedHeaders Identifica quais encaminhadores devem ser processados.

Veja o ForwardedHeaders Enum para a lista de campos
aplicáveis. Os valores típicos atribuídos a essa propriedade
são
ForwardedHeaders.XForwardedFor |
ForwardedHeaders.XForwardedProto
.
O valor padrão é ForwardedHeaders.None.
ForwardedHostHeaderName Use o cabeçalho especificado por essa propriedade, em

ForwardedHeadersDefaults.XForwardedHostHeaderName.
usa o cabeçalho X-Forwarded-Host , mas usa algum
O padrão é X-Forwarded-Host .
ForwardedProtoHeaderName Use o cabeçalho especificado por essa propriedade, em

ForwardedHeadersDefaults.XForwardedProtoHeaderName
. Esta opção é usada quando o proxy/encaminhador não
usa o cabeçalho X-Forwarded-Proto , mas usa algum
O padrão é X-Forwarded-Proto .
ForwardLimit Limita o número de entradas nos cabeçalhos que são

processados. Defina para null para desabilitar o limite,
mas isso só deve ser feito se KnownProxies ou
KnownNetworks estão configurados.
O padrão é 1.
KnownNetworks Intervalos de endereços de redes conhecidas dos quais

aceitar cabeçalhos encaminhados. Forneça os intervalos
de IP usando notação de CIDR (Roteamento entre
Domínios sem Classificação).

obrigatório, veja
O padrão é um IList<IPNetwork> contendo uma única

entrada para IPAddress.Loopback .
OPÇÃO DESCRIÇÃO
KnownProxies Endereços de proxies conhecidos dos quais aceitar

cabeçalhos encaminhados. Use KnownProxies especificar
correspondências exatas de endereço IP.

obrigatório, veja
O padrão é um IList<IPAddress> contendo uma única

entrada para IPAddress.IPv6Loopback .
OriginalForHeaderName Use o cabeçalho especificado por essa propriedade, em

ForwardedHeadersDefaults.XOriginalForHeaderName.
O padrão é X-Original-For .
OriginalHostHeaderName Use o cabeçalho especificado por essa propriedade, em

ForwardedHeadersDefaults.XOriginalHostHeaderName.
O padrão é X-Original-Host .
OriginalProtoHeaderName Use o cabeçalho especificado por essa propriedade, em

ForwardedHeadersDefaults.XOriginalProtoHeaderName.
O padrão é X-Original-Proto .
RequireHeaderSymmetry Exigem o número de valores de cabeçalho a serem

sincronizados entre os
ForwardedHeadersOptions.ForwardedHeaders sendo
processados.
O padrão no ASP.NET Core 1.x é true . O padrão no

ASP.NET Core 2.0 ou posterior é false .
Cenários e casos de uso

Quando não é possível adicionar cabeçalhos encaminhados e todas as solicitações são seguras
Em alguns casos, pode não ser possível adicionar cabeçalhos encaminhados para as solicitações passadas
por proxy ao aplicativo. Se o proxy está impondo que todas as solicitações externas públicas sejam HTTPS,
o esquema pode ser definido manualmente em Startup.Configure antes de usar qualquer tipo de
middleware:
{
context.Request.Scheme = "https";
return next();
});
Esse código pode ser desabilitado com uma variável de ambiente ou outra definição de configuração em
um ambiente de preparo ou de desenvolvimento.
Lidar com o caminho base e proxies que alteram o caminho da solicitação
Alguns proxies passam o caminho intacto, mas com um caminho base de aplicativo que deve ser removido
para que o roteamento funcione corretamente. O middleware de UsePathBaseExtensions.UsePathBase
divide o caminho em HttpRequest.Path e o caminho base do aplicativo em HttpRequest.PathBase.
Se /foo é o caminho base do aplicativo para um caminho de proxy passado como /foo/api/1 , o
middleware define Request.PathBase para /foo e Request.Path para /api/1 com o seguinte comando:
app.UsePathBase("/foo");
O caminho original e o caminho base são reaplicados quando o middleware é chamado novamente na
ordem inversa. Para obter mais informações sobre o processamento de ordem de middleware, consulte
Middleware do ASP.NET Core.
Se o proxy cortar o caminho (por exemplo, encaminhando /foo/api/1 para /api/1 ), corrija
redirecionamentos e links definindo a propriedade PathBase da solicitação:

{
context.Request.PathBase = new PathString("/foo");
return next();
});
Se o proxy estiver adicionando dados de caminho, descarte a parte do caminho para corrigir
redirecionamentos e links usando StartsWithSegments (PathString, PathString) e atribuindo para a
propriedade Path:

{
if (context.Request.Path.StartsWithSegments("/foo", out var remainder))
{
context.Request.Path = remainder;
}
return next();
});
Configuração de um proxy que usa diferentes nomes de cabeçalho

Se o proxy não usar cabeçalhos nomeados X-Forwarded-For e X-Forwarded-Proto para encaminhar a
porta/endereço do proxy e as informações de origem do esquema, defina as opções
ForwardedForHeaderName e ForwardedProtoHeaderName para corresponder aos nomes de cabeçalho
usados pelo proxy:
{
options.ForwardedForHeaderName = "Header_Name_Used_By_Proxy_For_X-Forwarded-For_Header";
options.ForwardedProtoHeaderName = "Header_Name_Used_By_Proxy_For_X-Forwarded-Proto_Header";
});
Configuração de endereços IPv4 representados como endereços IPv6

O servidor usa soquetes de modo duplo e os endereços IPv4 são fornecidos em um formato IPv6 (por
exemplo, 10.0.0.1 no formato IPv4 representado no formato IPv6 como ::ffff:10.0.0.1 ou
::ffff:a00:1 ). Confira IPAddress.MapToIPv6. Para determinar se este formato é obrigatório, veja
HttpContext.Connection.RemoteIpAddress.
No exemplo a seguir, um endereço de rede que fornece cabeçalhos encaminhados é adicionado à lista
KnownNetworks no formato IPv6.
Endereço IPv4: 10.11.12.1/8
Conversão em endereço IPv6: ::ffff:10.11.12.1

Comprimento do prefixo convertido: 104
Você pode também fornecer o endereço no formato hexadecimal ( 10.11.12.1 , representado no formato
IPv6 como ::ffff:0a0b:0c01 ). Quando converter um endereço IPv4 em IPv6, adicione 96 ao comprimento
do prefixo CIDR ( 8 no exemplo) para levar em conta o prefixo IPv6 adicional ::ffff: (8 + 96 = 104).
// To access IPNetwork and IPAddress, add the following namespaces:

// using using System.Net;
// using Microsoft.AspNetCore.HttpOverrides;
{
options.ForwardedHeaders =
ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
options.KnownNetworks.Add(new IPNetwork(
IPAddress.Parse("::ffff:10.11.12.1"), 104));
});
Quando os cabeçalhos não são encaminhados conforme o esperado, habilite registro em log. Se os logs
não fornecerem informações suficientes para solucionar o problema, enumere os cabeçalhos de solicitação
recebidos pelo servidor. Use middleware embutido para gravar cabeçalhos de solicitação para uma
resposta do aplicativo ou para log dos cabeçalhos. Coloque um dos exemplos de código a seguir
imediatamente após a chamada para UseForwardedHeaders em Startup.Configure .
Para escrever os cabeçalhos na resposta do aplicativo, use o seguinte middleware embutido terminal:
{
context.Response.ContentType = "text/plain";
// Request method, scheme, and path

$"Request Method: {context.Request.Method}{Environment.NewLine}");
$"Request Scheme: {context.Request.Scheme}{Environment.NewLine}");
$"Request Path: {context.Request.Path}{Environment.NewLine}");
// Headers
await context.Response.WriteAsync($"Request Headers:{Environment.NewLine}");
foreach (var header in context.Request.Headers)

{
await context.Response.WriteAsync($"{header.Key}: " +
$"{header.Value}{Environment.NewLine}");
}
await context.Response.WriteAsync(Environment.NewLine);
// Connection: RemoteIp
$"Request RemoteIp: {context.Connection.RemoteIpAddress}");
});
Também é possível escrever nos logs em vez do corpo da resposta usando o seguinte middleware
embutido. Isso permite que o site funcione normalmente durante a depuração.
var logger = _loggerFactory.CreateLogger<Startup>();

{
// Request method, scheme, and path
logger.LogDebug("Request Method: {METHOD}", context.Request.Method);
logger.LogDebug("Request Scheme: {SCHEME}", context.Request.Scheme);
logger.LogDebug("Request Path: {PATH}", context.Request.Path);
// Headers
foreach (var header in context.Request.Headers)
{
logger.LogDebug("Header: {KEY}: {VALUE}", header.Key, header.Value);
}
// Connection: RemoteIp
logger.LogDebug("Request RemoteIp: {REMOTE_IP_ADDRESS}",
context.Connection.RemoteIpAddress);
await next();
});
Quando processado, os valores X-Forwarded-{For|Proto|Host} são movidos para

X-Original-{For|Proto|Host} . Se há vários valores em um determinado cabeçalho, observe que o
middleware de cabeçalhos encaminhados processa cabeçalhos na ordem inversa, da direita para esquerda.
O ForwardLimit padrão é 1 (um), portanto, apenas o valor mais à direita dos cabeçalhos será processado, a
menos que o valor de ForwardLimit aumente.
O IP de remoto original da solicitação precisa corresponder a uma entrada nas listas KnownProxies ou
KnownNetworks antes dos cabeçalhos encaminhados serem processados. Isso limita a falsificação de
cabeçalho por não aceitar encaminhadores de proxies não confiáveis. Quando um proxy desconhecido é
detectado, o registro em log indica o endereço dele:
September 20th 2018, 15:49:44.168 Unknown proxy: 10.0.0.100:54321
No exemplo anterior, 10.0.0.100 é um servidor proxy. Se o servidor for um proxy confiável, adicione o
endereço IP do servidor a KnownProxies (ou adicione uma rede confiável a KnownNetworks ) em
Startup.ConfigureServices . Para obter mais informações, consulte a seção Opções de middleware de
cabeçalhos encaminhados.
{
});
IMPORTANT
Permitir que somente proxies e redes confiáveis encaminhem os cabeçalhos. Caso contrário, podem ocorrer ataques
de falsificação de IP.
Recursos adicionais
Microsoft Security Advisory CVE -2018-0787: vulnerabilidade de elevação de privilégio do ASP.NET
Core
Por Luke Latham e Chris Ross

Um web farm é um grupo de dois ou mais servidores web (ou nós) que hospedam várias instâncias de um
aplicativo. Quando as solicitações de usuários chegam a um web farm, um balanceador de carga distribui as
solicitações para os nós de farm da web. Os web farms melhoram:
Disponibilidade/confiabilidade – quando um ou mais nós falham, o balanceador de carga pode rotear
solicitações para outros nós em funcionamento para continuar a processar solicitações.
Capacidade e desempenho – vários nós podem processar mais solicitações que um único servidor. O
balanceador de carga equilibra a carga de trabalho ao distribuir as solicitações para os nós.
Escalabilidade – quando a necessidade da capacidade for maior ou menor, o número de nós ativos pode ser
aumentado ou diminuído para corresponder à carga de trabalho. Tecnologias de plataforma de web farm,
como o Serviço de Aplicativo do Azure, podem adicionar ou remover nós por solicitação do administrador do
sistema ou automaticamente sem a intervenção humana.
Facilidade de manutenção – os nós de um web farm podem contar com um conjunto de serviços
compartilhados, o que resulta em um gerenciamento mais fácil do sistema. Por exemplo, os nós de um web
farm podem contar com um servidor de banco de dados individual e um local de rede comum para recursos
estáticos, como imagens e arquivos para download.
Este tópico descreve as configurações e dependências para aplicativos ASP.NET Core hospedados em um web
farm que conta com recursos compartilhados.
Configuração geral
Aprenda como configurar ambientes de hospedagem e implantar aplicativos ASP.NET Core. Configure um
gerenciador de processo em cada nó do web farm para automatizar o início e a reinicialização do aplicativo.
Cada nó requer o tempo de execução do ASP.NET Core. Para saber mais, confira os tópicos na área Hospedar e
implantar da documentação.
Configure o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga
Saiba mais sobre a configuração para aplicativos hospedados por trás de servidores proxy e balanceadores de
carga, o que muitas vezes oculta informações de solicitação importantes.
Serviço de Aplicativo do Azure é um serviço de plataforma de computação em nuvem da Microsoft para
hospedar aplicativos Web, incluindo o ASP.NET Core. O Serviço de Aplicativo é uma plataforma totalmente
gerenciada que fornece escalabilidade automática, balanceamento de carga, aplicação de patch e implantação
contínua.
Dados do aplicativo
Quando um aplicativo é dimensionado para várias instâncias, pode haver um estado do aplicativo que exija o
compartilhamento entre os nós. Se o estado for transitório, considere a possibilidade de compartilhar um
IDistributedCache. Se o estado compartilhado exigir persistência, considere armazenar o estado compartilhado
em um banco de dados.
Configuração necessária
O serviço de cache e a proteção de dados exigem uma configuração para aplicativos implantados em um web
farm.
Proteção de Dados
O sistema de proteção de dados do ASP.NET Core é usado por aplicativos para proteger os dados. A proteção
de dados baseia-se em um conjunto de chaves de criptografia armazenados em um token de autenticação.
Quando o sistema de Proteção de dados é inicializado, ele aplica as configurações padrão que armazenam
localmente o token de autenticação. Sob a configuração padrão, um token de autenticação exclusivo é
armazenado em cada nó do web farm. Consequentemente, cada nó do web farm não pode descriptografar os
dados criptografados por um aplicativo em qualquer outro nó. A configuração padrão normalmente não é
adequada para hospedagem de aplicativos em um web farm. Uma alternativa à implementação de um token de
autenticação compartilhado é sempre rotear as solicitações do usuário para o mesmo nó. Para saber mais sobre
a configuração do sistema de Proteção de dados para implantações de web farm, confira Configurar a proteção
de dados do ASP.NET Core.
Cache
Em um ambiente de web farm, o mecanismo de cache deve compartilhar os itens em cache pelos nós do web
farm. O serviço de cache deve contar com um cache Redis comum, um banco de dados compartilhado do SQL
Server ou uma implementação personalizada de cache que compartilha os itens em cache pelo web farm. Para
obter mais informações, consulte O cache no ASP.NET Core distribuído.
Componentes dependentes
Os cenários a seguir não exigem configuração adicional, mas dependem de tecnologias que exigem
configurações para web farms.
CENÁRIO DEPENDE DE …
Autenticação Proteção de dados (confira Configurar a proteção de dados

do ASP.NET Core).
Para obter mais informações, consulte Usar autenticação de

cookie sem o ASP.NET Core Identity e Compartilhar cookies
entre aplicativos com o ASP.NET e ASP.NET Core.
Identidade Configuração e autenticação do banco de dados.
Para obter mais informações, consulte Introdução à

identidade do ASP.NET Core.
Session Proteção de dados (cookies criptografados) (confira

Configurar a proteção de dados do ASP.NET Core) e cache
(confira O cache no ASP.NET Core distribuído).
Para saber mais, confira Estado de sessão e aplicativo: estado

de sessão.
TempData Proteção de dados (cookies criptografados) (confira

Configurar a proteção de dados do ASP.NET Core) ou sessão
(confira Estado de sessão e aplicativo: estado de sessão).
Para saber mais, consulte Estado de sessão e aplicativo:

TempData.
CENÁRIO DEPENDE DE …
Antifalsificação Proteção de dados (confira Configurar a proteção de dados

do ASP.NET Core).
Para obter mais informações, consulte Ataques de evitar

entre solicitação intersite forjada (CSRF/XSRF) no ASP.NET
Core.
Quando a proteção de dados ou cache não está configurada para um ambiente de web farm, erros intermitentes
ocorrem quando as solicitações são processadas. Isso acontece porque os nós não compartilham os mesmos
recursos e as solicitações do usuário não são sempre roteadas para o mesmo nó.
Considere um usuário que entra no aplicativo usando a autenticação de cookie. O usuário entra no aplicativo em
um nó do web farm. Se a sua próxima solicitação chegar ao mesmo nó no qual ele se conectou, o aplicativo
consegue descriptografar o cookie de autenticação e permite o acesso ao recurso do aplicativo. Se a sua próxima
solicitação chegar em um nó diferente, o aplicativo não consegue descriptografar o cookie de autenticação a
partir do nó em que o usuário entrou e a autorização do recurso solicitado falhará.
Quando qualquer um dos seguintes sintomas ocorrem de forma intermitente, o problema normalmente é
rastreado a configuração incorreta de proteção de dados ou cache para um ambiente de web farm:
Quebras de autenticação – o cookie de autenticação está configurado incorretamente ou não pode ser
descriptografado. Falha de login OpenIdConnect ou OAuth (Facebook, Microsoft, Twitter) com o erro "Falha
de correlação".
Quebras de autorização – a identidade foi perdida.
O estado de sessão perde os dados.
Os itens em cache desaparecem.
O TempData falhará.
Os POSTs falham – a verificação antifalsificação falhará.
Para saber mais sobre a configuração de Proteção de dados para implantações de web farm, confira Configurar
a proteção de dados do ASP.NET Core. Para saber mais sobre a configuração de cache para implantações de
web farm, confira O cache no ASP.NET Core distribuído.
Perfis de publicação do Visual Studio para a
implantação do aplicativo ASP.NET Core
Por Sayed Hashimi de Ibrahim e Rick Anderson

Este documento artigo se concentra no uso do Visual Studio 2017 para criar e usar perfis de publicação. Os perfis
de publicação criados com o Visual Studio podem ser executados do MSBuild e do Visual Studio 2017. Consulte
Publicar um aplicativo Web ASP.NET Core no Serviço de Aplicativo do Azure usando o Visual Studio para obter
instruções sobre a publicação no Azure.
O arquivo de projeto a seguir foi criado com o comando dotnet new mvc :
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
</Project>
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
</Project>
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
</Project>
O atributo <Project> do elemento Sdk realiza as seguintes tarefas:

Importa o arquivo de propriedades de $ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Web\Sdk\Sdk.Props no início.
Importa o arquivo de destino de $ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Web\Sdk\Sdk.targets no fim.
O local padrão para MSBuildSDKsPath (com o Visual Studio Enterprise 2017) é a pasta
%programfiles(x86 )%\Microsoft Visual Studio\2017\Enterprise\MSBuild\Sdks.
O SDK de Microsoft.NET.Sdk.Web depende de:
Microsoft.NET.Sdk.Web.ProjectSystem
Microsoft.NET.Sdk.Publish
O que faz com que as propriedades e os destinos a seguir a sejam importados:
$ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Web.ProjectSystem\Sdk\Sdk.Props
$ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Web.ProjectSystem\Sdk\Sdk.targets
$ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Publish\Sdk\Sdk.Props
$ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Publish\Sdk\Sdk.targets
Destinos de publicação importam o conjunto certo de destinos com base no método de publicação usado.
Quando o MSBuild ou o Visual Studio carrega um projeto, as seguintes ações de nível alto ocorrem:
Compilar projeto
Computar arquivos a publicar
Publicar arquivos para o destino
Itens de projeto de computação

Quando o projeto é carregado, os itens de projeto (arquivos) são computados. O atributo item type determina
como o arquivo é processado. Por padrão, os arquivos .cs são incluídos na lista de itens Compile . Os arquivos na
lista de itens Compile são compilados.
A lista de itens Content contém arquivos que são publicados juntamente com as saídas de build. Por padrão, os
arquivos correspondendo ao padrão wwwroot/** são incluídos no item Content . O padrão glob wwwroot/\*\*
corresponde a todos os arquivos na pasta wwwroot e subpastas. Para adicionar explicitamente um arquivo à lista
de publicação, adicione o arquivo diretamente no arquivo .csproj conforme mostrado em Arquivos de Inclusão.
Ao selecionar o botão Publicar no Visual Studio ou ao publicar da linha de comando:
Os itens/propriedades são calculados (os arquivos necessários para compilar).
Somente Visual Studio: pacotes NuGet são restaurados. (A restauração precisa ser explícita pelo usuário na
CLI.)
O projeto é compilado.
Os itens de publicação são computados (os arquivos necessários para a publicação).
O projeto é publicado (os arquivos computados são copiados para o destino de publicação).
Quando um projeto do ASP.NET Core faz referência a Microsoft.NET.Sdk.Web no arquivo de projeto, um arquivo
app_offline.htm é colocado na raiz do diretório do aplicativo Web. Quando o arquivo estiver presente, o módulo
do ASP.NET Core apenas desligará o aplicativo e servirá o arquivo app_offline.htm durante a implantação. Para
obter mais informações, consulte Referência de configuração do módulo do ASP.NET Core.
Publicação de linha de comando básica

A publicação de linha de comando funciona em todas as plataformas compatíveis com o .NET Core e não requer
o Visual Studio. Nas amostras abaixo, o comando dotnet publish é executado no diretório do projeto (que contém
o arquivo .csproj). Se você não estiver na pasta do projeto, passe explicitamente no caminho do arquivo de
projeto. Por exemplo:
dotnet publish C:\Webs\Web1
Execute os comandos a seguir para criar e publicar um aplicativo Web:
dotnet new mvc

dotnet publish
dotnet new mvc

dotnet restore
dotnet publish
O comando dotnet publish gera uma saída semelhante à seguinte:
C:\Webs\Web1>dotnet publish
Microsoft (R) Build Engine version 15.3.409.57025 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.
Web1 -> C:\Webs\Web1\bin\Debug\netcoreapp2.0\Web1.dll

Web1 -> C:\Webs\Web1\bin\Debug\netcoreapp2.0\publish\
A pasta de publicação padrão é bin\$(Configuration)\netcoreapp<version>\publish . O padrão para

$(Configuration) é Debug. Na amostra anterior, o <TargetFramework> é netcoreapp2.0 .
dotnet publish -h exibe informações de ajuda para publicação.

O comando a seguir especifica um build de Release e o diretório de publicação:
dotnet publish -c Release -o C:\MyWebs\test
O comando dotnet publish chama MSBuild, que invoca o destino Publish . Quaisquer parâmetros passados para
dotnet publish são passados para o MSBuild. O parâmetro -c é mapeado para a propriedade do MSBuild
Configuration . O parâmetro -o é mapeado para OutputPath .
Propriedades do MSBuild podem ser passadas usando qualquer um dos seguintes formatos:
p:<NAME>=<VALUE>
/p:<NAME>=<VALUE>
O comando a seguir publica um build de Release para um compartilhamento de rede:

dotnet publish -c Release /p:PublishDir=//r8/release/AdminWeb
O compartilhamento de rede é especificado com barras "/" ( //r8/) e funciona em todas as plataformas com
suporte do .NET Core.
Confirme que o aplicativo publicado para implantação não está em execução. Os arquivos da pasta publish são
bloqueados quando o aplicativo está em execução. A implantação não pode ocorrer porque arquivos bloqueados
não podem ser copiados.
Perfis de publicação
Esta seção usa o Visual Studio 2017 para criar um perfil de publicação. Uma vez criado, é possível publicar do
Visual Studio ou da linha de comando.
Perfis de publicação podem simplificar o processo de publicação e podem existir em qualquer número. Crie um
perfil de publicação no Visual Studio escolhendo um dos seguintes caminhos:
Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Publicar.
Como alternativa, você pode selecionar Publicar <nome_do_projeto> no menu Build.
A guia Publicar da página de capacidades do aplicativo é exibida. Se o projeto não tem um perfil de publicação, a
página a seguir é exibida:
Quando a opção Pasta é selecionada, especifique um caminho de pasta para armazenar os ativos publicados. A
pasta padrão é bin\Release\PublishOutput. Clique no botão Criar Perfil para concluir.
Depois de um perfil de publicação ser criado, a guia Publicar é alterada. O perfil recém-criado é exibido em uma
lista suspensa. Clique em Criar novo perfil para fazer isso.
O Assistente de publicação dá suporte aos destinos de publicação a seguir:
Máquinas Virtuais do Azure
IIS, FTP, etc. (para qualquer servidor Web)
Pasta
Importar Perfil
Para obter mais informações, confira Quais opções de publicação são adequadas para mim.
Quando você cria um perfil de publicação com o Visual Studio, um arquivo do MSBuild
Properties/PublishProfiles/<nome_do_perfil>.pubxml é criado. O .pubxml é um arquivo do MSBuild e contém
definições de configuração de publicação. Esse arquivo pode ser alterado para personalizar o processo de build e
de publicação. Esse arquivo é lido pelo processo de publicação. <LastUsedBuildConfiguration> é especial porque é
uma propriedade global e não deverá estar em nenhum arquivo importado no build. Para obter mais
informações, confira MSBuild: como definir a propriedade de configuração.
Ao publicar em um destino do Azure, o arquivo .pubxml contém o identificador de assinatura do Azure. Com esse
tipo de destino, não é recomendável adicionar esse arquivo ao controle do código-fonte. Ao publicar em um
destino não Azure, é seguro fazer check-in do arquivo .pubxml.
Informações confidenciais (como a senha de publicação) são criptografadas em um nível por usuário/computador.
Elas são armazenadas no arquivo Properties/PublishProfiles/<nome_do_perfil>.pubxml.user. Já que esse arquivo
pode armazenar informações confidenciais, o check-in dele não deve ser realizado no controle do código-fonte.
Para obter uma visão geral de como publicar um aplicativo Web do ASP.NET Core, veja Hospedar e implantar. As
tarefas e os destinos de MSBuild necessários para publicar um aplicativo ASP.NET Core são de software livre no
https://github.com/aspnet/websdk.
O dotnet publish pode usar os perfis de publicação de pasta, MSDeploy e Kudu:
Pasta (funciona em modo multiplataforma):
dotnet publish WebApplication.csproj /p:PublishProfile=<FolderProfileName>
MSDeploy (atualmente só funciona no Windows, uma vez que o MSDeploy não é multiplataforma):
dotnet publish WebApplication.csproj /p:PublishProfile=<MsDeployProfileName> /p:Password=<DeploymentPassword>
Pacote MSDeploy (atualmente só funciona no Windows, uma vez que o MSDeploy não é multiplataforma):
dotnet publish WebApplication.csproj /p:PublishProfile=<MsDeployPackageProfileName>
Nos exemplos anteriores, não passe o deployonbuild para dotnet publish .

Para obter mais informações, confira Microsoft.NET.Sdk.Publish.
O dotnet publish dá suporte às APIs do Kudu, para publicar no Azure de qualquer plataforma. A publicação do
Visual Studio dá suporte às APIs do Kudu, mas ela é compatível com o WebSDK para publicação multiplataforma
para o Azure.
Adicione um perfil de publicação à pasta Properties/PublishProfiles com o seguinte conteúdo:
<Project>
<PropertyGroup>
<PublishProtocol>Kudu</PublishProtocol>
<PublishSiteName>nodewebapp</PublishSiteName>
<UserName>username</UserName>
<Password>password</Password>
</PropertyGroup>
</Project>
Execute o seguinte comando para compactar os conteúdos de publicação e publicá-los no Azure usando as APIs
do Kudu:
dotnet publish /p:PublishProfile=Azure /p:Configuration=Release
Defina as seguintes propriedades de MSBuild ao usar um perfil de publicação:

DeployOnBuild=true
PublishProfile=<Publish profile name>
Ao publicar com um perfil chamado FolderProfile, é possível executar qualquer um dos comandos abaixo:
dotnet build /p:DeployOnBuild=true /p:PublishProfile=FolderProfile
msbuild /p:DeployOnBuild=true /p:PublishProfile=FolderProfile
Ao invocar dotnet build, ele chama msbuild para executar o processo de build e de publicação. Chamar
dotnet build ou msbuild é equivalente ao passar um perfil de pasta. Ao chamar o MSBuild diretamente no
Windows, a versão do .NET Framework do MSBuild é usada. O MSDeploy é atualmente limitado a computadores
Windows para a publicação. Chamar dotnet build em um perfil não de pasta invoca o MSBuild que, por sua vez,
usa MSDeploy em perfis não de pasta. Chamar dotnet build em um perfil não de pasta invoca o MSBuild
(usando MSDeploy) e resulta em uma falha (mesmo quando em execução em uma plataforma do Windows). Para
publicar com um perfil não de pasta, chame o MSBuild diretamente.
A pasta de perfil de publicação a seguir foi criada com o Visual Studio e publica em um compartilhamento de
rede:


<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<WebPublishMethod>FileSystem</WebPublishMethod>
<PublishProvider>FileSystem</PublishProvider>
<LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
<LastUsedPlatform>Any CPU</LastUsedPlatform>
<SiteUrlToLaunchAfterPublish />
<LaunchSiteAfterPublish>True</LaunchSiteAfterPublish>
<ExcludeApp_Data>False</ExcludeApp_Data>
<PublishFramework>netcoreapp1.1</PublishFramework>
<ProjectGuid>c30c453c-312e-40c4-aec9-394a145dee0b</ProjectGuid>
<publishUrl>\\r8\Release\AdminWeb</publishUrl>
<DeleteExistingFiles>False</DeleteExistingFiles>
</PropertyGroup>
</Project>
Observe que <LastUsedBuildConfiguration> é definido como Release . Ao publicar no Visual Studio, o valor da
propriedade de configuração <LastUsedBuildConfiguration> é definido usando o valor quando o processo de
publicação é iniciado. A propriedade de configuração <LastUsedBuildConfiguration> é especial e não deve ser
substituída em um arquivo do MSBuild importado. Essa propriedade pode ser substituída da linha de comando.
Usando a CLI do .NET Core:
dotnet build -c Release /p:DeployOnBuild=true /p:PublishProfile=FolderProfile
Usando o MSBuild:
msbuild /p:Configuration=Release /p:DeployOnBuild=true /p:PublishProfile=FolderProfile
Publicar em um ponto de extremidade do MSDeploy da linha de

comando
A publicação pode ser feita usando a CLI do .NET Core ou o MSBuild. dotnet publish é executado no contexto
do .NET Core. O comando msbuild requer o .NET Framework, que limita-o a ambientes Windows.
A maneira mais fácil publicar com MSDeploy é primeiro criar um perfil de publicação no Visual Studio de 2017 e
usar o perfil da linha de comando.
Na amostra a seguir, um aplicativo Web do ASP.NET Core é criado (usando dotnet new mvc ) e um perfil de
publicação do Azure é adicionado com o Visual Studio.
Execute msbuild de um Prompt de Comando do Desenvolvedor para VS 2017. O Prompt de Comando do
Desenvolvedor terá o msbuild.exe correto em seu caminho com algumas variáveis do MSBuild definidas.
O MSBuild usa a sintaxe a seguir:
msbuild <path-to-project-file> /p:DeployOnBuild=true /p:PublishProfile=<Publish Profile> /p:Username=
<USERNAME> /p:Password=<PASSWORD>
Obtenha o Password do arquivo <Nome da publicação>.PublishSettings. Baixe o arquivo .PublishSettings de uma

das seguintes opções:
Gerenciador de Soluções: clique com o botão direito do mouse no aplicativo Web e selecione Baixar Perfil de
Publicação.
Portal do Azure: clique em Obter perfil de publicação no painel Visão geral de seu aplicativo Web.
Username pode ser encontrado no perfil de publicação.
A amostra a seguir usa o perfil de publicação Web11112 – Implantação da Web:
msbuild "C:\Webs\Web1\Web1.csproj" /p:DeployOnBuild=true

/p:PublishProfile="Web11112 - Web Deploy" /p:Username="$Web11112"
/p:Password="<password removed>"
Excluir arquivos
Ao publicar aplicativos Web do ASP.NET Core, os artefatos de build e o conteúdo da pasta wwwroot são
incluídos. msbuild dá suporte a padrões de caractere curinga. Por exemplo, o elemento <Content> a seguir exclui
todos os arquivos de texto (.txt) da pasta wwwroot/content e de todas as suas subpastas.
<ItemGroup>
<Content Update="wwwroot/content/**/*.txt" CopyToPublishDirectory="Never" />
</ItemGroup>
A marcação anterior pode ser adicionada a um perfil de publicação ou ao arquivo .csproj. Quando adicionada ao
arquivo .csproj, a regra será adicionada a todos os perfis de publicação no projeto.
O elemento <MsDeploySkipRules> a seguir exclui todos os arquivos da pasta wwwroot/content:
<ItemGroup>
<MsDeploySkipRules Include="CustomSkipFolder">
<ObjectName>dirPath</ObjectName>
<AbsolutePath>wwwroot\\content</AbsolutePath>
</MsDeploySkipRules>
</ItemGroup>
<MsDeploySkipRules> não exclui os destinos de ignorados do site de implantação. Pastas e arquivos de destino de
<Content> são excluídos do site de implantação. Por exemplo, suponha que um aplicativo Web implantado tinha
os seguintes arquivos:
Views/Home/About1.cshtml
Nos elementos <MsDeploySkipRules> a seguir, esses arquivos não seriam excluídos no site de implantação.
<ItemGroup>
<MsDeploySkipRules Include="CustomSkipFile">
<ObjectName>filePath</ObjectName>
<AbsolutePath>Views\\Home\\About1.cshtml</AbsolutePath>
</ItemGroup>
Os elementos <MsDeploySkipRules> anteriores impedem que os arquivos ignorados sejam implantados. Ele não
excluirá esses arquivos depois que eles forem implantados.
O elemento <Content> a seguir exclui os arquivos de destino no site de implantação:
<ItemGroup>
<Content Update="Views/Home/About?.cshtml" CopyToPublishDirectory="Never" />
</ItemGroup>
O uso da implantação de linha de comando com o elemento <Content> anterior produz a seguinte saída:
MSDeployPublish:
Starting Web deployment task from source:
manifest(C:\Webs\Web1\obj\Release\netcoreapp1.1\PubTmp\Web1.SourceManifest.
xml) to Destination: auto().
Deleting file (Web11112\Views\Home\About1.cshtml).
Updating file (Web11112\web.config).
Updating file (Web11112\Web1.deps.json).
Updating file (Web11112\Web1.dll).
Updating file (Web11112\Web1.pdb).
Updating file (Web11112\Web1.runtimeconfig.json).
Successfully executed Web deployment task.
Publish Succeeded.
Done Building Project "C:\Webs\Web1\Web1.csproj" (default targets).
Incluir arquivos
A marcação a seguir inclui uma pasta images fora do diretório do projeto para a pasta wwwroot/images do site
de publicação:
<ItemGroup>
<_CustomFiles Include="$(MSBuildProjectDirectory)/../images/**/*" />
<DotnetPublishFiles Include="@(_CustomFiles)">
<DestinationRelativePath>wwwroot/images/%(RecursiveDir)%(Filename)%(Extension)</DestinationRelativePath>
</DotnetPublishFiles>
</ItemGroup>
A marcação pode ser adicionada ao arquivo .csproj ou ao perfil de publicação. Se ela for adicionada ao arquivo
.csproj, ela será incluída em cada perfil de publicação no projeto.
A marcação realçada a seguir mostra como:
Copiar um arquivo de fora do projeto para a pasta wwwroot.
Excluir a pasta wwwroot\Content.
Excluir Views\Home\About2.cshtml.


<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<WebPublishMethod>FileSystem</WebPublishMethod>
<PublishProvider>FileSystem</PublishProvider>
<LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
<LastUsedPlatform>Any CPU</LastUsedPlatform>
<SiteUrlToLaunchAfterPublish />
<LaunchSiteAfterPublish>True</LaunchSiteAfterPublish>
<ExcludeApp_Data>False</ExcludeApp_Data>
<PublishFramework />
<ProjectGuid>afa9f185-7ce0-4935-9da1-ab676229d68a</ProjectGuid>
<publishUrl>bin\Release\PublishOutput</publishUrl>
<DeleteExistingFiles>False</DeleteExistingFiles>
</PropertyGroup>
<ItemGroup>
<ResolvedFileToPublish Include="..\ReadMe2.MD">
<RelativePath>wwwroot\ReadMe2.MD</RelativePath>
</ResolvedFileToPublish>
<Content Update="wwwroot\Content\**\*" CopyToPublishDirectory="Never" />

<Content Update="Views\Home\About2.cshtml" CopyToPublishDirectory="Never" />
</ItemGroup>
</Project>
Consulte o Leiame do WebSDK para obter mais amostras de implantação.
Executar um destino antes ou depois da publicação

Os destinos BeforePublish e AfterPublish internos executam um destino antes ou após o destino de publicação.
Adicione os elementos a seguir ao perfil de publicação para registrar em log as mensagens de console antes e
após a publicação:
<Target Name="CustomActionsBeforePublish" BeforeTargets="BeforePublish">

<Message Text="Inside BeforePublish" Importance="high" />
</Target>
<Target Name="CustomActionsAfterPublish" AfterTargets="AfterPublish">
<Message Text="Inside AfterPublish" Importance="high" />
</Target>
Publicar em um servidor usando um certificado não confiável

Adicione a propriedade <AllowUntrustedCertificate> com um valor True ao perfil de publicação:
<PropertyGroup>
<AllowUntrustedCertificate>True</AllowUntrustedCertificate>
</PropertyGroup>
O serviço Kudu
Para exibir os arquivos em uma implantação de aplicativo Web do Serviço de Aplicativo do Azure, use o serviço
Kudu. Acrescente o token scm ao nome do aplicativo Web. Por exemplo:
URL RESULTADO
http://mysite.azurewebsites.net/ Aplicativo Web
http://mysite.scm.azurewebsites.net/ Serviço Kudu
Selecione o item de menu Console de Depuração para exibir, editar, excluir ou adicionar arquivos.
Recursos adicionais
A Implantação da Web (MSDeploy) simplifica a implantação de aplicativos Web e sites da Web em servidores
IIS.
https://github.com/aspnet/websdk: problemas de arquivos e recursos de solicitação para implantação.
Publicar um aplicativo Web ASP.NET em uma VM do Azure usando o Visual Studio
Estrutura do diretório do ASP.NET Core
Por Luke Latham

No ASP.NET Core, o diretório de aplicativo publicado, publicar, é composto de arquivos de aplicativo, arquivos
de configuração, ativos estáticos, pacotes e o tempo de execução (para implantações autossuficientes).
TIPO DE APLICATIVO ESTRUTURA DE DIRETÓRIOS
Implantação dependente de estrutura publish†

Logs† (opcional, a menos que necessário para
receber logs de stdout)
Exibições† (aplicativos MVC; se as exibições
não são pré-compiladas)
Páginas† (aplicativos de Páginas do Razor ou
MVC, se as páginas não são pré-compiladas)
wwwroot†
arquivos *.dll
<nome-do-assembly>.deps.json
<nome-do-assembly>.dll
<nome-do-assembly>.pdb
<nome-do-assembly>.PrecompiledViews.dll
<nome-do-assembly>.PrecompiledViews.pdb
<nome-do-assembly>.runtimeconfig.json
web.config (implantações do IIS)
Implantação autossuficiente publish†

Logs† (opcional, a menos que necessário para
receber logs de stdout)
refs†
Exibições† (aplicativos MVC; se as exibições
não são pré-compiladas)
Páginas† (aplicativos de Páginas do Razor ou
MVC, se as páginas não são pré-compiladas)
wwwroot†
arquivos *.dll
<nome-do-assembly>.deps.json
<nome-do-assembly>.exe
<nome-do-assembly>.pdb
<nome-do-assembly>.PrecompiledViews.dll
<nome-do-assembly>.PrecompiledViews.pdb
<nome-do-assembly>.runtimeconfig.json
web.config (implantações do IIS)
†Indica um diretório
O diretório publish representa o caminho raiz de conteúdo (também chamado de caminho base do aplicativo)
da implantação. Qualquer que seja o nome fornecido para o diretório publish do aplicativo implantado no
servidor, o local dele serve como o caminho físico do servidor para o aplicativo hospedado.
O diretório wwwroot, se presente, contém somente ativos estáticos.
O diretório Logs de stdout pode ser criado para a implantação usando uma das duas abordagens a seguir:
Adicione o seguinte elemento <Target> ao arquivo de projeto:
<Target Name="CreateLogsFolder" AfterTargets="Publish">

<MakeDir Directories="$(PublishDir)Logs"
Condition="!Exists('$(PublishDir)Logs')" />
<WriteLinesToFile File="$(PublishDir)Logs\.log"
Lines="Generated file"
Overwrite="True"
Condition="!Exists('$(PublishDir)Logs\.log')" />
</Target>
O elemento <MakeDir> cria uma pasta Logs vazia na saída publicada. O elemento usa a propriedade
PublishDir para determinar o local de destino no qual criar a pasta. Vários métodos de implantação,
como a Implantação da Web, ignoram pastas vazias durante a implantação. O elemento
<WriteLinesToFile> gera um arquivo na pasta Logs, o que garante a implantação da pasta no servidor.
Observe que a criação de pasta ainda pode falhar se o processo de trabalho não tem acesso de gravação
para a pasta de destino.
Crie fisicamente o diretório Logs no servidor na implantação.
O diretório de implantação requer permissões de leitura/execução. O diretório Logs requer permissões de
leitura/gravação. Diretórios adicionais em que os arquivos são gravados exigem permissões de
leitura/gravação.
Referência de erros comuns para o Serviço de
Aplicativo do Azure e o IIS com o ASP.NET Core
Por Luke Latham

A lista a seguir não é uma lista completa de erros. Se você encontrar um erro não listado aqui, abra um novo
problema com instruções detalhadas para reproduzir o erro.
Colete as seguintes informações:
Comportamento do navegador
Entradas do Log de Eventos do Aplicativo
Entradas do log de stdout do Módulo do ASP.NET Core
Compare as informações para os erros comuns a seguir. Se uma correspondência for encontrada, siga o aviso
de solução de problemas.
IMPORTANT
O instalador não pode obter os Pacotes Redistribuíveis do VC++

Exceção do Instalador: 0x80072efd ou 0x80072f76 – erro não especificado
Exceção do Log do Instalador†: erro 0x80072efd ou 0x80072f76: falha ao executar o pacote EXE
†O log está localizado em C:\Users\
{USER }\AppData\Local\Temp\dd_DotNetCoreWinSvrHosting__{timestamp}.log.
Solução de problemas:
Se o sistema não tiver acesso à Internet durante a instalação do pacote de hospedagem, essa exceção
ocorrerá quando o instalador for impedido de obter os Pacotes Redistribuíveis do Microsoft Visual C++
2015. Obtenha um instalador do Centro de Download da Microsoft. Se o instalador falhar, o servidor poderá
não receber o tempo de execução do .NET Core necessário para hospedar uma FDD (implantação
dependente de estrutura). Ao hospedar uma FDD, confirme se o tempo de execução está instalado em
Programas & Recursos. Se necessário, obtenha um instalador de tempo de execução de Todos os Downloads
do .NET. Depois de instalar o tempo de execução, reinicie o sistema ou o IIS executando net stop was /y
seguido por net start w3svc em um prompt de comando.
O upgrade do sistema operacional removeu o Módulo do ASP.NET

Core de 32 bits
Log do Aplicativo: a DLL do Módulo C:\WINDOWS\system32\inetsrv\aspnetcore.dll falhou ao ser
carregada. Os dados são o erro.
Arquivos que não são do sistema operacional no diretório C:\Windows\SysWOW64\inetsrv não são
preservados durante um upgrade do sistema operacional. Se o Módulo do ASP.NET Core estiver instalado
antes de uma atualização do sistema operacional e, em seguida, qualquer AppPool for executado no modo
de 32 bits após uma atualização do sistema operacional, esse problema será encontrado. Após um upgrade
do sistema operacional, repare o Módulo do ASP.NET Core. Veja Instalar o pacote de Hospedagem do .NET
Core. Selecione Reparar ao executar o instalador.
Conflitos de plataforma com o RID

Navegador: 502.5 Erro HTTP – falha do processo
Log do Aplicativo: o aplicativo 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY }' com a raiz física 'C:
{PATH}' falhou ao iniciar o processo com a linha de comando '"C:\{PATH}{assembly}.{exe|dll}" ', ErrorCode
= '0x80004005 : ff.
Log do Módulo do ASP.NET Core: exceção sem tratamento: System.BadImageFormatException: não
foi possível carregar o arquivo ou o assembly '{assembly}.dll'. Foi feita uma tentativa de carregar um
programa com um formato incorreto.
Confirme se o aplicativo é executado localmente no Kestrel. Uma falha do processo pode ser o resultado
de um problema no aplicativo. Para obter mais informações, confira Solução de problemas.
Confirme que o <PlatformTarget> no .csproj não entra em conflito com o RID. Por exemplo, não
especifique um <PlatformTarget> igual a x86 e publique com um RID igual a win10-x64 , usando dotnet
publish -c Release -r win10 -x64 ou definindo o <RuntimeIdentifiers> no .csproj como win10-x64 . O
projeto é publicado sem avisos nem erros, mas falha com as exceções registradas acima no sistema.
Se essa exceção ocorrer para uma implantação dos Aplicativos do Azure ao fazer upgrade de um
aplicativo e implantar assemblies mais recentes, exclua manualmente todos os arquivos da implantação
anterior. Assemblies incompatíveis remanescentes podem resultar em uma exceção
System.BadImageFormatException durante a implantação de um aplicativo atualizado.
Ponto de extremidade de URI incorreto ou site interrompido

Navegador: ERR_CONNECTION_REFUSED
Log do Aplicativo: nenhuma entrada
Log do Módulo do ASP.NET Core: arquivo de log não criado
Confirme se que o ponto de extremidade do URI correto para o aplicativo está sendo usado. Verifique as
associações.
Confirme que o site do IIS não está no estado Parado.
Recursos do servidor CoreWebEngine ou W3SVC desabilitados

Exceção do Sistema Operacional: os recursos CoreWebEngine e W3SVC do IIS 7.0 devem ser instalados
para usar o Módulo do ASP.NET Core.
Confirme que a função e os recursos apropriados estão habilitados. Consulte Configuração do IIS.
Caminho físico do site incorreto ou aplicativo ausente

Navegador: 403 Proibido – acesso negado OU 403.14 Proibido – o servidor Web está configurado para
não listar o conteúdo deste diretório.
Confira as Configurações Básicas no site do IIS e a pasta do aplicativo físico. Confirme que o aplicativo
está na pasta no Caminho físico do site do IIS.
Função incorreta, módulo não instalado ou permissões incorretas

Navegador: 500.19 Erro interno do servidor – a página solicitada não pode ser acessada porque os
dados de configuração relacionados da página são inválidos.
Confirme que você habilitou a função apropriada. Consulte Configuração do IIS.
Verifique Programas & Recursos e confirme se o Módulo do Microsoft ASP.NET Core foi instalado.
Se o Módulo do Microsoft ASP.NET Core não estiver presente na lista de programas instalados,
instale o módulo. Veja Instalar o pacote de Hospedagem do .NET Core.
Verifique se o Pool de aplicativos > Modelo de processo > Identidade está definido como
ApplicationPoolIdentity ou se a identidade personalizada tem as permissões corretas para acessar a
pasta de implantação do aplicativo.
processPath incorreto, variável de PATH ausente, pacote de

hospedagem não instalado, sistema/IIS não reiniciado, Pacotes
Redistribuíveis do VC++ não instalados ou violação de acesso de
dotnet.exe
Log do Aplicativo: o aplicativo 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY }' com a raiz física 'C:\
{PATH}' falhou ao iniciar o processo com a linha de comando '".{assembly}.exe" ', ErrorCode =
'0x80070002 : 0.
Log do Módulo do ASP.NET Core: arquivo de log criado, mas vazio
Verifique o atributo processPath no elemento <aspNetCore> em web.config para confirmar se ele é dotnet
para uma FDD (implantação dependente de estrutura) ou .{assembly }.exe para uma SCD (implantação
autossuficiente).
Para uma FDD, o dotnet.exe pode não estar acessível por meio das configurações de PATH. Confirme se
*C:\Program Files\dotnet* existe nas configurações de PATH do Sistema.
Para uma FDD, o dotnet.exe pode não estar acessível para a identidade do usuário do Pool de aplicativos.
Confirme se a identidade do usuário do AppPool tem acesso ao diretório C:\Program Files\dotnet.
Confirme se não há nenhuma regra de negação configurada para a identidade do usuário do AppPool no
C:\Arquivos de Programas\dotnet e nos diretórios do aplicativo.
Talvez você tenha implantado uma FDD e instalado o .NET Core sem reiniciar o IIS. Reinicie o servidor
ou o IIS executando net stop was /y seguido por net start w3svc em um prompt de comando.
Você pode ter implantado uma FDD sem instalar o tempo de execução do .NET Core no sistema de
hospedagem. Se o tempo de execução do .NET Core ainda não foi instalado, execute o Instalador do
Pacote de Hospedagem do .NET Core no sistema. Veja Instalar o pacote de Hospedagem do .NET
Core. Se estiver tentando instalar o tempo de execução do .NET Core em um sistema sem uma conexão
com a Internet, obtenha o tempo de execução em Todos os Downloads do .NET e execute o instalador do
pacote de hospedagem para instalar o Módulo do ASP.NET Core. Conclua a instalação reiniciando o
sistema ou o IIS executando net stop was /y seguido por net start w3svc em um prompt de comando.
Talvez você tenha implantado uma FDD e os Pacotes redistribuíveis do Microsoft Visual C++ 2015 (x64 )
não estejam instalados no sistema. Obtenha um instalador do Centro de Download da Microsoft.
Argumentos incorretos do elemento <aspNetCore>

{PATH}' falhou ao iniciar o processo com a linha de comando '"dotnet" .{assembly}.dll', ErrorCode =
'0x80004005 : 80008081.
Log do Módulo do ASP.NET Core: o aplicativo a ser executado não existe: 'PATH{assembly}.dll'
Examine o atributo arguments no elemento <aspNetCore> no web.config para confirmar se ele: (a) é .
{assembly }.dll de uma FDD (implantação dependente de estrutura); ou (b) não está presente, é uma
cadeia de caracteres vazia (arguments="") ou uma lista de argumentos do aplicativo (arguments="arg1,
arg2, ...") para uma SCD (implantação autossuficiente).
Versão do .NET Framework ausente

Navegador: 502.3 Gateway incorreto – Erro de conexão ao tentar encaminhar a solicitação.
Log do Aplicativo: ErrorCode = O aplicativo 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY }' com a
raiz física 'C:\{PATH}' falhou ao iniciar o processo com a linha de comando '"dotnet" .{assembly}.dll',
ErrorCode = '0x80004005 : 80008081.
Log do Módulo do ASP.NET Core: exceção do método, arquivo ou assembly ausente. O método, o
arquivo ou o assembly especificado na exceção é um método, arquivo ou assembly do .NET Framework.
Instale a versão do .NET Framework ausente no sistema.
Para uma FDD (implantação dependente de estrutura), confirme se você tem o tempo de execução
correto instalado no sistema. Se o projeto foi atualizado de 1.1 para 2.0 e implantado no sistema de
hospedagem e resultou nessa exceção, verifique se a estrutura 2.0 está no sistema de hospedagem.
Pool de aplicativos interrompido

Navegador: 503 Serviço não disponível
Confirme que o Pool de Aplicativos não está no estado Parado.
Middleware de Integração do IIS não implementado

{PATH}' criou um processo com a linha de comando '"C:\{PATH}{assembly}.{exe|dll}"', mas falhou, não
respondeu ou não escutou na porta '{PORT}' fornecida, ErrorCode = '0x800705b4'
Log do Módulo do ASP.NET Core: arquivo de log criado, mostrando uma operação normal.
Confirme que uma das seguintes condições é verdadeira:
O middleware de integração de IIS é referenciado chamando-se o método UseIISIntegration no
WebHostBuilder do aplicativo ( ASP.NET Core 1.x)
Os aplicativos usam o método CreateDefaultBuilder (ASP.NET Core 2.x).
Veja Hospedar no ASP.NET Core para obter mais detalhes.
O subaplicativo inclui uma seção <manipuladores>

Navegador: 500.19 Erro HTTP – erro interno do servidor
Log do Módulo do ASP.NET Core: arquivo de log criado, mostrando uma operação normal do
aplicativo raiz. O arquivo de log não foi criado para o subaplicativo.
Confirme se o arquivo web.config do subaplicativo não inclui uma seção <handlers> .
caminho do log de stdout incorreto

Navegador: o aplicativo responde normalmente.
Log do Aplicativo: Aviso: não foi possível criar o stdoutLogFile \?
\C:_apps\app_folder\bin\Release\netcoreapp2.0\win10-
x64\publish\logs\path_doesnt_exist\stdout_8748_201831835937.log, ErrorCode = -2147024893.
O caminho stdoutLogFile especificado no elemento <aspNetCore> de web.config não existe. Para obter mais
informações, veja a seção Criação e redirecionamento de log do tópico de referência de configuração do
Módulo do ASP.NET Core.
Problema geral de configuração do aplicativo

{PATH}' criou um processo com a linha de comando '"C:\{PATH}{assembly}.{exe|dll}"', mas falhou, não
respondeu ou não escutou na porta '{PORT}' fornecida, ErrorCode = '0x800705b4'
Log do Módulo do ASP.NET Core: arquivo de log criado, mas vazio
Essa exceção geral indica que o processo não pôde ser iniciado, provavelmente, devido a um problema de
configuração do aplicativo. Consultando Estrutura de diretório, confirme se as pastas e os arquivos
implantados do aplicativo são apropriados e se os arquivos de configuração do aplicativo estão presentes e
contêm as configurações corretas para o aplicativo e o ambiente. Para obter mais informações, confira
Solução de problemas.
Visão geral sobre a segurança do ASP.NET Core
O ASP.NET Core permite que desenvolvedores configurem e gerenciem facilmente a segurança de seus
aplicativos. O ASP.NET Core contém recursos para gerenciamento de autenticação, autorização, proteção de
dados, imposição de SSL, segredos de aplicativo, proteção contra falsificação de solicitação e gerenciamento de
CORS. Esses recursos de segurança permitem que você crie aplicativos de ASP.NET Core robustos e seguros ao
mesmo tempo.
Recursos de segurança do ASP.NET Core

O ASP.NET Core fornece várias ferramentas e bibliotecas para proteger seus aplicativos, incluindo provedores de
identidade internos, mas você pode usar serviços de identidade de terceiros, como Facebook, Twitter e LinkedIn.
Com o ASP.NET Core, você pode gerenciar facilmente os segredos do aplicativo, que são uma maneira de
armazenar e usar informações confidenciais sem a necessidade de expô-los no código.
Autenticação versus Autorização

A autenticação é um processo em que um usuário fornece credenciais que são comparadas àquelas armazenadas
em um sistema operacional, num banco de dados, no aplicativo ou no recurso. Se elas corresponderem, os
usuários se autenticarão com êxito e, assim, poderão realizar ações para as quais são autorizados, durante um
processo de autorização. A autorização é o processo que determina o que um usuário pode fazer.
Outra forma de pensar na autenticação é considerá-la como uma maneira de entrar em um espaço, como um
servidor, um banco de dados, um aplicativo ou um recurso, ao passo que a autorização refere-se a quais ações o
usuário poderá executar em que objetos dentro desse espaço (servidor, banco de dados ou aplicativo).
Vulnerabilidades comuns no software

O ASP.NET Core e o EF contêm recursos que ajudam a proteger seus aplicativos e impedir violações de segurança.
A seguinte lista de links leva à documentação com detalhe de técnicas para evitar as vulnerabilidades de segurança
mais comuns em aplicativos Web:
Ataques de script entre sites
Ataques de injeção de SQL
CSRF (solicitação intersite forjada)
Ataques de redirecionamento aberto
Há mais vulnerabilidades sobre as quais você deve estar atento. Para obter mais informações, consulte a seção
neste documento em Documentação de segurança do ASP.NET Core.
Documentação de segurança do ASP.NET Core

Autenticação
Introdução ao Identity
Habilitar a autenticação usando o Facebook, o Google e outros provedores externos
Habilitar a autenticação com o Web Services Federation
Configurar a Autenticação do Windows
Usar a autenticação de cookie sem o Identity
Integrar o Azure AD em um aplicativo Web ASP.NET Core
Chamar uma API Web ASP.NET Core em um aplicativo do WPF usando o Azure AD
Chamar uma API Web em um aplicativo Web ASP.NET Core usando o Azure AD
Um aplicativo Web ASP.NET Core com o Azure AD B2C
Proteger aplicativos ASP.NET Core com o IdentityServer4
Autorização
Introdução
Criar um aplicativo com os dados do usuário protegidos por autorização
Autorização simples
Autorização baseada em função
Autorização baseada em declarações
Autorização baseada em política
Injeção de dependência em manipuladores de requisitos
Autorização baseada em recursos
Autorização baseada em exibição
Limitar a identidade por esquema
Proteção de dados
Introdução à proteção de dados
Introdução às APIs de proteção de dados
APIs de consumidor
Visão geral das APIs de consumidor
Cadeias de caracteres de finalidade
Multilocação e hierarquia de finalidade
Senhas hash
Limitar o tempo de vida de cargas protegidas
Desproteger cargas cujas chaves foram revogadas
Configuração
Configurar a proteção de dados
Configurações padrão
Política ampla de computador
Cenários sem reconhecimento de DI
APIs de extensibilidade
APIs diversas
Implementação
Compatibilidade
Substitua <machineKey> no ASP.NET
Criar um aplicativo com os dados do usuário protegidos por autorização
Armazenamento seguro dos segredos do aplicativo no desenvolvimento
Impor o SSL
Prevenir ataques de redirecionamento abertos
Evitar scripts entre sites
Habilitar o CORS (Solicitações Entre Origens)
Compartilhar cookies entre aplicativos
Lista segura de IP
Por Rick Anderson

O ASP.NET Core Identity é um sistema de associação que adiciona a funcionalidade de logon para
aplicativos ASP.NET Core. Os usuários podem criar uma conta com as informações de logon armazenadas
no Identity ou eles podem usar um provedor de logon externo. Provedores de logon externo com suporte
incluem Facebook, Google, Account da Microsoft e Twitter.
Identidade pode ser configurada usando um banco de dados do SQL Server para armazenar nomes de
usuário, senhas e dados de perfil. Como alternativa, outro repositório persistente pode ser usado, por
exemplo, o armazenamento de tabelas do Azure.
Exibir ou baixar o código de exemplo (como baixar)).
Neste tópico, saiba como usar a identidade para registrar, faça logon e logoff de um usuário. Para obter
instruções mais detalhadas sobre como criar aplicativos que usam a identidade, consulte a seção próximas
etapas no final deste artigo.
AddDefaultIdentity e AddIdentity
AddDefaultIdentity foi introduzido no ASP. Core 2.1. Chamar AddDefaultIdentity é semelhante a chamar o
seguinte:
AddIdentity
AddDefaultUI
AddDefaultTokenProviders
Ver AddDefaultIdentity fonte para obter mais informações.
Criar um aplicativo Web com autenticação

Crie um projeto de aplicativo Web ASP.NET Core com contas de usuário individuais.
Visual Studio
CLI do .NET Core
Selecione Arquivo > Novo > Projeto.
Selecione Aplicativo Web ASP.NET Core. Nomeie o projeto WebApp1 para ter o mesmo namespace
que o download do projeto. Clique em OK.
Selecione um ASP.NET Core aplicativo Web para o ASP.NET Core 2.1, em seguida, selecione alterar
autenticação.
Selecione contas de usuário individuais e clique em Okey.
Fornece o projeto gerado ASP.NET Core Identity como um biblioteca de classes Razor.
Registro de teste e de logon
Execute o aplicativo e registrar um usuário. Dependendo do tamanho da tela, você talvez precise selecionar
o botão de alternância de navegação para ver os registre e Login links.
Exibir o banco de dados de identidade
Visual Studio
CLI do .NET Core
Dos modo de exibição menu, selecione Pesquisador de objetos do SQL Server (SSOX).
Navegue até (localdb) MSSQLLocalDB (SQL Server 13). Clique duas vezes em dbo. AspNetUsers
> exibir dados:
Configurar os serviços de identidade

Serviços são adicionados no ConfigureServices . O padrão típico consiste em chamar todos os métodos
Add{Service} e, em seguida, chamar todos os métodos services.Configure{Service} . O código a seguir não
inclui o modelo gerado CookiePolicyOptions :

{
options.UseSqlServer(
Configuration.GetConnectionString("DefaultConnection")));
services.AddDefaultIdentity<IdentityUser>()
.AddEntityFrameworkStores<ApplicationDbContext>();
services.Configure<IdentityOptions>(options =>
{
// Password settings.
options.Password.RequireDigit = true;
options.Password.RequireLowercase = true;
options.Password.RequireNonAlphanumeric = true;
options.Password.RequireUppercase = true;
options.Password.RequiredLength = 6;
options.Password.RequiredUniqueChars = 1;
// Lockout settings.
options.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(5);
options.Lockout.MaxFailedAccessAttempts = 5;
options.Lockout.AllowedForNewUsers = true;
// User settings.
options.User.AllowedUserNameCharacters =
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._@+";
options.User.RequireUniqueEmail = false;
});
services.ConfigureApplicationCookie(options =>
{
// Cookie settings
options.ExpireTimeSpan = TimeSpan.FromMinutes(5);
options.LoginPath = "/Identity/Account/Login";
options.AccessDeniedPath = "/Identity/Account/AccessDenied";
options.SlidingExpiration = true;
});
}
O código anterior configura a identidade com os valores de opção padrão. Serviços são disponibilizados
para o aplicativo por meio injeção de dependência.
Identidade é habilitada por meio da chamada UseAuthentication. UseAuthentication Adiciona a
autenticação middleware ao pipeline de solicitação.
{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
{
{
// Password settings
options.Password.RequireNonAlphanumeric = false;
options.Password.RequireLowercase = false;
// Lockout settings
// User settings
options.User.RequireUniqueEmail = true;
});
{
// Cookie settings
// If the LoginPath isn't set, ASP.NET Core defaults
// the path to /Account/Login.
options.LoginPath = "/Account/Login";
// If the AccessDeniedPath isn't set, ASP.NET Core defaults
// the path to /Account/AccessDenied.
options.AccessDeniedPath = "/Account/AccessDenied";
});

services.AddTransient<IEmailSender, EmailSender>();
services.AddMvc();
}
Serviços são disponibilizados para o aplicativo por meio injeção de dependência.

Identidade é habilitada para o aplicativo, chamando UseAuthentication no Configure método.
UseAuthentication Adiciona a autenticação middleware ao pipeline de solicitação.
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
{
{
}
else
{
}
{
routes.MapRoute(
name: "default",
});
}

{
services.AddMvc();
// Configure Identity
{
// Lockout settings
// Cookie settings
options.Cookies.ApplicationCookie.ExpireTimeSpan = TimeSpan.FromDays(150);
options.Cookies.ApplicationCookie.LoginPath = "/Account/Login";
// User settings
});

}
Esses serviços são disponibilizados para o aplicativo por meio injeção de dependência.
Identidade é habilitada para o aplicativo, chamando UseIdentity no Configure método. UseIdentity
Adiciona a autenticação baseada em cookie middleware ao pipeline de solicitação.

{
{
}
else
{
}
app.UseIdentity();
// Add external authentication middleware below. To configure them please see

https://go.microsoft.com/fwlink/?LinkID=532715
{
routes.MapRoute(
name: "default",
});
}
Para obter mais informações, consulte o classe IdentityOptions e inicialização do aplicativo.
Registre-se de Scaffold, logon e logoff

Siga o criar o scaffolding de identidade em um projeto do Razor com autorização instruções para gerar o
código mostrado nesta seção.
Visual Studio
CLI do .NET Core
Adicione os arquivos de registro, logon e logoff.
Registre -se de examinar
Quando um usuário clica o registre link, o RegisterModel.OnPostAsync ação é invocada. O usuário é criado
pelo CreateAsync sobre o _userManager objeto. _userManager é fornecido pela injeção de dependência):
public async Task<IActionResult> OnPostAsync(string returnUrl = null)
{
returnUrl = returnUrl ?? Url.Content("~/");
{
var user = new IdentityUser { UserName = Input.Email, Email = Input.Email };
var result = await _userManager.CreateAsync(user, Input.Password);
if (result.Succeeded)
{
_logger.LogInformation("User created a new account with password.");
var code = await _userManager.GenerateEmailConfirmationTokenAsync(user);

var callbackUrl = Url.Page(
"/Account/ConfirmEmail",
pageHandler: null,
values: new { userId = user.Id, code = code },
protocol: Request.Scheme);
await _emailSender.SendEmailAsync(Input.Email, "Confirm your email",

$"Please confirm your account by <a
href='{HtmlEncoder.Default.Encode(callbackUrl)}'>clicking here</a>.");
await _signInManager.SignInAsync(user, isPersistent: false);

return LocalRedirect(returnUrl);
}
foreach (var error in result.Errors)
{
ModelState.AddModelError(string.Empty, error.Description);
}
}
// If we got this far, something failed, redisplay form

return Page();
}
Quando um usuário clica o registre link, o Register ação é invocada em AccountController . O Register
ação cria o usuário chamando CreateAsync sobre o _userManager objeto (fornecidas para
AccountController pela injeção de dependência):
//
// POST: /Account/Register
[HttpPost]
[AllowAnonymous]
public async Task<IActionResult> Register(RegisterViewModel model)
{
{
var user = new ApplicationUser { UserName = model.Email, Email = model.Email };
var result = await _userManager.CreateAsync(user, model.Password);
{
// For more information on how to enable account confirmation and password reset please
visit http://go.microsoft.com/fwlink/?LinkID=532713
// Send an email with this link
//var code = await _userManager.GenerateEmailConfirmationTokenAsync(user);
//var callbackUrl = Url.Action("ConfirmEmail", "Account", new { userId = user.Id, code =
code }, protocol: HttpContext.Request.Scheme);
//await _emailSender.SendEmailAsync(model.Email, "Confirm your account",
// "Please confirm your account by clicking this link: <a href=\"" + callbackUrl +
"\">link</a>");
_logger.LogInformation(3, "User created a new account with password.");
return RedirectToAction(nameof(HomeController.Index), "Home");
}
AddErrors(result);
}

return View(model);
}
Se o usuário foi criado com êxito, o usuário é conectado pela chamada para _signInManager.SignInAsync .
Observação: consulte a confirmação de conta para verificar as etapas para impedir o logon imediato no
registro.
Fazer Logon
O formulário de logon é exibido quando:
O faça logon no link é selecionado.
Um usuário tenta acessar uma página restrita que eles não estão autorizados a acessar ou quando eles
ainda não foram autenticados pelo sistema.
Quando o formulário na página de logon é enviado, o OnPostAsync ação é chamada. PasswordSignInAsync é
chamado de _signInManager (fornecido pela injeção de dependência) do objeto.
{
{
// This doesn't count login failures towards account lockout
// To enable password failures to trigger account lockout,
// set lockoutOnFailure: true
var result = await _signInManager.PasswordSignInAsync(Input.Email,
Input.Password, Input.RememberMe, lockoutOnFailure: true);
{
_logger.LogInformation("User logged in.");
}
if (result.RequiresTwoFactor)
{
return RedirectToPage("./LoginWith2fa", new { ReturnUrl = returnUrl,
RememberMe = Input.RememberMe });
}
if (result.IsLockedOut)
{
_logger.LogWarning("User account locked out.");
return RedirectToPage("./Lockout");
}
else
{
ModelState.AddModelError(string.Empty, "Invalid login attempt.");
return Page();
}
}

return Page();
}
A base Controller classe expõe um User propriedade que você pode acessar métodos do controlador. Por
exemplo, você pode enumerar User.Claims e tomar decisões de autorização. Para obter mais informações,
consulte Introdução à autorização no núcleo do ASP.NET.
O formulário de logon é exibido quando os usuários selecionam o faça logon no vincular ou será
redirecionado ao acessar uma página que requer autenticação. Quando o usuário envia o formulário na
página de login, a ação AccountController Login é chamada.
O Login faz chamadas PasswordSignInAsync no objeto _signInManager (fornecido pelo AccountController
por injeção de dependência).
//
// POST: /Account/Login
[HttpPost]
[AllowAnonymous]
public async Task<IActionResult> Login(LoginViewModel model, string returnUrl = null)
{
ViewData["ReturnUrl"] = returnUrl;
{
// This doesn't count login failures towards account lockout
// To enable password failures to trigger account lockout, set lockoutOnFailure: true
var result = await _signInManager.PasswordSignInAsync(model.Email,
model.Password, model.RememberMe, lockoutOnFailure: false);
{
_logger.LogInformation(1, "User logged in.");
return RedirectToLocal(returnUrl);
}
{
return RedirectToAction(nameof(SendCode), new { ReturnUrl = returnUrl, RememberMe =
model.RememberMe });
}
{
_logger.LogWarning(2, "User account locked out.");
return View("Lockout");
}
else
{
return View(model);
}
}

return View(model);
}
A base de ( Controller ou PageModel ) classe expõe um User propriedade. Por exemplo, User.Claims
podem ser enumeradas para tomar decisões de autorização.
Fazer logoff
O fazer logoff link invoca o LogoutModel.OnPost ação.
using System;
using System.Linq;
using Microsoft.AspNetCore.Identity;
namespace WebApp1.Areas.Identity.Pages.Account
{
[AllowAnonymous]
public class LogoutModel : PageModel
{
private readonly SignInManager<IdentityUser> _signInManager;
private readonly ILogger<LogoutModel> _logger;
public LogoutModel(SignInManager<IdentityUser> signInManager, ILogger<LogoutModel> logger)

{
_signInManager = signInManager;
_logger = logger;
}
public void OnGet()

{
}
public async Task<IActionResult> OnPost(string returnUrl = null)

{
await _signInManager.SignOutAsync();
_logger.LogInformation("User logged out.");
if (returnUrl != null)
{
}
else
{
return Page();
}
}
}
}
SignOutAsync limpa as declarações do usuário armazenadas em um cookie. Não redirecionar após chamar
SignOutAsync ou o usuário irá não ser desconectado.
POST é especificado na Pages/Shared/_LoginPartial.cshtml:

@inject SignInManager<IdentityUser> SignInManager

@inject UserManager<IdentityUser> UserManager
@if (SignInManager.IsSignedIn(User))
{
<form asp-area="Identity" asp-page="/Account/Logout"
asp-route-returnUrl="@Url.Page("/Index", new { area = "" })"
method="post"
id="logoutForm" class="navbar-right">
<ul class="nav navbar-nav navbar-right">
<li>
<a asp-area="Identity" asp-page="/Account/Manage/Index" title="Manage">
Hello @UserManager.GetUserName(User)!</a>
</li>
<li>
<button type="submit" class="btn btn-link navbar-btn navbar-link">Logout</button>
</li>
</ul>
</form>
}
else
{
<li><a asp-area="Identity" asp-page="/Account/Register">Register</a></li>
<li><a asp-area="Identity" asp-page="/Account/Login">Login</a></li>
</ul>
}
Clicar a fazer logoff vincular chamadas a LogOut ação.
//
// POST: /Account/LogOut
[HttpPost]
public async Task<IActionResult> LogOut()
{
await _signInManager.SignOutAsync();
_logger.LogInformation(4, "User logged out.");
}
O código anterior chama o _signInManager.SignOutAsync método. O SignOutAsync método limpa as

declarações do usuário armazenadas em um cookie.
Identidade de teste
Os modelos de projeto da web padrão permitem acesso anônimo para as home pages. Para testar a
identidade, adicione [Authorize] para a página sobre.
namespace WebApp1.Pages
{
[Authorize]
{
public void OnGet()

{
Message = "Your application description page.";
}
}
}
Se você estiver entrado, saia do serviço. Execute o aplicativo e selecione o sobre link. Você será
redirecionado à página de logon.
Explore a identidade
Para explorar a identidade em mais detalhes:
Criar fonte de interface do usuário de identidade completa
Examine a origem de cada página e percorrer o depurador.
Componentes de identidade
Todos os identidade NuGet pacotes dependentes são incluídos na metapacote Microsoft.
O pacote principal para a identidade está Microsoft.AspNetCore.Identity. Este pacote contém o conjunto
principal de interfaces para ASP.NET Core Identity e é incluído por
Microsoft.AspNetCore.Identity.EntityFrameworkCore .
Migrando para o ASP.NET Core Identity

Para obter mais informações e diretrizes sobre como migrar o armazenamento de identidade existente,
consulte migrar autenticação e identidade.
Definindo a força da senha

Consulte configuração para obter um exemplo que defina os requisitos mínimos de senha.
Próximas etapas
Configurar o Identity
Criar um aplicativo ASP.NET Core com os dados de usuário protegidos por autorização
Adicionar, baixar e excluir dados de usuário personalizada à identidade em um projeto ASP.NET Core
Habilitar a geração de código QR TOTP para aplicativos de autenticador no ASP.NET Core
Migrar autenticação e identidade para o ASP.NET Core
Confirmação de conta e de recuperação de senha no ASP.NET Core
Autenticação de dois fatores com SMS no ASP.NET Core
Identidade de Scaffold em projetos ASP.NET Core
Por Rick Anderson

O ASP.NET Core 2.1 e posterior fornece ASP.NET Core Identity como um biblioteca de classes Razor.
Aplicativos que incluem a identidade podem aplicar o scaffolder para seletivamente, adicione o código-fonte
contido na identidade Razor classe RCL (biblioteca). Talvez você queira gerar o código-fonte para que você
possa modificar o código e alterar o comportamento. Por exemplo, você pode instruir o scaffolder a gerar o
código usado no registro. Código gerado tem precedência sobre o mesmo código na RCL de Identidade. Para
obter controle total da interface do usuário e usar a RCL padrão, consulte a seção criar fonte de interface do
usuário de identidade completa.
Aplicativos que fazem não incluem autenticação pode aplicar o scaffolder para adicionar o pacote de identidade
da RCL. Você tem a opção de selecionar o código de Identidade a ser gerado.
Embora o scaffolder gera a maioria do código necessário, você precisará atualizar seu projeto para concluir o
processo. Este documento explica as etapas necessárias para concluir uma atualização de scaffolding de
identidade.
Quando o scaffolder de identidade é executado, uma Scaffoldingreadme arquivo é criado no diretório do
projeto. O Scaffoldingreadme arquivo contém instruções gerais sobre o que é necessário para concluir a
atualização de scaffolding de identidade. Este documento contém instruções mais completas que o
Scaffoldingreadme arquivo.
É recomendável usar um sistema de controle do código-fonte que mostra as diferenças de arquivo e permite
que você faça alterações fora. Inspecione as alterações depois de executar o scaffolder de identidade.
NOTE
Os serviços são necessários ao usar autenticação de dois fatores, recuperação de confirmação e a senha da contae outros
recursos de segurança com identidade. Serviços ou stubs de serviço não são gerados quando o scaffolding de identidade.
Serviços para habilitar esses recursos devem ser adicionados manualmente. Por exemplo, consulte exigem Email de
confirmação.
Identidade de Scaffold em um projeto vazio

Execute o scaffolder de identidade:
Visual Studio
CLI do .NET Core
Partir Gerenciador de soluções, clique com botão direito no projeto > Add > New Scaffolded Item.
No painel à esquerda do adicionar Scaffold caixa de diálogo, selecione identidade > adicionar.
No identidade de adição caixa de diálogo, selecione as opções desejadas.
Selecione a página de layout existente ou seu arquivo de layout será substituído pela marcação
incorreta. Por exemplo ~/Pages/Shared/_Layout.cshtml para as páginas Razor
~/Views/Shared/_Layout.cshtml para projetos MVC
Selecione o + botão para criar um novo classe de contexto de dados.
Selecione adicionar.
Adicione as seguintes chamadas destacadas para o Startup classe:

{
{
services.AddMvc();
}
{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
}
UseHsts é recomendável, mas não é necessário. Ver protocolo de segurança de transporte estrito HTTP para
Exige que o código de banco de dados de identidade gerado migrações do Entity Framework Core. Criar uma
migração e atualizar o banco de dados. Por exemplo, execute os seguintes comandos:
Visual Studio
CLI do .NET Core
No Visual Studio Package Manager Console:
Add-Migration CreateIdentitySchema
Update-Database
O parâmetro de nome "CreateIdentitySchema" para o Add-Migration comando é arbitrário.

"CreateIdentitySchema" Descreve a migração.
Identidade de Scaffold em um projeto do Razor sem autorização

existente
Visual Studio
CLI do .NET Core
Identidade é configurada no Areas/Identity/IdentityHostingStartup.cs. Para obter mais informações, consulte
IHostingStartup.
As migrações, UseAuthentication e layout
Visual Studio
CLI do .NET Core
Update-Database

Habilitar a autenticação
No Configure método da Startup classe, chame UseAuthentication depois UseStaticFiles :

{
{
}

{
services.AddMvc();
}

{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
}
Alterações de layout
Opcional: Adicionar o logon parcial ( _LoginPartial ) para o arquivo de layout:
<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] - RazorNoAuth8</title>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
<a asp-page="/Index" class="navbar-brand">RazorNoAuth8</a>
</div>
</ul>
<partial name="_LoginPartial" />
</div>
</div>
</nav>

@RenderBody()
<hr />
<footer>
<p>© 2018 - RazorNoAuth8</p>
</footer>
</div>
</environment>
</script>
</script>
</environment>

</body>
</html>
Identidade de Scaffold em um projeto do Razor com autorização

Visual Studio
CLI do .NET Core
incorreta. Quando um existente _layout. cshtml arquivo for selecionado, ele é não substituídos.
Por exemplo ~/Pages/Shared/_Layout.cshtml para as páginas Razor ~/Views/Shared/_Layout.cshtml para
projetos MVC
Para usar o contexto de dados existente, selecione pelo menos um arquivo para substituir. Você deve
selecionar pelo menos um arquivo para adicionar seu contexto de dados.
Selecione sua classe de contexto de dados.
Para criar um novo contexto de usuário e, possivelmente, crie uma classe de usuário personalizada para a
identidade:
Observação: Se você estiver criando um novo contexto de usuário, você não precisa selecionar um arquivo para
substituir.
Algumas opções de identidade são configuradas no Areas/Identity/IdentityHostingStartup.cs. Para obter mais
informações, consulte IHostingStartup.
Identidade de Scaffold em um projeto do MVC sem autorização

existente
Visual Studio
CLI do .NET Core
Opcional: Adicionar o logon parcial ( _LoginPartial ) para o Views/Shared/_Layout.cshtml arquivo:
<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] - MvcNoAuth3</title>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
<a asp-area="" asp-controller="Home" asp-action="Index" class="navbar-brand">MvcNoAuth3</a>
</div>
</ul>
<partial name="_LoginPartial" />
</div>
</div>
</nav>

@RenderBody()
<hr />
<footer>
<p>© 2018 - MvcNoAuth3</p>
</footer>
</div>
</environment>
</script>
</script>
</environment>

</body>
</html>
Mover o Pages/Shared/_LoginPartial.cshtml arquivo Views/Shared/_LoginPartial.cshtml

Identidade é configurada no Areas/Identity/IdentityHostingStartup.cs. Para obter mais informações, consulte
IHostingStartup.
Visual Studio
CLI do .NET Core
Update-Database

Chame UseAuthentication depois UseStaticFiles :

{

{
services.AddMvc();
}

{
{
}
else
{
app.UseHsts();
}
}
}
Identidade de Scaffold em um projeto do MVC com autorização

Visual Studio
CLI do .NET Core
incorreta. Quando um existente _layout. cshtml arquivo for selecionado, ele é não substituídos.
Por exemplo ~/Pages/Shared/_Layout.cshtml para as páginas Razor ~/Views/Shared/_Layout.cshtml para
projetos MVC
Para usar o contexto de dados existente, selecione pelo menos um arquivo para substituir. Você deve
selecionar pelo menos um arquivo para adicionar seu contexto de dados.
Selecione sua classe de contexto de dados.
Para criar um novo contexto de usuário e, possivelmente, crie uma classe de usuário personalizada para a
identidade:
Observação: Se você estiver criando um novo contexto de usuário, você não precisa selecionar um arquivo para
substituir.
Excluir o páginas/Shared pasta e os arquivos nessa pasta.
Criar fonte de interface do usuário de identidade completa
Para manter o controle total da interface do usuário de identidade, execute o scaffolder de identidade e
selecione substituir todos os arquivos.
O seguinte código realçado mostra as alterações para substituir o padrão de identidade da interface do usuário
com identidade em um aplicativo web do ASP.NET Core 2.1. Você talvez queira fazer isso para ter controle total
sobre a interface do usuário de identidade.

{
{
});
services.AddIdentity<IdentityUser, IdentityRole>()
// services.AddDefaultIdentity<IdentityUser>()
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1)
{
options.AllowAreas = true;
options.Conventions.AuthorizeAreaFolder("Identity", "/Account/Manage");
options.Conventions.AuthorizeAreaPage("Identity", "/Account/Logout");
});
{
options.LoginPath = $"/Identity/Account/Login";
options.LogoutPath = $"/Identity/Account/Logout";
options.AccessDeniedPath = $"/Identity/Account/AccessDenied";
});
// using Microsoft.AspNetCore.Identity.UI.Services;
services.AddSingleton<IEmailSender, EmailSender>();
}
O padrão de identidade é substituído no código a seguir:
services.AddIdentity<IdentityUser, IdentityRole>()
// services.AddDefaultIdentity<IdentityUser>()
O seguinte código define a LoginPath, LogoutPath, e AccessDeniedPath:
{
options.LoginPath = $"/Identity/Account/Login";
options.LogoutPath = $"/Identity/Account/Logout";
options.AccessDeniedPath = $"/Identity/Account/AccessDenied";
});
Registrar um IEmailSender implementação, por exemplo:
public class EmailSender : IEmailSender

{
public Task SendEmailAsync(string email, string subject, string message)
{
}
}
Recursos adicionais
Alterações no código de autenticação para o ASP.NET Core 2.1 e posterior
Adicionar, baixar e excluir dados de usuário
personalizada à identidade em um projeto ASP.NET
Core
Por Rick Anderson

Este artigo mostra como:
Adicione dados de usuário personalizada para um aplicativo web ASP.NET Core.
Decore o modelo de dados de usuário personalizada com o PersonalData para que ele fica automaticamente
disponível para download e exclusão de atributo. Tornando os dados capazes de ser baixado e excluído ajuda a
cumprir GDPR requisitos.
O exemplo de projeto é criado a partir de um aplicativo web páginas Razor, mas as instruções são semelhantes
para um aplicativo web ASP.NET Core MVC.
Pré-requisitos

Visual Studio
CLI do .NET Core
No menu Arquivo do Visual Studio, selecione Novo > Projeto. Nomeie o projeto WebApp1 se você deseja
corresponder ao namespace da baixar exemplo código.
Selecione aplicativo Web ASP.NET Core > Okey
Selecione ASP.NET Core 2.1 na lista suspensa
Selecione aplicativo Web > Okey
Compile e execute o projeto.
Execute o scaffolder de identidade

Visual Studio
CLI do .NET Core
No identidade de adição caixa de diálogo, as seguintes opções:
Selecione o arquivo de layout existente ~/Pages/Shared/_Layout.cshtml
Selecione os arquivos a seguir para substituir:
Conta/registro
Conta/gerenciar/índice
Selecione o + botão para criar um novo classe de contexto de dados. Aceite o tipo
(WebApp1.Models.WebApp1Context se o projeto é denominado WebApp1).
Selecione o + botão para criar um novo classe User. Aceite o tipo (WebApp1User se o projeto é
denominado WebApp1) > adicionar.
Siga as instruções da migrações, UseAuthentication e layout para executar as seguintes etapas:
Criar uma migração e atualizar o banco de dados.
Adicione UseAuthentication a Startup.Configure .
Adicionar <partial name="_LoginPartial" /> ao arquivo de layout.
Teste o aplicativo:
Registrar um usuário
Selecione o novo nome de usuário (ao lado de Logout link). Talvez você precise expandir a janela ou
selecione o ícone da barra de navegação para mostrar o nome de usuário e outros links.
Selecione o dados pessoais guia.
Selecione o Baixe botão e examinado o PersonalData.json arquivo.
Teste o excluir botão, que exclui o fez logon de usuário.
Adicionar dados de usuário personalizada para o banco de dados de

identidade
Atualização de IdentityUser derivado da classe com propriedades personalizadas. Se você nomeou o projeto
WebApp1, o arquivo é nomeado Areas/Identity/Data/WebApp1User.cs. Atualize o arquivo com o código a seguir:
using System;
namespace WebApp1.Areas.Identity.Data
{
public class WebApp1User : IdentityUser
{
[PersonalData]
[PersonalData]
public DateTime DOB { get; set; }
}
}
As propriedades decoradas com o PersonalData atributo são:

Excluído, quando o Areas/Identity/Pages/Account/Manage/DeletePersonalData.cshtml página do Razor
chama UserManager.Delete .
Incluído nos dados baixados pela Areas/Identity/Pages/Account/Manage/DownloadPersonalData.cshtml
página do Razor.
Atualizar a página Account/Manage/Index.cshtml
Atualizar o InputModel na Areas/Identity/Pages/Account/Manage/Index.cshtml.cs com o seguinte código
realçado:
public partial class IndexModel : PageModel

{
private readonly UserManager<WebApp1User> _userManager;
private readonly SignInManager<WebApp1User> _signInManager;
private readonly IEmailSender _emailSender;
public IndexModel(
UserManager<WebApp1User> userManager,
SignInManager<WebApp1User> signInManager,
IEmailSender emailSender)
{
_userManager = userManager;
_emailSender = emailSender;
}
public string Username { get; set; }
public bool IsEmailConfirmed { get; set; }
[TempData]
public string StatusMessage { get; set; }
[BindProperty]
public InputModel Input { get; set; }
public class InputModel

{
[Required]
[DataType(DataType.Text)]
[Display(Name = "Full name")]
[Required]
[Display(Name = "Birth Date")]
[Required]
[EmailAddress]
[Phone]
[Display(Name = "Phone number")]
public string PhoneNumber { get; set; }
}
public async Task<IActionResult> OnGetAsync()

{
var user = await _userManager.GetUserAsync(User);
if (user == null)
{
return NotFound($"Unable to load user with ID '{_userManager.GetUserId(User)}'.");
}
var userName = await _userManager.GetUserNameAsync(user);

var email = await _userManager.GetEmailAsync(user);
var phoneNumber = await _userManager.GetPhoneNumberAsync(user);
Username = userName;
Input = new InputModel

{
Name = user.Name,
DOB = user.DOB,
Email = email,
PhoneNumber = phoneNumber
};
IsEmailConfirmed = await _userManager.IsEmailConfirmedAsync(user);
return Page();
}

{
{
return Page();
}

if (user == null)
{
}
if (Input.Name != user.Name)
{
user.Name = Input.Name;
}
if (Input.DOB != user.DOB)
{
user.DOB = Input.DOB;
}

if (Input.Email != email)
{
var setEmailResult = await _userManager.SetEmailAsync(user, Input.Email);
if (!setEmailResult.Succeeded)
{
var userId = await _userManager.GetUserIdAsync(user);
throw new InvalidOperationException($"Unexpected error occurred setting email for user with ID
'{userId}'.");
}
}
var phoneNumber = await _userManager.GetPhoneNumberAsync(user);

if (Input.PhoneNumber != phoneNumber)
{
var setPhoneResult = await _userManager.SetPhoneNumberAsync(user, Input.PhoneNumber);
if (!setPhoneResult.Succeeded)
{
throw new InvalidOperationException($"Unexpected error occurred setting phone number for user
with ID '{userId}'.");
}
}
await _userManager.UpdateAsync(user);
await _signInManager.RefreshSignInAsync(user);
StatusMessage = "Your profile has been updated";
}
public async Task<IActionResult> OnPostSendVerificationEmailAsync()

{
{
return Page();
}

if (user == null)
{
}

pageHandler: null,
values: new { userId = userId, code = code },
await _emailSender.SendEmailAsync(
email,
"Confirm your email",
$"Please confirm your account by <a href='{HtmlEncoder.Default.Encode(callbackUrl)}'>clicking
here</a>.");
StatusMessage = "Verification email sent. Please check your email.";

}
}
Atualizar o Areas/Identity/Pages/Account/Manage/Index.cshtml com a seguinte marcação realçada:

@page
@model IndexModel
@{
ViewData["Title"] = "Profile";
}
@Html.Partial("_StatusMessage", Model.StatusMessage)
<div class="row">
<form id="profile-form" method="post">
<div asp-validation-summary="All" class="text-danger"></div>
<label asp-for="Username"></label>
<input asp-for="Username" class="form-control" disabled />
</div>
<label asp-for="Input.Email"></label>
@if (Model.IsEmailConfirmed)
{
<div class="input-group">
<input asp-for="Input.Email" class="form-control" />
<span class="input-group-addon" aria-hidden="true"><span class="glyphicon glyphicon-ok
text-success"></span></span>
</div>
}
else
{
<button id="email-verification" type="submit" asp-page-handler="SendVerificationEmail"
class="btn btn-link">Send verification email</button>
}
<span asp-validation-for="Input.Email" class="text-danger"></span>
</div>
<label asp-for="Input.Name"></label>
<input asp-for="Input.Name" class="form-control" />
</div>
<label asp-for="Input.DOB"></label>
<input asp-for="Input.DOB" class="form-control" />
</div>
<label asp-for="Input.PhoneNumber"></label>
<input asp-for="Input.PhoneNumber" class="form-control" />
<span asp-validation-for="Input.PhoneNumber" class="text-danger"></span>
</div>
<button type="submit" class="btn btn-default">Save</button>
</form>
</div>
</div>
@section Scripts {
}
Atualizar a página Register

Atualizar o InputModel na Areas/Identity/Pages/Account/Register.cshtml.cs com o seguinte código realçado:
[BindProperty]
public InputModel Input { get; set; }
public string ReturnUrl { get; set; }
public class InputModel

{
{
[Required]
[DataType(DataType.Text)]
[Display(Name = "Full name")]
[Required]
[Display(Name = "Birth Date")]
[Required]
[EmailAddress]
[Display(Name = "Email")]
[Required]
[StringLength(100, ErrorMessage = "The {0} must be at least {2} and at max {1} characters long.",
MinimumLength = 6)]
[Display(Name = "Password")]
[Display(Name = "Confirm password")]
[Compare("Password", ErrorMessage = "The password and confirmation password do not match.")]
public string ConfirmPassword { get; set; }
}

{
{
var user = new WebApp1User {
UserName = Input.Email,
Email = Input.Email,
Name = Input.Name,
DOB = Input.DOB
};
{

pageHandler: null,

here</a>.");

}
{
}
}

return Page();
}
Atualizar o Areas/Identity/Pages/Account/Register.cshtml com a seguinte marcação realçada:
@page
@model RegisterModel
@{
ViewData["Title"] = "Register";
}
<div class="row">
<form asp-route-returnUrl="@Model.ReturnUrl" method="post">
<h4>Create a new account.</h4>
<hr />
<div asp-validation-summary="All" class="text-danger"></div>
<label asp-for="Input.Name"></label>
<input asp-for="Input.Name" class="form-control" />
<span asp-validation-for="Input.Name" class="text-danger"></span>
</div>
<label asp-for="Input.DOB"></label>
<input asp-for="Input.DOB" class="form-control" />
<span asp-validation-for="Input.DOB" class="text-danger"></span>
</div>
<label asp-for="Input.Email"></label>
<span asp-validation-for="Input.Email" class="text-danger"></span>
</div>
<label asp-for="Input.Password"></label>
<input asp-for="Input.Password" class="form-control" />
<span asp-validation-for="Input.Password" class="text-danger"></span>
</div>
<label asp-for="Input.ConfirmPassword"></label>
<input asp-for="Input.ConfirmPassword" class="form-control" />
<span asp-validation-for="Input.ConfirmPassword" class="text-danger"></span>
</div>
<button type="submit" class="btn btn-default">Register</button>
</form>
</div>
</div>
@section Scripts {
}
Compile o projeto.
Adicionar uma migração para os dados de usuário personalizada
Visual Studio
CLI do .NET Core
Add-Migration CustomUserData
Update-Database
Teste de criar, exibir, baixar, excluir dados de usuário personalizada
Teste o aplicativo:
Registre um novo usuário.
Exibir os dados de usuário personalizada no /Identity/Account/Manage página.
Baixar e exibir os dados pessoais de usuários da /Identity/Account/Manage/PersonalData página.
Personalização de modelo de identidade no ASP.NET
Core
Por Arthur Vickers

Identidade do ASP.NET Core fornece uma estrutura para gerenciar e armazenar as contas de usuário em
aplicativos ASP.NET Core. Identidade é adicionada ao seu projeto quando contas de usuário individuais é
selecionado como o mecanismo de autenticação. Por padrão, a identidade faz usar de um Entity Framework (EF )
modelo de dados central. Este artigo descreve como personalizar o modelo de identidade.
Identidade e migrações do EF Core

Antes de examinar o modelo, ele é útil para entender como a identidade funciona com migrações do EF Core para
criar e atualizar um banco de dados. No nível superior, o processo é:
1. Definir ou atualizar uma modelo de dados no código.
2. Adicione uma migração para traduzir esse modelo para as alterações que podem ser aplicadas ao banco de
dados.
3. Verifique que a migração representa corretamente suas intenções.
4. Aplique a migração para atualizar o banco de dados para ser sincronizado com o modelo.
5. Repita as etapas 1 a 4 para refinar o modelo ainda mais e manter o banco de dados em sincronia.
Use uma das abordagens a seguir para adicionar e aplicar as migrações:
O Package Manager Console janela (PMC ) se usando o Visual Studio. Para obter mais informações, consulte
ferramentas do EF Core PMC.
A CLI do .NET Core se usando a linha de comando. Para obter mais informações, consulte ferramentas de linha
de comando do EF Core .NET.
Clicar a aplicar migrações botão na página de erro quando o aplicativo é executado.
O ASP.NET Core tem um manipulador de página de erro de tempo de desenvolvimento. O manipulador pode
aplicar migrações quando o aplicativo é executado. Para aplicativos de produção, geralmente é mais apropriado
para gerar scripts SQL das migrações e implantar as alterações do banco de dados como parte de uma
implantação de aplicativo e o banco de dados controlada.
Quando um novo aplicativo usando a identidade é criado, as etapas 1 e 2 acima já tem sido concluídas. Ou seja, o
modelo de dados iniciais já existir e a migração inicial foi adicionada ao projeto. A migração inicial ainda precisa ser
aplicada ao banco de dados. A migração inicial pode ser aplicada por meio de uma das seguintes abordagens:
Execute Update-Database no PMC.
Executar dotnet ef database update em um shell de comando.
Clique o aplicar migrações botão na página de erro quando o aplicativo é executado.
Repita as etapas anteriores, como as alterações são feitas no modelo.
O modelo de identidade
Tipos de entidade
O modelo de identidade consiste dos seguintes tipos de entidade.
TIPO DE ENTIDADE DESCRIÇÃO
User Representa o usuário.
Role Representa uma função.
UserClaim Representa uma declaração que um usuário possui.
UserToken Representa um token de autenticação para um usuário.
UserLogin Associa um usuário com um logon.
RoleClaim Representa uma declaração que é concedida a todos os

usuários dentro de uma função.
UserRole Uma entidade de junção que associa os usuários e funções.
Relacionamentos de tipo de entidade

O tipos de entidade estão relacionados uns aos outros das seguintes maneiras:
Cada User pode ter muitas UserClaims .
Cada User pode ter muitas UserLogins .
Cada User pode ter muitas UserTokens .
Cada Role pode ter muitas associado RoleClaims .
Cada User pode ter muitas associados Roles e cada Role pode ser associado a muitos Users . Essa é uma
relação de muitos-para-muitos que requer uma tabela de junção no banco de dados. A tabela de junção é
representada pelo UserRole entidade.
Configuração de modelo padrão
Identidade define muitos classes de contexto que herdam de DbContext para configurar e usar o modelo. Essa
configuração é feita usando o EF Core Fluent API do Code First no OnModelCreating método da classe de
contexto. A configuração padrão é:
builder.Entity<TUser>(b =>
{
// Primary key
b.HasKey(u => u.Id);
// Indexes for "normalized" username and email, to allow efficient lookups

b.HasIndex(u => u.NormalizedUserName).HasName("UserNameIndex").IsUnique();
b.HasIndex(u => u.NormalizedEmail).HasName("EmailIndex");
// Maps to the AspNetUsers table

b.ToTable("AspNetUsers");
// A concurrency token for use with the optimistic concurrency checking

b.Property(u => u.ConcurrencyStamp).IsConcurrencyToken();
// Limit the size of columns to use efficient database types

b.Property(u => u.UserName).HasMaxLength(256);
b.Property(u => u.NormalizedUserName).HasMaxLength(256);
b.Property(u => u.Email).HasMaxLength(256);
b.Property(u => u.NormalizedEmail).HasMaxLength(256);
// The relationships between User and other entity types

// Note that these relationships are configured with no navigation properties
// Each User can have many UserClaims

b.HasMany<TUserClaim>().WithOne().HasForeignKey(uc => uc.UserId).IsRequired();
// Each User can have many UserLogins

b.HasMany<TUserLogin>().WithOne().HasForeignKey(ul => ul.UserId).IsRequired();
// Each User can have many UserTokens

b.HasMany<TUserToken>().WithOne().HasForeignKey(ut => ut.UserId).IsRequired();
// Each User can have many entries in the UserRole join table
b.HasMany<TUserRole>().WithOne().HasForeignKey(ur => ur.UserId).IsRequired();
});
builder.Entity<TUserClaim>(b =>
{
// Primary key
b.HasKey(uc => uc.Id);
// Maps to the AspNetUserClaims table

b.ToTable("AspNetUserClaims");
});
builder.Entity<TUserLogin>(b =>
{
// Composite primary key consisting of the LoginProvider and the key to use
// with that provider
b.HasKey(l => new { l.LoginProvider, l.ProviderKey });
// Limit the size of the composite key columns due to common DB restrictions
b.Property(l => l.LoginProvider).HasMaxLength(128);
b.Property(l => l.ProviderKey).HasMaxLength(128);
// Maps to the AspNetUserLogins table

b.ToTable("AspNetUserLogins");
});
builder.Entity<TUserToken>(b =>
{
// Composite primary key consisting of the UserId, LoginProvider and Name
b.HasKey(t => new { t.UserId, t.LoginProvider, t.Name });
// Limit the size of the composite key columns due to common DB restrictions
b.Property(t => t.LoginProvider).HasMaxLength(maxKeyLength);
b.Property(t => t.Name).HasMaxLength(maxKeyLength);
// Maps to the AspNetUserTokens table

b.ToTable("AspNetUserTokens");
});
builder.Entity<TRole>(b =>
{
// Primary key
b.HasKey(r => r.Id);
// Index for "normalized" role name to allow efficient lookups

b.HasIndex(r => r.NormalizedName).HasName("RoleNameIndex").IsUnique();
// Maps to the AspNetRoles table

b.ToTable("AspNetRoles");
// A concurrency token for use with the optimistic concurrency checking

b.Property(r => r.ConcurrencyStamp).IsConcurrencyToken();
// Limit the size of columns to use efficient database types

b.Property(u => u.Name).HasMaxLength(256);
b.Property(u => u.NormalizedName).HasMaxLength(256);
// The relationships between Role and other entity types

// Note that these relationships are configured with no navigation properties
// Each Role can have many entries in the UserRole join table
b.HasMany<TUserRole>().WithOne().HasForeignKey(ur => ur.RoleId).IsRequired();
// Each Role can have many associated RoleClaims

b.HasMany<TRoleClaim>().WithOne().HasForeignKey(rc => rc.RoleId).IsRequired();
});
builder.Entity<TRoleClaim>(b =>
{
// Primary key
b.HasKey(rc => rc.Id);
// Maps to the AspNetRoleClaims table

b.ToTable("AspNetRoleClaims");
});
builder.Entity<TUserRole>(b =>
{
// Primary key
b.HasKey(r => new { r.UserId, r.RoleId });
// Maps to the AspNetUserRoles table

b.ToTable("AspNetUserRoles");
});
Tipos genéricos de modelo

Identidade define o padrão Common Language Runtime tipos (CLR ) para cada um dos tipos de entidade listados
acima. Esses tipos são prefixados com identidade:
IdentityUser
IdentityRole
IdentityUserClaim
IdentityUserToken
IdentityUserLogin
IdentityRoleClaim
IdentityUserRole
Em vez de usar esses tipos diretamente, os tipos podem ser usados como classes base para os tipos do aplicativo.
O DbContext classes definidas pela identidade são genéricas, de modo que diferentes tipos CLR podem ser usados
para uma ou mais dos tipos de entidade no modelo. Esses tipos genéricos também permitem que o User tipo de
dados (PK) chave primária a ser alterado.
Ao usar a identidade com suporte para funções, um IdentityDbContext classe deve ser usada. Por exemplo:
// Uses all the built-in Identity types
// Uses `string` as the key type
public class IdentityDbContext
: IdentityDbContext<IdentityUser, IdentityRole, string>
{
}
// Uses the built-in Identity types except with a custom User type
public class IdentityDbContext<TUser>
: IdentityDbContext<TUser, IdentityRole, string>
where TUser : IdentityUser
{
}
// Uses the built-in Identity types except with custom User and Role types
// The key type is defined by TKey
public class IdentityDbContext<TUser, TRole, TKey> : IdentityDbContext<
TUser, TRole, TKey, IdentityUserClaim<TKey>, IdentityUserRole<TKey>,
IdentityUserLogin<TKey>, IdentityRoleClaim<TKey>, IdentityUserToken<TKey>>
where TUser : IdentityUser<TKey>
where TRole : IdentityRole<TKey>
where TKey : IEquatable<TKey>
{
}
// No built-in Identity types are used; all are specified by generic arguments
public abstract class IdentityDbContext<
TUser, TRole, TKey, TUserClaim, TUserRole, TUserLogin, TRoleClaim, TUserToken>
: IdentityUserContext<TUser, TKey, TUserClaim, TUserLogin, TUserToken>
where TRole : IdentityRole<TKey>
where TUserClaim : IdentityUserClaim<TKey>
where TUserRole : IdentityUserRole<TKey>
where TUserLogin : IdentityUserLogin<TKey>
where TRoleClaim : IdentityRoleClaim<TKey>
where TUserToken : IdentityUserToken<TKey>
Também é possível usar a identidade sem funções (apenas declarações), caso em que um
IdentityUserContext<TUser> classe deve ser usada:
// Uses the built-in non-role Identity types except with a custom User type
public class IdentityUserContext<TUser>
: IdentityUserContext<TUser, string>
where TUser : IdentityUser
{
}
// Uses the built-in non-role Identity types except with a custom User type
public class IdentityUserContext<TUser, TKey> : IdentityUserContext<
TUser, TKey, IdentityUserClaim<TKey>, IdentityUserLogin<TKey>,
IdentityUserToken<TKey>>
{
}
// No built-in Identity types are used; all are specified by generic arguments, with no roles
public abstract class IdentityUserContext<
TUser, TKey, TUserClaim, TUserLogin, TUserToken> : DbContext
where TUserClaim : IdentityUserClaim<TKey>
where TUserLogin : IdentityUserLogin<TKey>
where TUserToken : IdentityUserToken<TKey>
{
}
Personalizar o modelo
O ponto de partida para a personalização de modelo é derivado do tipo de contexto apropriado. Consulte a
modelar tipos genéricos seção. Esse tipo de contexto geralmente é chamado ApplicationDbContext e é criada pelos
modelos do ASP.NET Core.
O contexto é usado para configurar o modelo de duas maneiras:
Fornecimento de entidade e tipos de chaves para os parâmetros de tipo genérico.
Substituindo OnModelCreating para modificar o mapeamento desses tipos.
Ao substituir OnModelCreating , base.OnModelCreating deve ser chamado pela primeira vez; a configuração de
substituição deve ser chamada em seguida. O EF Core geralmente tem uma política last-one-wins para a
configuração. Por exemplo, se o ToTable método para um tipo de entidade é chamado pela primeira vez com o
nome de uma tabela e, em seguida, novamente mais tarde com um nome de tabela diferente, o nome da tabela na
segunda chamada é usado.
Dados de usuário personalizada
Dados de usuário personalizados há suporte para herdar de IdentityUser . É comum para esse tipo de nome
ApplicationUser :

{
public string CustomTag { get; set; }
}
Use o ApplicationUser tipo como um argumento genérico para o contexto:

public class ApplicationDbContext : IdentityDbContext<ApplicationUser>
{
public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
: base(options)
{
}
}
Não é necessário substituir OnModelCreating no ApplicationDbContext classe. O EF Core mapeia o CustomTag

propriedade por convenção. No entanto, o banco de dados precisa ser atualizado para criar um novo CustomTag
coluna. Para criar a coluna, adicione uma migração e, em seguida, atualize o banco de dados, conforme descrito em
identidade e migrações do EF Core.
Atualização Startup.ConfigureServices para usar o novo ApplicationUser classe:
services.AddDefaultIdentity<ApplicationUser>()
.AddDefaultUI();
No ASP.NET Core 2.1 ou posterior, a identidade é fornecida como uma biblioteca de classes Razor. Para obter mais
informações, consulte Identidade de Scaffold em projetos ASP.NET Core. Consequentemente, o código anterior
requer uma chamada para AddDefaultUI. Se o scaffolder de identidade foi usado para adicionar arquivos de
identidade para o projeto, remova a chamada para AddDefaultUI . Para obter mais informações, consulte:
Identidade Scaffold
Adicionar, baixar e excluir dados de usuário personalizada à identidade
.AddEntityFrameworkStores<ApplicationDbContext, Guid>()
Alterar o tipo de chave primária

Uma alteração para o tipo de dados da coluna PK depois que o banco de dados foi criado é um problema em
muitos sistemas de banco de dados. Alterando a PK normalmente envolve descartar e recriar a tabela. Portanto,
tipos de chave devem ser especificados na migração inicial quando o banco de dados é criado.
Siga estas etapas para alterar o tipo de PK:
1. Se o banco de dados foi criado antes da alteração de PK, execute Drop-Database (PMC ) ou
dotnet ef database drop ( CLI do .NET Core) para excluí-lo.
2. Depois de confirmar a exclusão do banco de dados, remova a migração inicial com Remove-Migration (PMC )
ou dotnet ef migrations remove (CLI do .NET Core).
3. Atualizar o ApplicationDbContext classe para derivar de IdentityDbContext<TUser,TRole,TKey>. Especifique
o novo tipo de chave para TKey . Por exemplo, para usar um Guid tipo de chave:
public class ApplicationDbContext
: IdentityDbContext<IdentityUser<Guid>, IdentityRole<Guid>, Guid>
{
: base(options)
{
}
}
No código anterior, as classes genéricas IdentityUser<TKey> e IdentityRole<TKey> deve ser especificado

para usar o novo tipo de chave.
No código anterior, as classes genéricas IdentityUser<TKey> e IdentityRole<TKey> deve ser especificado
para usar o novo tipo de chave.
Startup.ConfigureServices deve ser atualizado para usar o usuário genérico:
services.AddDefaultIdentity<IdentityUser<Guid>>()
services.AddIdentity<IdentityUser<Guid>, IdentityRole>()
services.AddIdentity<IdentityUser<Guid>, IdentityRole>()
4. Se um personalizado ApplicationUser classe está sendo usado, atualize a classe para herdar de
IdentityUser . Por exemplo:
using System;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
public class ApplicationUser : IdentityUser<Guid>

{
}
using System;
public class ApplicationUser : IdentityUser<Guid>

{
}
Atualização ApplicationDbContext para fazer referência a personalizada ApplicationUser classe:

: IdentityDbContext<ApplicationUser, IdentityRole<Guid>, Guid>
{
: base(options)
{
}
}
Registrar a classe de contexto do banco de dados personalizados ao adicionar o serviço de identidade no

.AddDefaultUI()
Tipo de dados da chave primária é inferido, analisando o DbContext objeto.

No ASP.NET Core 2.1 ou posterior, a identidade é fornecida como uma biblioteca de classes Razor. Para
obter mais informações, consulte Identidade de Scaffold em projetos ASP.NET Core. Consequentemente, o
código anterior requer uma chamada para AddDefaultUI. Se o scaffolder de identidade foi usado para
adicionar arquivos de identidade para o projeto, remova a chamada para AddDefaultUI .
O AddEntityFrameworkStores método aceita um TKey tipo que indica o tipo de dados da chave primária.
5. Se um personalizado ApplicationRole classe está sendo usado, atualize a classe para herdar de
IdentityRole<TKey> . Por exemplo:
using System;
public class ApplicationRole : IdentityRole<Guid>

{
}
Atualização ApplicationDbContext para fazer referência a personalizada ApplicationRole classe. Por

exemplo, a classe a seguir faz referência a um personalizado ApplicationUser e um personalizado
ApplicationRole :
using System;
public class ApplicationDbContext :

IdentityDbContext<ApplicationUser, ApplicationRole, Guid>
{
: base(options)
{
}
}


{
{
});
services.AddIdentity<ApplicationUser, ApplicationRole>()
.AddDefaultUI()
services.AddMvc()
}

No ASP.NET Core 2.1 ou posterior, a identidade é fornecida como uma biblioteca de classes Razor. Para
obter mais informações, consulte Identidade de Scaffold em projetos ASP.NET Core. Consequentemente, o
código anterior requer uma chamada para AddDefaultUI. Se o scaffolder de identidade foi usado para
adicionar arquivos de identidade para o projeto, remova a chamada para AddDefaultUI .
using System;

{
: base(options)
{
}
}

{
services.AddMvc()
{
options.Conventions.AuthorizeFolder("/Account/Manage");
options.Conventions.AuthorizePage("/Account/Logout");
});
}
using System;

{
: base(options)
{
}
}


{
services.AddMvc();
}
O AddEntityFrameworkStores método aceita um TKey tipo que indica o tipo de dados da chave primária.
Adicionar propriedades de navegação
Alterar a configuração de modelo para relações pode ser mais difícil do que fazendo outras alterações. Deve-se ter
cuidado para substituir as relações existentes em vez de criar novas relações adicionais. Em particular, a relação
alterada deve especificar o mesmo (FK) propriedade de chave estrangeira como a relação existente. Por exemplo, a
relação entre Users e UserClaims é, por padrão, especificada da seguinte maneira:
builder.Entity<TUser>(b =>
{
b.HasMany<TUserClaim>()
.WithOne()
.HasForeignKey(uc => uc.UserId)
.IsRequired();
});
A FK para essa relação é especificada como o UserClaim.UserId propriedade. HasMany e WithOne são chamados
sem argumentos para criar a relação sem propriedades de navegação.
Adicionar uma propriedade de navegação ApplicationUser que permite que associado UserClaims seja
referenciado do usuário:

{
public virtual ICollection<IdentityUserClaim<string>> Claims { get; set; }
}
O TKey para IdentityUserClaim<TKey> é o tipo especificado para o PK de usuários. Nesse caso, TKey é string
porque os padrões estão sendo usados. Ele tem não o tipo de PK para o UserClaim tipo de entidade.
Agora que existe a propriedade de navegação, ele deve ser configurado no OnModelCreating :

{
: base(options)
{
}

{
base.OnModelCreating(modelBuilder);
modelBuilder.Entity<ApplicationUser>(b =>
{
b.HasMany(e => e.Claims)
.WithOne()
.IsRequired();
});
}
}
Observe que a relação é configurada exatamente como ele era antes, apenas com uma propriedade de navegação
especificada na chamada para HasMany .
As propriedades de navegação só existem no modelo do EF, não o banco de dados. Como a FK para a relação não
foi alterado, esse tipo de alteração de modelo não exige o banco de dados a ser atualizada. Isso pode ser verificado
com a adição de uma migração após fazer a alteração. O Up e Down métodos estão vazios.
Adicionar todas as propriedades de navegação do usuário
O exemplo a seguir usando a seção acima como orientação, configura as propriedades de navegação unidirecional
para todas as relações em usuário:
{
public virtual ICollection<IdentityUserLogin<string>> Logins { get; set; }
public virtual ICollection<IdentityUserToken<string>> Tokens { get; set; }
public virtual ICollection<IdentityUserRole<string>> UserRoles { get; set; }
}

{
: base(options)
{
}

{
{
.WithOne()
.IsRequired();

b.HasMany(e => e.Logins)
.WithOne()
.HasForeignKey(ul => ul.UserId)
.IsRequired();

b.HasMany(e => e.Tokens)
.WithOne()
.HasForeignKey(ut => ut.UserId)
.IsRequired();
b.HasMany(e => e.UserRoles)
.WithOne()
.HasForeignKey(ur => ur.UserId)
.IsRequired();
});
}
}
Adicionar propriedades de navegação do usuário e a função

Usando a seção acima como orientação, o exemplo a seguir configura as propriedades de navegação para todas as
relações no usuário e a função:
{
public virtual ICollection<IdentityUserLogin<string>> Logins { get; set; }
public virtual ICollection<IdentityUserToken<string>> Tokens { get; set; }
public virtual ICollection<ApplicationUserRole> UserRoles { get; set; }
}
public class ApplicationRole : IdentityRole

{
}
public class ApplicationUserRole : IdentityUserRole<string>

{
public virtual ApplicationUser User { get; set; }
public virtual ApplicationRole Role { get; set; }
}
: IdentityDbContext<
ApplicationUser, ApplicationRole, string,
IdentityUserClaim<string>, ApplicationUserRole, IdentityUserLogin<string>,
IdentityRoleClaim<string>, IdentityUserToken<string>>
{
: base(options)
{
}

{
{
.WithOne()
.IsRequired();

.WithOne()
.IsRequired();

.WithOne()
.IsRequired();
.WithOne(e => e.User)
.IsRequired();
});
modelBuilder.Entity<ApplicationRole>(b =>
{
.WithOne(e => e.Role)
.HasForeignKey(ur => ur.RoleId)
.IsRequired();
});
}
}
Notas:
Este exemplo também inclui o UserRole entidade, que é necessário para navegar pela relação muitos-para-
muitos dos usuários às funções de ingresso.
Lembre-se de alterar os tipos das propriedades de navegação de refletir isso ApplicationXxx tipos agora estão
sendo usados em vez de IdentityXxx tipos.
Lembre-se de usar o ApplicationXxx no genérico ApplicationContext definição.
Adicionar todas as propriedades de navegação
Usando a seção acima como orientação, o exemplo a seguir configura as propriedades de navegação para todas as
relações em todos os tipos de entidade:

{
public virtual ICollection<ApplicationUserClaim> Claims { get; set; }
public virtual ICollection<ApplicationUserLogin> Logins { get; set; }
public virtual ICollection<ApplicationUserToken> Tokens { get; set; }
}
public class ApplicationRole : IdentityRole

{
public virtual ICollection<ApplicationRoleClaim> RoleClaims { get; set; }
}
public class ApplicationUserRole : IdentityUserRole<string>

{
}
public class ApplicationUserClaim : IdentityUserClaim<string>

{
}
public class ApplicationUserLogin : IdentityUserLogin<string>

{
}
public class ApplicationRoleClaim : IdentityRoleClaim<string>

{
}
public class ApplicationUserToken : IdentityUserToken<string>

{
}
: IdentityDbContext<
ApplicationUser, ApplicationRole, string,
ApplicationUserClaim, ApplicationUserRole, ApplicationUserLogin,
ApplicationRoleClaim, ApplicationUserToken>
{
: base(options)
{
}

{
{
.IsRequired();

.IsRequired();

.IsRequired();
.IsRequired();
});
modelBuilder.Entity<ApplicationRole>(b =>
{
.HasForeignKey(ur => ur.RoleId)
.IsRequired();
// Each Role can have many associated RoleClaims

b.HasMany(e => e.RoleClaims)
.HasForeignKey(rc => rc.RoleId)
.IsRequired();
});
}
}
Usar chaves compostas

As seções anteriores demonstrou como alterar o tipo da chave usada no modelo de identidade. Alterando o
modelo de chave de identidade para usar chaves compostas não é suportado nem recomendado. Usar uma chave
composta com identidade envolve a alteração como o código do Gerenciador de identidade interage com o
modelo. Essa personalização está além do escopo deste documento.
Alterar nomes de tabela/coluna e as facetas
Para alterar os nomes das tabelas e colunas, chame base.OnModelCreating . Em seguida, adicione a configuração
para substituir qualquer um dos padrões. Por exemplo, para alterar o nome de todas as tabelas de identidade:

{
modelBuilder.Entity<IdentityUser>(b =>
{
b.ToTable("MyUsers");
});
modelBuilder.Entity<IdentityUserClaim<string>>(b =>
{
b.ToTable("MyUserClaims");
});
modelBuilder.Entity<IdentityUserLogin<string>>(b =>
{
b.ToTable("MyUserLogins");
});
modelBuilder.Entity<IdentityUserToken<string>>(b =>
{
b.ToTable("MyUserTokens");
});
modelBuilder.Entity<IdentityRole>(b =>
{
b.ToTable("MyRoles");
});
modelBuilder.Entity<IdentityRoleClaim<string>>(b =>
{
b.ToTable("MyRoleClaims");
});
modelBuilder.Entity<IdentityUserRole<string>>(b =>
{
b.ToTable("MyUserRoles");
});
}
Esses exemplos usam os tipos de identidade padrão. Se usar um tipo de aplicativo, como ApplicationUser ,
configurar esse tipo em vez do tipo padrão.
O exemplo a seguir altera alguns nomes de coluna:
{
{
b.Property(e => e.Email).HasColumnName("EMail");
});
modelBuilder.Entity<IdentityUserClaim<string>>(b =>
{
b.Property(e => e.ClaimType).HasColumnName("CType");
b.Property(e => e.ClaimValue).HasColumnName("CValue");
});
}
Alguns tipos de colunas de banco de dados podem ser configurados com determinados facetas (por exemplo, o
máximo string comprimento permitido). O exemplo a seguir define os comprimentos máximos da coluna para
várias string propriedades no modelo:

{
{
b.Property(u => u.UserName).HasMaxLength(128);
b.Property(u => u.NormalizedUserName).HasMaxLength(128);
b.Property(u => u.Email).HasMaxLength(128);
b.Property(u => u.NormalizedEmail).HasMaxLength(128);
});
modelBuilder.Entity<IdentityUserToken<string>>(b =>
{
b.Property(t => t.LoginProvider).HasMaxLength(128);
b.Property(t => t.Name).HasMaxLength(128);
});
}
Mapear para um esquema diferente

Esquemas podem se comportar de maneira diferente em provedores de banco de dados. Para o SQL Server, o
padrão é criar todas as tabelas na dbo esquema. As tabelas podem ser criadas em um esquema diferente. Por
exemplo:

{
modelBuilder.HasDefaultSchema("notdbo");
}
Carregamento lento
Nesta seção, o suporte para proxies de carregamento lento no modelo de identidade é adicionado. Carregamento
lento é útil, pois ele permite que as propriedades de navegação a ser usada sem primeiro garantir que eles são
carregados.
Tipos de entidade podem ser feitos adequados para carregamento lento de diversas maneiras, conforme descrito
na documentação do EF Core. Para simplificar, use proxies de carregamento lento, que requer:
Instalação dos entityframeworkcore pacote.
Uma chamada para UseLazyLoadingProxies dentro de AddDbContext<TContext>.
Tipos de entidade pública com public virtual propriedades de navegação.
O exemplo a seguir demonstra a chamada UseLazyLoadingProxies em Startup.ConfigureServices :
services
.AddDbContext<ApplicationDbContext>(
b => b.UseSqlServer(connectionString)
.UseLazyLoadingProxies())
.AddDefaultIdentity<ApplicationUser>()
Consulte os exemplos anteriores para obter orientação sobre como adicionar propriedades de navegação para os
tipos de entidade.
Recursos adicionais
Identidade de Scaffold em projetos ASP.NET Core
Opções de autenticação de comunidade OSS para
ASP.NET Core
Esta página contém as opções de autenticação fornecido pela comunidade de código aberto para o ASP.NET Core.
Esta página é atualizada periodicamente como novos provedores de se tornar disponíveis.
Provedores de autenticação de sistemas operacionais

A lista a seguir está classificada alfabeticamente.
NOME DESCRIÇÃO
AspNet.Security.OpenIdConnect.Server (ASOS) ASOS é um nível baixo, o primeiro protocolo OpenID Connect

server framework para ASP.NET Core e OWIN/Katana.
Cierge Cierge é um servidor de OpenID Connect que manipula a

inscrição de usuário, logon, perfis, gerenciamento e logons
sociais.
Servidor Gluu Enterprise estiver pronto, abra o software de origem para a

identidade, gerenciamento de acesso (IAM) e logon único
(SSO). Para obter mais informações, consulte o documentação
do produto Gluu.
IdentityServer IdentityServer é uma estrutura de OpenID Connect e OAuth

2.0 para ASP.NET Core, certificada oficialmente a base de
OpenID e sob controle do Foundation .NET. Para obter mais
informações, consulte bem-vindo ao IdentityServer4
(documentação).
OpenIddict OpenIddict é um servidor de OpenID Connect de fácil de usar

para ASP.NET Core.
Para adicionar um provedor, editar esta página.

Configurar a identidade do ASP.NET Core
Identidade do ASP.NET Core usa valores padrão para configurações como a política de senha, bloqueio e
configuração de cookie. Essas configurações podem ser substituídas no Startup classe.
Opções de identidade
O IdentityOptions classe representa as opções que podem ser usadas para configurar o sistema de identidade.
IdentityOptions deve ser definido após chamando AddIdentity ou AddDefaultIdentity .
Identidade baseada em declarações

IdentityOptions.ClaimsIdentity Especifica o ClaimsIdentityOptions com as propriedades mostradas na tabela a
seguir.
RoleClaimType Obtém ou define o tipo de declaração ClaimTypes.Role

usado para uma declaração de função.
SecurityStampClaimType Obtém ou define o tipo de declaração AspNet.Identity.SecurityStamp

usado para a declaração de carimbo de
segurança.
UserIdClaimType Obtém ou define o tipo de declaração ClaimTypes.NameIdentifier

usado para a declaração do
identificador de usuário.
UserNameClaimType Obtém ou define o tipo de declaração ClaimTypes.Name

usado para a declaração de nome de
usuário.
Bloqueio
O bloqueio é definido na PasswordSignInAsync método:
{
{
var result = await _signInManager.PasswordSignInAsync(Input.Email,
Input.Password, Input.RememberMe,
lockoutOnFailure: false);
{
_logger.LogInformation("User logged in.");
}
{
return RedirectToPage("./LoginWith2fa", new { ReturnUrl = returnUrl,
Input.RememberMe });
}
{
_logger.LogWarning("User account locked out.");
}
else
{
return Page();
}
}

return Page();
}
O código anterior se baseia o Login modelo de identidade.

Opções de bloqueio são definidas na StartUp.ConfigureServices :
{
// Default Lockout settings.
});
O código anterior define o IdentityOptions LockoutOptions com valores padrão.

Uma autenticação bem-sucedida redefine a contagem de tentativas de acesso com falha e redefine o relógio.
IdentityOptions.Lockout Especifica o LockoutOptions com as propriedades mostradas na tabela.
AllowedForNewUsers Determina se um novo usuário poderá true

ser bloqueado.
DefaultLockoutTimeSpan A quantidade de tempo um usuário 5 minutos

está bloqueado quando ocorre um
bloqueio.
MaxFailedAccessAttempts O número de tentativas de acesso com 5

falha até que um usuário está
bloqueado, se o bloqueio está
habilitado.
Senha
Por padrão, a identidade requer que as senhas conter um caractere maiusculo, caractere minúsculo, um dígito e
um caractere não alfanumérico. As senhas devem ter pelo menos seis caracteres. PasswordOptions podem ser
definidas na Startup.ConfigureServices .
{
// Default Password settings.
});
services.AddIdentity<ApplicationUser, IdentityRole>(options =>

{
})
{
});
IdentityOptions.Password Especifica o PasswordOptions com as propriedades mostradas na tabela.
RequireDigit Requer um número entre 0 a 9 na true

senha.
RequiredLength O comprimento mínimo da senha. 6
RequireLowercase Requer um caractere minúsculo na true

senha.
RequireNonAlphanumeric Requer um caractere não alfanuméricos true

na senha.
RequiredUniqueChars Só se aplica ao ASP.NET Core 2.0 ou 1

posterior.
Requer o número de caracteres

distintas na senha.
RequireUppercase Requer um caractere maiusculo na true

senha.
RequireDigit Requer um número entre 0 a 9 na true

senha.
RequiredLength O comprimento mínimo da senha. 6
RequireLowercase Requer um caractere minúsculo na true

senha.
RequireNonAlphanumeric Requer um caractere não alfanuméricos true

na senha.
RequireUppercase Requer um caractere maiusculo na true

senha.
Entrar
O seguinte código define SignIn configurações (para valores padrão):
{
// Default SignIn settings.
options.SignIn.RequireConfirmedEmail = true;
options.SignIn.RequireConfirmedPhoneNumber = false;
});
services.AddIdentity<ApplicationUser, IdentityRole>(options =>

{
// Signin settings
options.SignIn.RequireConfirmedEmail = true;
options.SignIn.RequireConfirmedPhoneNumber = false;
})
IdentityOptions.SignIn Especifica o SignInOptions com as propriedades mostradas na tabela.
RequireConfirmedEmail Requer um email confirmado para false

entrar.
RequireConfirmedPhoneNumber Requer um número de telefone false

confirmado entrar.
Tokens
IdentityOptions.Tokens Especifica o TokenOptions com as propriedades mostradas na tabela.
AuthenticatorTokenProvider Obtém ou define o AuthenticatorTokenProvider usado

para validar entradas de dois fatores com um autenticador.
ChangeEmailTokenProvider Obtém ou define o ChangeEmailTokenProvider usado para

gerar tokens usados nos emails de confirmação de alteração
de email.
ChangePhoneNumberTokenProvider Obtém ou define o ChangePhoneNumberTokenProvider usada

para gerar tokens usados ao alterar os números de telefone.
EmailConfirmationTokenProvider Obtém ou define o provedor de token usado para gerar

tokens usados nos emails de confirmação de conta.
PasswordResetTokenProvider Obtém ou define o IUserTwoFactorTokenProvider usado para

gerar tokens usados nos emails de redefinição de senha.
ProviderMap Usado para construir um provedor de Token de usuário com a

chave usada como o nome do provedor.
User
{
// Default User settings.
options.User.AllowedUserNameCharacters =
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._@+";
});
IdentityOptions.User Especifica o UserOptions com as propriedades mostradas na tabela.
AllowedUserNameCharacters Caracteres permitidos no nome de abcdefghijklmnopqrstuvwxyz

usuário. ABCDEFGHIJKLMNOPQRSTUVWXYZ
0123456789
-._@+
RequireUniqueEmail Requer que cada usuário tenha um false

email exclusivo.
Configurações de cookie
Configurar o cookie do aplicativo em Startup.ConfigureServices . ConfigureApplicationCookie deve ser chamado
após chamando AddIdentity ou AddDefaultIdentity .
{
options.AccessDeniedPath = "/Identity/Account/AccessDenied";
options.Cookie.Name = "YourAppCookieName";
options.LoginPath = "/Identity/Account/Login";
// ReturnUrlParameter requires
//using Microsoft.AspNetCore.Authentication.Cookies;
options.ReturnUrlParameter = CookieAuthenticationDefaults.ReturnUrlParameter;
});
{
options.AccessDeniedPath = "/Account/AccessDenied";
options.Cookie.Name = "YourAppCookieName";
options.LoginPath = "/Account/Login";
// ReturnUrlParameter requires ùsing Microsoft.AspNetCore.Authentication.Cookies;`
options.ReturnUrlParameter = CookieAuthenticationDefaults.ReturnUrlParameter;
});
{
// Cookie settings
options.Cookies.ApplicationCookie.CookieName = "YourAppCookieName";
options.Cookies.ApplicationCookie.ExpireTimeSpan = TimeSpan.FromDays(150);
options.Cookies.ApplicationCookie.LoginPath = "/Account/LogIn";
options.Cookies.ApplicationCookie.AccessDeniedPath = "/Account/AccessDenied";
options.Cookies.ApplicationCookie.AutomaticAuthenticate = true;
// Requires ùsing Microsoft.AspNetCore.Authentication.Cookies;`
options.Cookies.ApplicationCookie.AuthenticationScheme =
CookieAuthenticationDefaults.AuthenticationScheme;
options.Cookies.ApplicationCookie.ReturnUrlParameter = CookieAuthenticationDefaults.ReturnUrlParameter;
});
Para obter mais informações, consulte CookieAuthenticationOptions.

Configurar a autenticação do Windows no ASP.NET
Core

Autenticação do Windows podem ser configurada para aplicativos ASP.NET Core hospedados com o IIS
HTTP. sys, ou WebListener.
Autenticação do Windows se baseia no sistema operacional para autenticar usuários de aplicativos ASP.NET
Core. Você pode usar a autenticação do Windows quando o servidor é executado em uma rede corporativa
usando identidades de domínio do Active Directory ou outras contas do Windows para identificar os usuários.
Autenticação do Windows é mais adequada para ambientes de intranet em que os usuários, aplicativos cliente
e servidores web pertencem ao mesmo domínio do Windows.
Saiba mais sobre a autenticação do Windows e instalá-lo para o IIS.
Habilitar a autenticação do Windows em um aplicativo ASP.NET Core

O modelo de aplicativo Web Visual Studio pode ser configurado para dar suporte à autenticação do Windows.
Use o modelo de aplicativo de autenticação do Windows
No Visual Studio:
1. Crie um novo Aplicativo Web ASP.NET Core.
2. Selecione o aplicativo Web na lista de modelos.
3. Selecione o alterar autenticação botão e selecione autenticação do Windows.
Execute o aplicativo. O nome de usuário aparece na parte superior direita do aplicativo.
Para trabalhos de desenvolvimento usando o IIS Express, o modelo fornece toda a configuração necessária
para usar a autenticação do Windows. A seção a seguir mostra como configurar manualmente um aplicativo
ASP.NET Core para autenticação do Windows.
Configurações do Visual Studio para Windows e autenticação anônima
O projeto do Visual Studio propriedades da página depurar guia fornece caixas de seleção para a
autenticação do Windows e autenticação anônima.
Como alternativa, essas duas propriedades podem ser configuradas na launchsettings. JSON arquivo:
{
"iisSettings": {
"windowsAuthentication": true,
"anonymousAuthentication": false,
"iisExpress": {
"sslPort": 0
}
} // additional options trimmed
}
Habilitar a autenticação do Windows com o IIS

O IIS usa a módulo do ASP.NET Core para hospedar aplicativos ASP.NET Core. Autenticação do Windows
está configurada no IIS, não o aplicativo. As seções a seguir mostram como usar o Gerenciador do IIS para
configurar um aplicativo ASP.NET Core para usar a autenticação do Windows.
Configuração do IIS
Habilite o serviço de função do IIS para autenticação do Windows. Para obter mais informações, consulte
habilitar autenticação do Windows nos serviços de função do IIS (consulte a etapa 2) .
Middleware de integração do IIS está configurado para autenticar solicitações de automaticamente por padrão.
Para obter mais informações, consulte hospedar o ASP.NET Core no Windows com o IIS: opções de IIS
(AutomaticAuthentication).
O módulo do ASP.NET está configurado para encaminhar o token de autenticação do Windows para o
aplicativo por padrão. Para obter mais informações, consulte referência de configuração do módulo do
ASP.NET Core: atributos do elemento aspNetCore.
Criar um novo site do IIS
Especifique um nome e uma pasta e permitir que ele crie um novo pool de aplicativos.
Personalizar autenticação
Abra os recursos de autenticação para o site.
Desabilitar a autenticação anônima e habilitar a autenticação do Windows.
Publicar seu projeto para a pasta de site do IIS

Usando o Visual Studio ou a CLI do .NET Core, publica o aplicativo para a pasta de destino.
Saiba mais sobre publicar no IIS.
Inicie o aplicativo para verificar se a autenticação do Windows está funcionando.
Habilitar a autenticação do Windows com o HTTP. sys

Embora o Kestrel não dá suporte a autenticação do Windows, você pode usar HTTP. sys para dar suporte a
cenários são hospedados no Windows. O exemplo a seguir configura o host de web do aplicativo para usar o
HTTP. sys com a autenticação do Windows:

{
public static void Main(string[] args) =>

{
options.Authentication.Schemes =
AuthenticationSchemes.NTLM | AuthenticationSchemes.Negotiate;
options.Authentication.AllowAnonymous = false;
})
.Build();
}
NOTE
O HTTP.sys delega à autenticação de modo kernel com o protocolo de autenticação Kerberos. Não há suporte para
autenticação de modo de usuário com o Kerberos e o HTTP.sys. A conta do computador precisa ser usada para
descriptografar o token/tíquete do Kerberos que é obtido do Active Directory e encaminhado pelo cliente ao servidor
para autenticar o usuário. Registre o SPN (nome da entidade de serviço) do host, não do usuário do aplicativo.
NOTE
Não há suporte para http. sys no Nano Server versão 1709 ou posterior. Para usar a autenticação do Windows e o HTTP.
sys com o Nano Server, use uma contêiner de Server Core (microsoft/windowsservercore). Para obter mais informações
sobre o Server Core, consulte qual é a opção de instalação Server Core no Windows Server?.
Habilitar a autenticação do Windows com o WebListener

Embora o Kestrel não dá suporte a autenticação do Windows, você pode usar WebListener para dar suporte a
cenários são hospedados no Windows. O exemplo a seguir configura o host de web do aplicativo para usar
WebListener com a autenticação do Windows:

{
{
.UseWebListener(options =>
{
options.ListenerSettings.Authentication.Schemes =
AuthenticationSchemes.Negotiate | AuthenticationSchemes.NTLM;
options.ListenerSettings.Authentication.AllowAnonymous = false;
})
.Build();
host.Run();
}
}
NOTE
O WebListener delega à autenticação de modo kernel com o protocolo de autenticação Kerberos. Não há suporte para
autenticação de modo de usuário com o Kerberos e o WebListener. A conta do computador precisa ser usada para
descriptografar o token/tíquete do Kerberos que é obtido do Active Directory e encaminhado pelo cliente ao servidor
para autenticar o usuário. Registre o SPN (nome da entidade de serviço) do host, não do usuário do aplicativo.
Trabalhar com a autenticação do Windows

Estado da configuração do acesso anônimo determina o modo no qual o [Authorize] e [AllowAnonymous]
atributos são usados no aplicativo. As seções a seguir explicam como lidar com os estados de configuração não
permitidos e têm permissão de acesso anônimo.
Não permitir acesso anônimo
Quando a autenticação do Windows está habilitada e o acesso anônimo é desabilitado, o [Authorize] e
[AllowAnonymous] atributos não têm nenhum efeito. Se o site do IIS (ou servidor HTTP. sys ou WebListener )
estiver configurado para não permitir acesso anônimo, a solicitação nunca atinge seu aplicativo. Por esse
motivo, o [AllowAnonymous] atributo não é aplicável.
Permitir o acesso anônimo
Quando a autenticação do Windows e o acesso anônimo estão habilitados, use o [Authorize] e
[AllowAnonymous] atributos. O [Authorize] atributo permite que você possa proteger partes do aplicativo que
realmente exigem a autenticação do Windows. O [AllowAnonymous] substituições de atributo [Authorize]
atributo uso dentro de aplicativos que permitem o acesso anônimo. Ver autorização simples para obter
detalhes de uso do atributo.
No ASP.NET Core 2.x, o [Authorize] atributo requer configuração adicional no Startup.cs desafiar solicitações
anônimas para a autenticação do Windows. A configuração recomendada varia um pouco com base no
servidor web que está sendo usado.
NOTE
Por padrão, os usuários que não têm autorização para acessar uma página são apresentados com uma resposta HTTP
403 vazia. O StatusCodePages middleware pode ser configurado para fornecer aos usuários uma melhor experiência de
"Acesso negado".
IIS
Se usar o IIS, adicione o seguinte para o ConfigureServices método:
// IISDefaults requires the following import:

// using Microsoft.AspNetCore.Server.IISIntegration;
services.AddAuthentication(IISDefaults.AuthenticationScheme);
HTTP.sys
Se usando HTTP. sys, adicione o seguinte para o ConfigureServices método:
// HttpSysDefaults requires the following import:

// using Microsoft.AspNetCore.Server.HttpSys;
services.AddAuthentication(HttpSysDefaults.AuthenticationScheme);
Representação
ASP.NET Core não implementar a representação. Aplicativos executados com a identidade do aplicativo para
todas as solicitações, usando a identidade de pool ou processo do aplicativo. Se você precisar executar
explicitamente uma ação em nome do usuário, use WindowsIdentity.RunImpersonated . Executar uma única ação
nesse contexto e, em seguida, feche o contexto.

{
try
{
var user = (WindowsIdentity)context.User.Identity;
.WriteAsync($"User: {user.Name}\tState: {user.ImpersonationLevel}\n");
WindowsIdentity.RunImpersonated(user.AccessToken, () =>
{
var impersonatedUser = WindowsIdentity.GetCurrent();
var message =
$"User: {impersonatedUser.Name}\tState: {impersonatedUser.ImpersonationLevel}";
var bytes = Encoding.UTF8.GetBytes(message);

context.Response.Body.Write(bytes, 0, bytes.Length);
});
}
catch (Exception e)
{
await context.Response.WriteAsync(e.ToString());
}
});
Observe que RunImpersonated não oferece suporte a operações assíncronas e não deve ser usado para
cenários complexos. Por exemplo, solicitações de todas ou cadeias de middleware de encapsulamento não é
tem suporte ou recomendado.
Provedores de armazenamento personalizados para
ASP.NET Core Identity
Por Steve Smith

O ASP.NET Core Identity é um sistema extensível que permite que você crie um provedor de armazenamento
personalizado e conectá-lo ao seu aplicativo. Este tópico descreve como criar um provedor de armazenamento
personalizado para o ASP.NET Core Identity. Ele aborda os conceitos importantes para a criação de seu próprio
provedor de armazenamento, mas não é um passo a passo.
Introdução
Por padrão, o sistema de identidade do ASP.NET Core armazena informações de usuário em um banco de dados
do SQL Server usando o Entity Framework Core. Para muitos aplicativos, essa abordagem funciona bem. No
entanto, você pode preferir usar um mecanismo de persistência diferente ou esquema de dados. Por exemplo:
Você usa Azure Table Storage ou outro armazenamento de dados.
As tabelas de banco de dados têm uma estrutura diferente.
Talvez você queira usar uma abordagem de acesso de dados diferentes, como Dapper.
Em cada um desses casos, você pode escrever um provedor personalizado para seu mecanismo de
armazenamento e conecte esse provedor ao seu aplicativo.
O ASP.NET Core Identity é incluído nos modelos de projeto no Visual Studio com a opção "Contas de usuário
individuais".
Ao usar a CLI do .NET Core, adicione -au Individual :
dotnet new mvc -au Individual

dotnet new webapi -au Individual
A arquitetura do ASP.NET Core Identity

Identidade do ASP.NET Core consiste em classes chamado gerentes e repositórios. Gerenciadores de são classes
de alto nível que um desenvolvedor de aplicativo usa para executar operações, como a criação de um usuário de
identidade. Repositórios são classes de nível inferior que especificam como entidades, como usuários e funções, são
persistentes. Repositórios seguem o padrão de repositório e estão intimamente acoplados com o mecanismo de
persistência. Os gerentes são separados dos armazenamentos, que significa que você pode substituir o mecanismo
de persistência sem alterar o código do aplicativo (com exceção de configuração).
O diagrama a seguir mostra como um aplicativo web interage com os gerentes, enquanto os armazenamentos de
interagem com a camada de acesso a dados.
Para criar um provedor de armazenamento personalizado, crie a fonte de dados, a camada de acesso a dados e as
classes de armazenamento que interagem com esta camada de acesso de dados (as caixas verdes e cinza no
diagrama acima). Você não precisa personalizar os gerentes ou seu código de aplicativo que interage com eles (as
caixas azuis acima).
Ao criar uma nova instância da UserManager ou RoleManager você fornecer o tipo da classe de usuário e passar
uma instância da classe de armazenamento como um argumento. Essa abordagem permite que você conecte suas
classes personalizadas no ASP.NET Core.
Reconfigurar o aplicativo para usar o novo provedor de armazenamento mostra como instanciar UserManager e
RoleManager com um repositório personalizado.
Tipos de dados de armazenamentos de identidade do ASP.NET Core

ASP.NET Core Identity tipos de dados são detalhados nas seções a seguir:
Usuários
Usuários registrados do seu site da web. O IdentityUser tipo pode ser estendido ou usado como um exemplo para
seu próprio tipo personalizado. Você não precisa herdar de um tipo específico para implementar sua própria
solução de armazenamento de identidade personalizada.
Declarações de usuário
Um conjunto de instruções (ou declarações) sobre o usuário que representam a identidade do usuário. Pode
permitir que uma expressão maior da identidade do usuário que pode ser obtido por meio de funções.
Logons de usuário
Informações sobre o provedor de autenticação externa (como Facebook ou uma conta da Microsoft) para usar ao
fazer logon em um usuário. Exemplo
Funções
Grupos de autorização para seu site. Inclui o nome da função Id e a função (como "Admin" ou "Employee").
Exemplo
A camada de acesso a dados

Este tópico pressupõe que você esteja familiarizado com o mecanismo de persistência que você pretende usar e
como criar entidades para esse mecanismo. Este tópico não fornece detalhes sobre como criar os repositórios ou
classes de acesso a dados; Ele fornece algumas sugestões sobre decisões de design ao trabalhar com o ASP.NET
Core Identity.
Você tem liberdade ao projetar a camada de acesso a dados para um provedor de repositório personalizado. Você
só precisará criar mecanismos de persistência para os recursos que você pretende usar em seu aplicativo. Por
exemplo, se você não estiver usando as funções em seu aplicativo, você não precisa criar armazenamento para
funções ou associações de função de usuário. Sua tecnologia e a infraestrutura existente podem exigir uma
estrutura que é muito diferente da implementação padrão do ASP.NET Core Identity. Na camada de acesso a
dados, você deve fornecer a lógica para trabalhar com a estrutura da sua implementação de armazenamento.
A camada de acesso a dados fornece a lógica para salvar os dados de identidade do ASP.NET Core em uma fonte
de dados. Camada de acesso a dados para o seu provedor de armazenamento personalizado pode incluir as
seguintes classes para armazenar informações de usuário e a função.
Classe de contexto
Encapsula as informações para conectar-se ao mecanismo de persistência e executar consultas. Várias classes de
dados requerem uma instância dessa classe, normalmente é fornecido por meio da injeção de dependência.
Exemplo.
Armazenamento de usuário
Armazena e recupera informações de usuário (por exemplo, o hash de nome e a senha do usuário). Exemplo
Armazenamento de função
Armazena e recupera informações de função (como o nome da função). Exemplo
Armazenamento de UserClaims
Armazena e recupera informações de declaração de usuário (como o tipo de declaração e o valor). Exemplo
Armazenamento de UserLogins
Armazena e recupera informações de logon do usuário (como um provedor de autenticação externa). Exemplo
Armazenamento de UserRole
Armazena e recupera a quais funções são atribuídas a quais usuários. Exemplo
Dica: implementar apenas as classes que você pretende usar em seu aplicativo.
Em classes de acesso a dados, forneça o código para executar operações de dados para o mecanismo de
persistência. Por exemplo, dentro de um provedor personalizado, você pode ter o código a seguir para criar um
novo usuário na armazenar classe:
public async Task<IdentityResult> CreateAsync(ApplicationUser user,

CancellationToken cancellationToken = default(CancellationToken))
{
cancellationToken.ThrowIfCancellationRequested();
if (user == null) throw new ArgumentNullException(nameof(user));
return await _usersTable.CreateAsync(user);

}
A lógica de implementação para criar o usuário está no _usersTable.CreateAsync método, mostrado abaixo.
Personalizar a classe de usuário

Ao implementar um provedor de armazenamento, crie uma classe de usuário que é equivalente à classe
IdentityUser.
No mínimo, sua classe de usuário deve incluir um Id e um UserName propriedade.
O IdentityUser classe define as propriedades que o UserManager chamadas ao executar operações de solicitadas.
O tipo de padrão de Id propriedade é uma cadeia de caracteres, mas você pode herdar de
IdentityUser<TKey, TUserClaim, TUserRole, TUserLogin, TUserToken> e especifique um tipo diferente. O framework
espera que a implementação de armazenamento para lidar com conversões de tipo de dados.
Personalizar o repositório do usuário

Criar um UserStore classe que fornece os métodos para todas as operações de dados no usuário. Essa classe é
equivalente a UserStore<TUser> classe. No seu UserStore classe, implemente IUserStore<TUser> e as interfaces
opcionais necessárias. Você selecione quais interfaces opcionais para implementar com base na funcionalidade
fornecida no seu aplicativo.
Interfaces opcionais
IUserRoleStore
IUserClaimStore
IUserPasswordStore
IUserSecurityStampStore
IUserEmailStore
IPhoneNumberStore
IQueryableUserStore
IUserLoginStore
IUserTwoFactorStore
IUserLockoutStore
As interfaces opcionais herdam IUserStore<TUser> . Você pode ver que um usuário de exemplo parcialmente
implementada armazenar na aplicativo de exemplo.
Dentro de UserStore classe, que você usar as classes de acesso de dados que você criou para executar operações.
Eles são passados usando a injeção de dependência. Por exemplo, no SQL Server com a implementação do
Dapper, o UserStore classe tem o CreateAsync método que usa uma instância de DapperUsersTable para inserir
um novo registro:
public async Task<IdentityResult> CreateAsync(ApplicationUser user)

{
string sql = "INSERT INTO dbo.CustomUser " +
"VALUES (@id, @Email, @EmailConfirmed, @PasswordHash, @UserName)";
int rows = await _connection.ExecuteAsync(sql, new { user.Id, user.Email, user.EmailConfirmed,

user.PasswordHash, user.UserName });
if(rows > 0)
{
return IdentityResult.Success;
}
return IdentityResult.Failed(new IdentityError { Description = $"Could not insert user {user.Email}." });
}
Interfaces a serem implementadas durante a personalização armazenamento de usuário
IUserStore
O IUserStore<TUser> interface é a única interface, você deve implementar no repositório do usuário. Define
métodos para criar, atualizar, excluir e recuperar os usuários.
IUserClaimStore
O IUserClaimStore<TUser> interface define os métodos a implementar para habilitar declarações do usuário.
Ela contém métodos para adicionar, remover e recuperando as declarações de usuário.
IUserLoginStore
O IUserLoginStore<TUser> define os métodos a implementar para habilitar provedores de autenticação
externa. Ela contém métodos para adicionar, remover e recuperar os logons de usuário e um método para
recuperar um usuário com base nas informações de logon.
IUserRoleStore
O IUserRoleStore<TUser> interface define os métodos a implementar para mapear um usuário a uma função.
Ela contém métodos para adicionar, remover e recuperar funções de usuário e um método para verificar se um
usuário está atribuído a uma função.
IUserPasswordStore
O IUserPasswordStore<TUser> interface define os métodos a implementar para persistir as senhas hash. Ela
contém métodos para obter e definir a senha de hash e um método que indica se o usuário tiver definido uma
senha.
IUserSecurityStampStore
O IUserSecurityStampStore<TUser> interface define os métodos a implementar para usar um carimbo de
segurança para que indica se as informações da conta do usuário foi alterado. Esse carimbo é atualizado
quando um usuário altera a senha ou adiciona ou remove logons. Ela contém métodos para obter e definir o
carimbo de segurança.
IUserTwoFactorStore
O IUserTwoFactorStore<TUser> interface define os métodos a implementar para dar suporte à autenticação de
dois fatores. Ela contém métodos para obter e definir se a autenticação de dois fatores é ativada para um
usuário.
IUserPhoneNumberStore
O IUserPhoneNumberStore<TUser> interface define os métodos a implementar para armazenar números de
telefone do usuário. Ela contém métodos para obter e definir o número de telefone e se o número de telefone
foi confirmado.
IUserEmailStore
O IUserEmailStore<TUser> interface define os métodos a implementar para armazenar endereços de email do
usuário. Ela contém métodos para obter e definir o endereço de email e se o email for confirmado.
IUserLockoutStore
O IUserLockoutStore<TUser> interface define os métodos a implementar para armazenar informações sobre
como bloquear uma conta. Ela contém métodos para controlar as tentativas de acesso com falha e bloqueios.
IQueryableUserStore
O IQueryableUserStore<TUser> interface define os membros que você pode implementar para fornecer um
repositório de usuários que podem ser consultados.
Você pode implementar apenas as interfaces que são necessários em seu aplicativo. Por exemplo:
public class UserStore : IUserStore<IdentityUser>,
IUserClaimStore<IdentityUser>,
IUserLoginStore<IdentityUser>,
IUserRoleStore<IdentityUser>,
IUserPasswordStore<IdentityUser>,
IUserSecurityStampStore<IdentityUser>
{
// interface implementations not shown
}
IdentityUserClaim, IdentityUserLogin e IdentityUserRole

O Microsoft.AspNet.Identity.EntityFramework namespace contém implementações do IdentityUserClaim,
IdentityUserLogin, e IdentityUserRole classes. Se você estiver usando esses recursos, você talvez queira criar suas
próprias versões dessas classes e definir as propriedades para seu aplicativo. No entanto, às vezes, é mais eficiente
para não carregar essas entidades na memória ao executar operações básicas (como adicionar ou remover a
declaração do usuário). Em vez disso, as classes de armazenamento de back-end podem executar essas operações
diretamente na fonte de dados. Por exemplo, o UserStore.GetClaimsAsync método pode chamar o
userClaimTable.FindByUserId(user.Id) método para executar uma consulta em que diretamente da tabela e retorna
uma lista de declarações.
Personalizar a classe de função

Ao implementar um provedor de armazenamento de função, você pode criar um tipo de função personalizada. Ele
não precisa implementar uma interface específica, mas ele deve ter uma Id e, normalmente terá uma Name
propriedade.
A seguir está um exemplo de classe de função:
using System;
namespace CustomIdentityProviderSample.CustomProvider
{
public class ApplicationRole
{
public Guid Id { get; set; } = Guid.NewGuid();
}
}
Personalizar o repositório da função

Você pode criar um RoleStore classe que fornece os métodos para todas as operações de dados em funções. Essa
classe é equivalente a alteração do RoleStore<TRole> classe. No RoleStore classe, você implementa o
IRoleStore<TRole> e, opcionalmente, o IQueryableRoleStore<TRole> interface.
IRoleStore<TRole>
O IRoleStore<TRole> interface define os métodos a implementar na classe de repositório de função. Ela
contém métodos para criar, atualizar, excluir e recuperar funções.
RoleStore<TRole>
Para personalizar RoleStore , crie uma classe que implementa o IRoleStore<TRole> interface.
Reconfigurar o aplicativo para usar um novo provedor de

armazenamento
Depois de implementar um provedor de armazenamento, você pode configurar seu aplicativo para usá-lo. Se seu
aplicativo usado o provedor padrão, substitua-o com o provedor personalizado.
1. Remover o Microsoft.AspNetCore.EntityFramework.Identity pacote do NuGet.
2. Se o provedor de armazenamento reside em um projeto separado ou um pacote, adicione uma referência a ele.
3. Substitua todas as referências a Microsoft.AspNetCore.EntityFramework.Identity com o uso de uma instrução
para o namespace do seu provedor de armazenamento.
4. No ConfigureServices método, altere o AddIdentity método usar seus tipos personalizados. Você pode criar
seus próprios métodos de extensão para essa finalidade. Ver IdentityServiceCollectionExtensions para obter um
exemplo.
5. Se você estiver usando as funções, atualize o RoleManager para usar seu RoleStore classe.
6. Atualize a cadeia de caracteres de conexão e as credenciais para a configuração de seu aplicativo.
Exemplo:

{
// Add identity types
// Identity Services
services.AddTransient<IUserStore<ApplicationUser>, CustomUserStore>();
services.AddTransient<IRoleStore<ApplicationRole>, CustomRoleStore>();
string connectionString = Configuration.GetConnectionString("DefaultConnection");
services.AddTransient<SqlConnection>(e => new SqlConnection(connectionString));
services.AddTransient<DapperUsersTable>();
// additional configuration
}
Referências
Provedores de armazenamento personalizados para a identidade do ASP.NET 4.x
ASP.NET Core Identity – neste repositório inclui links para a comunidade mantida provedores de
armazenamento.
Autenticação de Facebook, Google e de provedor
externo no ASP.NET Core
Por Valeriy Novytskyy e Rick Anderson

Este tutorial demonstra como criar um aplicativo ASP.NET Core 2.x que permite aos usuários fazer logon
usando o OAuth 2.0 com as credenciais de provedores de autenticação externa.
Os provedores Facebook, Twitter, Google e Microsoft são abordados nas seções a seguir. Outros provedores
estão disponíveis em pacotes de terceiros, como AspNet.Security.OAuth.Providers e
AspNet.Security.OpenId.Providers.
Permitir que os usuários entrem com suas credenciais existentes é conveniente para os usuários e transfere
muitas das complexidades de gerenciar o processo de entrada para um terceiro. Para obter exemplos de como
os logons sociais podem impulsionar o tráfego e as conversões de clientes, consulte os estudos de caso do
Facebook e do Twitter.
Observação: os pacotes apresentados aqui eliminam uma grande parte da complexidade do fluxo de
autenticação OAuth, mas o entendimento dos detalhes pode ser necessário durante a solução de problemas.
Muitos recursos estão disponíveis; por exemplo, consulte Introdução ao OAuth 2 ou Noções básicas do OAuth
2. Alguns problemas podem ser resolvidos examinando o código-fonte do ASP.NET Core para os pacotes de
provedores.
Criar um novo projeto ASP.NET Core

No Visual Studio 2017, crie um novo projeto na Página Inicial ou por meio de Arquivo > Novo >
Projeto.
Selecione o modelo Aplicativo Web ASP.NET Core disponível na categoria Visual C# > .NET Core:
Toque em Aplicativo Web e verifique se a opção Autenticação está definida como Contas de Usuário
Individuais:
Observação: este tutorial aplica-se à versão do SDK do ASP.NET Core 2.0 que pode ser selecionada na parte
superior do assistente.
Aplicar migrações
Execute o aplicativo e selecione o link login.
Selecione o link Registrar como um novo usuário.
Insira o email e a senha para a nova conta e, em seguida, selecione Registrar.
Siga as instruções para aplicar as migrações.
Exigir SSL
O OAuth 2.0 exige o uso de SSL para autenticação por meio do protocolo HTTPS.
Observação: os projetos criados com o uso de modelos de projeto Aplicativo Web ou API Web para o
ASP.NET Core 2.x são automaticamente configurados para habilitar o SSL e iniciados com a URL HTTPS se a
opção Contas de Usuário Individuais foi selecionada na caixa de diálogo Alterar Autenticação no
assistente do projeto, conforme mostrado acima.
Exija o SSL em seu site seguindo as etapas do tópico Impor o SSL em um aplicativo ASP.NET Core.
Usar o SecretManager para armazenar os tokens atribuídos por

provedores de logon
Os provedores de logon social atribuem tokens de ID do Aplicativo e Segredo do Aplicativo durante o
processo de registro. Os nomes de token exatos variam de acordo com o provedor. Esses tokens representam
as credenciais que seu aplicativo usa para acessar a API. Os tokens constituem os "segredos" que podem ser
vinculados à configuração de aplicativo com a ajuda do Secret Manager. O Secret Manager é uma alternativa
mais segura para armazenar os tokens em um arquivo de configuração, como appsettings.json.
IMPORTANT
O Secret Manager destina-se apenas para fins de desenvolvimento. Você pode armazenar e proteger os segredos de
teste e produção do Azure com o provedor de configuração do Azure Key Vault.
Siga as etapas no tópico Armazenamento seguro dos segredos do aplicativo em desenvolvimento no ASP.NET
Core para armazenar os tokens atribuídos por cada provedor de logon abaixo.
Configurar os provedores de logon necessários para o aplicativo

Use os seguintes tópicos para configurar seu aplicativo para usar os respectivos provedores:
Instruções do Facebook
Instruções do Twitter
Instruções do Google
Instruções da Microsoft
Outras instruções do provedor
Caso o aplicativo exija vários provedores, encadeie os métodos de extensão do provedor em
AddAuthentication:
services.AddAuthentication()
.AddMicrosoftAccount(microsoftOptions => { ... })
.AddGoogle(googleOptions => { ... })
.AddTwitter(twitterOptions => { ... })
.AddFacebook(facebookOptions => { ... });
Definir a senha opcionalmente

Ao registrar um provedor de logon externo, você não precisa ter uma senha registrada no aplicativo. Isso o
alivia da tarefa de criar e lembrar de uma senha para o site, mas também o torna dependente do provedor de
logon externo. Se o provedor de logon externo não estiver disponível, você não poderá fazer logon no site.
Para criar uma senha e entrar usando seu email definido durante o processo de entrada com provedores
externos:
Toque no link alias de email Olá < > na parte superior direita para navegar até a exibição Gerenciar.
Toque em Criar
Defina uma senha válida e use-a para entrar com seu email.
Próximas etapas
Este artigo apresentou a autenticação externa e explicou os pré-requisitos necessários para adicionar
logons externos ao aplicativo ASP.NET Core.
Páginas de referência específicas ao provedor para configurar logons para os provedores necessários
para o aplicativo.
Você talvez queira manter os dados adicionais sobre o usuário e seus tokens de atualização e acesso.
Para obter mais informações, consulte Manter declarações adicionais e os tokens de provedores
externos no ASP.NET Core.
Configuração de logon externo do Facebook no
ASP.NET Core

Este tutorial mostra como permitir que os usuários entrem com a conta do Facebook deles usando um projeto de
amostra do ASP.NET Core 2.0 criado na página anterior. Autenticação do Facebook requer o
Microsoft.AspNetCore.Authentication.Facebook pacote do NuGet. Vamos começar criando um Facebook App ID
seguindo as etapas oficiais.
Criar o aplicativo no Facebook

Navegue até a página aplicativos no site para desenvolvedores do Facebook. Se você ainda não tiver uma
conta do Facebook, use o link Sign up foinscrever-se para o Facebook na página de logon para criar
uma.
Clique no botão adicionar um novo aplicativo no canto superior direito para criar uma nova ID de
aplicativo.
Preencha o formulário e clique no botão criar ID do aplicativo.
Na página selecionar um produto , clique em Set Up no painel Facebook Login.

O assistente Quickstart iniciará com escolher uma plataforma como a primeira página. Ignore o
assistente clicando no link configurações no menu à esquerda:
Você verá a configurações do cliente OAuth página:

Insira o URI de desenvolvimento com /signin-facebook acrescentado para o URIs de redirecionamento de
OAuth válido campo (por exemplo: https://localhost:44320/signin-facebook ). A autenticação do Facebook
configurada mais tarde neste tutorial automaticamente manipulará as solicitações no /signin-facebook rota
para implementar o fluxo de OAuth.
NOTE
O URI /signin-facebook é definido como o retorno de chamada padrão do provedor de autenticação do Facebook. Você
pode alterar o retorno de chamada padrão URI ao configurar o middleware de autenticação do Facebook por meio de
herdadas RemoteAuthenticationOptions.CallbackPath propriedade da FacebookOptions classe.
Clique em salvar alterações.

Clique em Configurações > básico link no painel de navegação à esquerda.
Nessa página, anote seu App ID e seu App Secret . Você adicionará os dois em seu aplicativo ASP.NET
Core na próxima seção:
Ao implantar o site, você precisará voltar para a página de configurações Logon do Facebook e registrar
um novo URI público.
ID do Facebook App Store e o segredo do aplicativo

Vincular as configurações confidenciais, como o Facebook App ID e App Secret para sua configuração de
aplicativo usando o Secret Manager. Para os fins deste tutorial, nomeie os tokens Authentication:Facebook:AppId
e Authentication:Facebook:AppSecret .
Execute os seguintes comandos para armazenar com segurança App ID e App Secret usando o Secret Manager:
dotnet user-secrets set Authentication:Facebook:AppId <app-id>

dotnet user-secrets set Authentication:Facebook:AppSecret <app-secret>
Configurar a autenticação do Facebook

ASP.NET Core 2.x
ASP.NET Core 1.x
Adicione o serviço do Facebook no método ConfigureServices do arquivo Startup.cs :
services.AddAuthentication().AddFacebook(facebookOptions =>
{
facebookOptions.AppId = Configuration["Authentication:Facebook:AppId"];
facebookOptions.AppSecret = Configuration["Authentication:Facebook:AppSecret"];
});
A chamada para AddIdentity define as configurações de esquema padrão. O AddAuthentication(String) conjuntos

de sobrecarregar os DefaultScheme propriedade. O AddAuthentication (ação<AuthenticationOptions>)
sobrecarga permite configurar opções de autenticação, que podem ser usadas para definir os esquemas de
autenticação padrão para finalidades diferentes. As chamadas subsequentes para AddAuthentication substituição
configurada anteriormente AuthenticationOptions propriedades.
AuthenticationBuilder métodos de extensão que registra um manipulador de autenticação podem ser chamados
apenas uma vez por esquema de autenticação. Há sobrecargas que permitem configurar as propriedades de
esquema, o nome de esquema e nome de exibição.
Caso o aplicativo exija vários provedores, encadeie os métodos de extensão do provedor em AddAuthentication:
Consulte as referências de API do FacebookOptions para obter mais informações sobre as opções de
configuração compatíveis com a autenticação do Facebook. As opções de configuração podem ser usadas para:
Solicitar informações diferentes sobre o usuário.
Adicionar argumentos de cadeia de caracteres de consulta para personalizar a experiência de logon.
Entrar com o Facebook

Executar o aplicativo e clique em faça logon no. Você verá uma opção para entrar com o Facebook.
Quando você clica em Facebook, você será redirecionado ao Facebook para autenticação:
Autenticação do Facebook solicita o endereço de email e o perfil público por padrão:

Depois que você insira suas credenciais do Facebook, você será redirecionado para seu site em que você pode
definir seu email.
Agora você está conectado usando suas credenciais do Facebook:
Apenas ASP.NET Core 2.x: se a identidade não for configurada chamando services.AddIdentity no
ConfigureServices , a autenticação resultará em ArgumentException: a opção 'SignInScheme' deve ser
fornecida. O modelo de projeto usado neste tutorial garante que isso é feito.
Se o banco de dados do site não foi criado por meio da aplicação a migração inicial, você obterá uma
operação de banco de dados falhou ao processar a solicitação erro. Toque aplicar migrações para criar o
banco de dados e atualizar para continuar após o erro.
Próximas etapas
Este artigo mostrou como você pode autenticar com o Facebook. Você pode seguir uma abordagem
semelhante para autenticar com outros provedores listados na página anterior.
Depois de publicar seu site da web para aplicativo web do Azure, você deve redefinir o AppSecret no
portal do desenvolvedor do Facebook.
Defina as Authentication:Facebook:AppId e Authentication:Facebook:AppSecret como configurações de
aplicativo no portal do Azure. Configurar o sistema de configuração para ler as chaves de variáveis de
ambiente.
Configuração de logon externo com o ASP.NET Core
do Twitter

Este tutorial mostra como habilitar usuários para entrar com sua conta do Twitter usando um projeto do
ASP.NET Core 2.0 de exemplo criado na página anterior.
Criar o aplicativo no Twitter

Navegue até https://apps.twitter.com/ e entrar. Se você ainda não tiver uma conta do Twitter, use o inscrever-
se agora link para criar uma. Depois de entrar, o gerenciamento de aplicativos página é mostrada:
Toque em criar novo aplicativo e preencha o aplicativo nome, descrição pública e site URI (que pode ser
temporária até que você Registre o nome de domínio):
Insira o URI de desenvolvimento com /signin-twitter acrescentados no válido URIs de redirecionamento
OAuth campo (por exemplo: https://localhost:44320/signin-twitter ). O esquema de autenticação do Twitter
configurado posteriormente neste tutorial automaticamente manipulará as solicitações no /signin-twitter
rota para implementar o fluxo do OAuth.
NOTE
O segmento do URI /signin-twitter é definido como o retorno de chamada padrão do provedor de autenticação do
Twitter. Você pode alterar o retorno de chamada padrão URI ao configurar o middleware de autenticação do Twitter via o
herdadas RemoteAuthenticationOptions.CallbackPath propriedade o TwitterOptions classe.
Preencha o restante do formulário e toque em criar seu aplicativo Twitter. Novos detalhes do aplicativo são
exibidos:
Ao implantar o site será necessário rever o gerenciamento de aplicativos página e registrar um novo URI
público.
Armazenar Twitter ConsumerKey e ConsumerSecret

Vincular as configurações confidenciais, como o Twitter Consumer Key e Consumer Secret para sua configuração
de aplicativo usando o Manager segredo. Para os fins deste tutorial, nomeie os tokens
Authentication:Twitter:ConsumerKey e Authentication:Twitter:ConsumerSecret .
Esses tokens podem ser encontradas no chaves e Tokens de acesso guia depois de criar seu novo aplicativo
Twitter:
Configurar a autenticação do Twitter
O modelo de projeto usado neste tutorial garante que Microsoft.AspNetCore.Authentication.Twitter pacote já está
instalado.
Para instalar este pacote com o Visual Studio 2017, clique com botão direito no projeto e selecione
gerenciar pacotes NuGet.
Para instalar o .NET Core CLI, execute o seguinte comando no diretório do projeto:
dotnet add package Microsoft.AspNetCore.Authentication.Twitter
ASP.NET Core 2.x

ASP.NET Core 1.x
Adicione o serviço do Twitter no ConfigureServices método Startup.cs arquivo:
services.AddAuthentication().AddTwitter(twitterOptions =>
{
twitterOptions.ConsumerKey = Configuration["Authentication:Twitter:ConsumerKey"];
twitterOptions.ConsumerSecret = Configuration["Authentication:Twitter:ConsumerSecret"];
});

Consulte o TwitterOptions referência de API para obter mais informações sobre opções de configuração com
suporte pela autenticação do Twitter. Isso pode ser usado para solicitar informações diferentes sobre o usuário.
Entrar com o Twitter

Execute o aplicativo e clique em login. Será exibida uma opção para entrar com o Twitter:
Clicando em Twitter redireciona para o Twitter para autenticação:

Depois de inserir suas credenciais do Twitter, você será redirecionado para o site onde você pode definir seu
email.
Agora você está conectado usando suas credenciais do Twitter:
Se o banco de dados do site não tiver sido criado, aplicando a migração inicial, você obterá uma operação de
banco de dados falhou ao processar a solicitação erro. Toque em aplicar migrações para criar o banco de
dados e a atualização para continuar após o erro.
Próximas etapas
Este artigo mostrou como você pode autenticar com o Twitter. Você pode seguir uma abordagem
semelhante para autenticar com outros provedores listados no página anterior.
Depois de publicar seu site da web para o aplicativo web do Azure, você deve redefinir o ConsumerSecret
no portal do desenvolvedor do Twitter.
Definir o Authentication:Twitter:ConsumerKey e Authentication:Twitter:ConsumerSecret como
configurações de aplicativo no portal do Azure. O sistema de configuração é configurado para ler as
chaves de variáveis de ambiente.
Configuração de logon externo do Google no
núcleo do ASP.NET

Este tutorial mostra como habilitar os usuários entrar com sua conta Google + usando um projeto do ASP.NET
Core 2.0 de exemplo criado no página anterior. Vamos começar seguindo o oficiais etapas para criar um novo
aplicativo no Console de API do Google.
Criar o aplicativo no Console de API do Google

Navegue até https://console.developers.google.com/projectselector/apis/library e entrar. Se você ainda não
tiver uma conta do Google, use mais opções > criar conta link para criar um:
Você será redirecionado para biblioteca API Manager página:

Toque em criar e insira seu nome do projeto:
Após aceitar a caixa de diálogo, você será redirecionado para a página de biblioteca, permitindo que você
escolha os recursos para seu novo aplicativo. Localizar API do Google + na lista e clique em seu link para
adicionar o recurso de API:
A página para a API recém-adicionado é exibida. Toque em habilitar para adicionar o Google + sinal de
recurso ao seu aplicativo:
Depois de habilitar a API, toque em criar credenciais para configurar os segredos:
Escolha:
API do Google +
Servidor Web (por exemplo, node.js, Tomcat), e
Dados de usuário:
Toque em as credenciais que eu preciso? que leva você para a segunda etapa de configuração de aplicativo,
criar uma ID de cliente OAuth 2.0:
Porque estamos criando um projeto do Google + com apenas um recurso (entrada), podemos inserir a
mesma nome para a ID do cliente OAuth 2.0 é usado para o projeto.
Insira o URI de desenvolvimento com /signin-google acrescentados no autorizados redirecionar URIs
campo (por exemplo: https://localhost:44320/signin-google ). A autenticação do Google configurada mais
tarde neste tutorial automaticamente manipulará as solicitações no /signin-google rota para implementar
o fluxo do OAuth.
NOTE
O segmento do URI /signin-google é definido como o retorno de chamada padrão do provedor de autenticação do
Google. Você pode alterar o retorno de chamada padrão URI ao configurar o middleware de autenticação do Google por
meio de herdadas RemoteAuthenticationOptions.CallbackPath propriedade o GoogleOptions classe.
Pressione TAB para adicionar o autorizados redirecionar URIs entrada.

Toque em criar ID do cliente, que leva você para a terceira etapa, configurar a tela de consentimento
de OAuth 2.0:
Insira seu voltado ao público endereço de Email e nome do produto mostrado para seu aplicativo
quando Google + solicita ao usuário para entrar. Opções adicionais estão disponíveis em mais opções de
personalização.
Toque em continuar para prosseguir para a última etapa, baixar credenciais:
Toque em baixar para salvar um arquivo JSON com segredos do aplicativo, e feito para concluir a
criação do novo aplicativo.
Ao implantar o site será necessário rever o Google Console e registre uma nova url pública.
Loja Google ClientID e ClientSecret

Vincular as configurações confidenciais com o Google Client ID e Client Secret para sua configuração de
aplicativo usando o Manager segredo. Para os fins deste tutorial, nomeie os tokens
Authentication:Google:ClientId e Authentication:Google:ClientSecret .
Os valores para esses tokens podem ser encontrados no arquivo JSON baixado na etapa anterior em
web.client_id e web.client_secret .
Configurar a autenticação do Google

ASP.NET Core 2.x
ASP.NET Core 1.x
Adicione o serviço do Google no ConfigureServices método Startup.cs arquivo:
services.AddAuthentication().AddGoogle(googleOptions =>
{
googleOptions.ClientId = Configuration["Authentication:Google:ClientId"];
googleOptions.ClientSecret = Configuration["Authentication:Google:ClientSecret"];
});
A chamada para AddIdentity define as configurações de esquema padrão. O AddAuthentication(String)

conjuntos de sobrecarregar os DefaultScheme propriedade. O AddAuthentication
(ação<AuthenticationOptions>) sobrecarga permite configurar opções de autenticação, que podem ser usadas
para definir os esquemas de autenticação padrão para finalidades diferentes. As chamadas subsequentes para
AddAuthentication substituição configurada anteriormente AuthenticationOptions propriedades.
Consulte o GoogleOptions referência de API para obter mais informações sobre opções de configuração com
suporte pela autenticação do Google. Isso pode ser usado para solicitar informações diferentes sobre o usuário.
Entrar com o Google

Execute o aplicativo e clique em login. Uma opção para entrar com o Google aparece:
Quando você clica no Google, você é redirecionado para o Google para autenticação:
Depois de inserir suas credenciais do Google, em seguida, você será redirecionado para o site onde você pode
definir seu email.
Agora você está conectado usando suas credenciais do Google:
Se você receber um 403 (Forbidden) página de erro do seu próprio aplicativo quando em execução no modo
de desenvolvimento (ou interrupção no depurador com o mesmo erro), certifique-se de que API do Google
+ foi habilitada no API do Gerenciador de biblioteca seguindo as etapas listadas anteriores nesta página.
Se a entrada não funciona e não estiver obtendo erros, alterne para o modo de desenvolvimento para facilitar
o problema depurar.
Se o banco de dados do site não tiver sido criado, aplicando a migração inicial, você obterá uma operação de
banco de dados falhou ao processar a solicitação erro. Toque em aplicar migrações para criar o banco de
dados e a atualização para continuar após o erro.
Próximas etapas
Este artigo mostrou como você pode autenticar com o Google. Você pode seguir uma abordagem
Depois de publicar seu site da web para o aplicativo web do Azure, você deve redefinir o ClientSecret no
Console de API do Google.
Definir o Authentication:Google:ClientId e Authentication:Google:ClientSecret como configurações de
aplicativo no portal do Azure. O sistema de configuração é configurado para ler as chaves de variáveis de
ambiente.
Configuração de logon externo Account da
Microsoft com o ASP.NET Core

Este tutorial mostra como habilitar os usuários entrar com sua conta da Microsoft usando um projeto do
ASP.NET Core 2.0 de exemplo criado no página anterior.
Criar o aplicativo no Portal do desenvolvedor da Microsoft

Navegue até https://apps.dev.microsoft.com e criar ou entrar em uma conta da Microsoft:
Se você ainda não tiver uma conta da Microsoft, toque em criar um! Depois de entrar, você será redirecionado
para meus aplicativos página:
Toque em adicionar um aplicativo no canto superior direito de canto e insira seu nome do aplicativo e
Contact Email:
Para os fins deste tutorial, desmarque o instalação interativa caixa de seleção.

Toque em criar para continuar a registro página. Forneça um nome e observe o valor da Id do
aplicativo, que você usar como ClientId posteriormente no tutorial:
Toque em Adicionar plataforma no plataformas seção e selecione o Web plataforma:
No novo Web plataforma seção, digite a URL de desenvolvimento com /signin-microsoft acrescentados no
URLs de redirecionamento campo (por exemplo: https://localhost:44320/signin-microsoft ). O esquema de
autenticação da Microsoft configurado mais tarde neste tutorial automaticamente manipulará as solicitações
no /signin-microsoft rota para implementar o fluxo de OAuth:
NOTE
O segmento do URI /signin-microsoft é definido como o retorno de chamada padrão do provedor de autenticação do
Microsoft. Você pode alterar o retorno de chamada padrão URI ao configurar o middleware de autenticação da Microsoft
por meio de herdadas RemoteAuthenticationOptions.CallbackPath propriedade o MicrosoftAccountOptions classe.
Toque em Adicionar URL para garantir que a URL foi adicionada.

Preencha quaisquer outras configurações de aplicativo, se necessário e toque em salvar na parte inferior
da página para salvar as alterações de configuração do aplicativo.
Ao implantar o site será necessário rever o registro página e defina uma nova URL pública.
Armazenar a Id do aplicativo da Microsoft e a senha

Observe o Application Id exibido no registro página.
Toque em gerar nova senha no segredos do aplicativo seção. Isso exibe uma caixa em que você pode
copiar a senha de aplicativo:
Vincular as configurações confidenciais como Microsoft Application ID e Password para sua configuração de
aplicativo usando o Manager segredo. Para os fins deste tutorial, nomeie os tokens
Authentication:Microsoft:ApplicationId e Authentication:Microsoft:Password .
Configurar a autenticação de conta da Microsoft

O modelo de projeto usado neste tutorial garante que Microsoft.AspNetCore.Authentication.MicrosoftAccount
pacote já está instalado.
Para instalar este pacote com o Visual Studio 2017, clique com botão direito no projeto e selecione
gerenciar pacotes NuGet.
Para instalar o .NET Core CLI, execute o seguinte comando no diretório do projeto:
dotnet add package Microsoft.AspNetCore.Authentication.MicrosoftAccount
ASP.NET Core 2.x

ASP.NET Core 1.x
Adicione o serviço Microsoft Account no ConfigureServices método Startup.cs arquivo:
services.AddAuthentication().AddMicrosoftAccount(microsoftOptions =>
{
microsoftOptions.ClientId = Configuration["Authentication:Microsoft:ApplicationId"];
microsoftOptions.ClientSecret = Configuration["Authentication:Microsoft:Password"];
});

Embora a terminologia usada no Portal do desenvolvedor do Microsoft nomes esses tokens ApplicationId e
Password , eles são expostos como ClientId e ClientSecret para a API de configuração.
Consulte o MicrosoftAccountOptions referência de API para obter mais informações sobre opções de
configuração com suporte pela autenticação Account da Microsoft. Isso pode ser usado para solicitar informações
diferentes sobre o usuário.
Entrar com a conta da Microsoft

Execute o aplicativo e clique em login. Uma opção para entrar com Microsoft será exibida:
Quando você clica na Microsoft, você é redirecionado para a Microsoft para autenticação. Depois de entrar com
sua Account da Microsoft (se ainda não estiver conectado), você será solicitado para permitir que o aplicativo
acessar suas informações:
Toque em Sim e você será redirecionado para o site da web onde você pode definir seu email.
Agora você está conectado usando suas credenciais da Microsoft:
Se o provedor do Microsoft Account redireciona para uma página de erro de entrada, observe os erro
título e descrição de cadeia de caracteres parâmetros de consulta diretamente após o # (hashtag) no Uri.
Embora a mensagem de erro parece ser um problema com a autenticação do Microsoft, a causa mais
comum é seu aplicativo Uri não corresponde a nenhuma do URIs de redirecionamento especificado
para o Web plataforma .
Se o banco de dados do site não tiver sido criado, aplicando a migração inicial, você obterá uma operação
de banco de dados falhou ao processar a solicitação erro. Toque em aplicar migrações para criar o banco
de dados e a atualização para continuar após o erro.
Próximas etapas
Este artigo mostrou como você pode autenticar com a Microsoft. Você pode seguir uma abordagem
Depois de publicar seu site da web para o aplicativo web do Azure, você deve criar um novo Password no
Portal do desenvolvedor do Microsoft.
Definir o Authentication:Microsoft:ApplicationId e Authentication:Microsoft:Password como
configurações de aplicativo no portal do Azure. O sistema de configuração é configurado para ler as
chaves de variáveis de ambiente.
Pesquisa rápida de outros provedores de
autenticação
Por Rick Anderson, Pranav Rastogi, e Valeriy Novytskyy

Aqui estão configurados instruções para alguns outros provedores OAuth comuns. Pacotes do NuGet de terceiros,
como aqueles mantidos pelo aspnet Contribuidor pode ser usada para complementar os provedores de
autenticação implementados pela equipe do ASP.NET Core.
Configurar LinkedIn entrar: https://www.linkedin.com/developer/apps . Consulte etapas oficiais.
Configurar Instagram entrar: https://www.instagram.com/developer/register/ . Consulte etapas oficiais.
Configurar Reddit entrar: https://www.reddit.com/login?
dest=https%3A%2F%2Fwww.reddit.com%2Fprefs%2Fapps . Consulte etapas oficiais.
Configurar Github entrar: https://github.com/login?
return_to=https%3A%2F%2Fgithub.com%2Fsettings%2Fapplications%2Fnew . Consulte etapas oficiais.
Configurar Yahoo entrar: https://login.yahoo.com/config/login?
src=devnet&.done=http%3A%2F%2Fdeveloper.yahoo.com%2Fapps%2Fcreate%2F . Consulte etapas
oficiais.
Configurar Tumblr entrar: https://www.tumblr.com/oauth/apps . Consulte etapas oficiais.
Configurar Pinterest entrar: https://www.pinterest.com/login/?next=http%3A%2F%2Fdevsite%2Fapps%2F
. Consulte etapas oficiais.
Configurar Pocket entrar: https://getpocket.com/developer/apps/new . Consulte etapas oficiais.
Configurar Flickr entrar: https://www.flickr.com/services/apps/create . Consulte etapas oficiais.
Configurar Dribble entrar: https://dribbble.com/signup . Consulte etapas oficiais.
Configurar Vimeo entrar: https://vimeo.com/join . Consulte etapas oficiais.
Configurar SoundCloud entrar: https://soundcloud.com/you/apps/new . Consulte etapas oficiais.
Configurar VK entrar: https://vk.com/apps?act=manage . Consulte etapas oficiais.
Vários provedores de autenticação

Manter declarações adicionais e os tokens de
provedores externos no ASP.NET Core
Por Luke Latham

Um aplicativo ASP.NET Core pode estabelecer declarações adicionais e tokens de provedores de autenticação
externa, como Facebook, Google, Microsoft e Twitter. Cada provedor revela informações diferentes sobre os
usuários em sua plataforma, mas o padrão para receber e transformar dados de usuário em declarações adicionais é
o mesmo.
Pré-requisito
Decida quais provedores de autenticação externa para dar suporte a no aplicativo. Para cada provedor, registrar o
aplicativo e obter o ID do cliente e segredo do cliente. Para obter mais informações, consulte Autenticação de
Facebook, Google e de provedor externo no ASP.NET Core. O aplicativo de exemplo usa o provedor de autenticação
do Google.
Configuração do provedor de autenticação

Defina a ID do cliente e segredo do cliente
O provedor de autenticação OAuth estabelece uma relação de confiança com um aplicativo usando uma ID de
cliente e o segredo do cliente. ID do cliente e valores de segredo do cliente são criados para o aplicativo pelo
provedor de autenticação externa quando o aplicativo é registrado com o provedor. Cada provedor externo que usa
o aplicativo deve ser configurado independentemente com a ID do cliente e o segredo do cliente do provedor. Para
obter mais informações, consulte os tópicos de provedor de autenticação externa que se aplicam ao seu cenário:
Autenticação do Facebook
Autenticação da Microsoft
Outros provedores de autenticação
OpenIdConnect
O aplicativo de exemplo configura o provedor de autenticação do Google com uma ID do cliente e segredo do
cliente fornecido pelo Google:
services.AddAuthentication().AddGoogle(options =>
{
// Provide the Google Client ID
options.ClientId = "XXXXXXXXXXX.apps.googleusercontent.com";
// Provide the Google Secret
options.ClientSecret = "g4GZ2#...GD5Gg1x";
options.Scope.Add("https://www.googleapis.com/auth/plus.login");
options.ClaimActions.MapJsonKey(ClaimTypes.Gender, "gender");
options.SaveTokens = true;
options.Events.OnCreatingTicket = ctx =>
{
List<AuthenticationToken> tokens = ctx.Properties.GetTokens()
as List<AuthenticationToken>;
tokens.Add(new AuthenticationToken()
{
Name = "TicketCreated",
Value = DateTime.UtcNow.ToString()
});
ctx.Properties.StoreTokens(tokens);
};
});
Estabelecer o escopo de autenticação

Especifique a lista de permissões para recuperar do provedor, especificando o Scope. Escopos de autenticação para
provedores externos comuns aparecem na tabela a seguir.
PROVIDER ESCOPO
Facebook https://www.facebook.com/dialog/oauth
Google https://www.googleapis.com/auth/plus.login
Microsoft https://login.microsoftonline.com/common/oauth2/v2.0/authorize
Twitter https://api.twitter.com/oauth/authenticate
O aplicativo de exemplo adiciona o Google plus.login escopo para solicitar a entrada do Google + nas permissões:
{
{
{
});
};
});
Mapear chaves de dados de usuário e criar declarações
Nas opções do provedor, especifique um MapJsonKey para cada chave nos dados de usuário do provedor externo
JSON para a identidade do aplicativo ler em entrar. Para obter mais informações sobre tipos de declaração, consulte
ClaimTypes.
O aplicativo de exemplo cria um Gender reivindicar do gender chave nos dados de usuário do Google:
{
{
{
});
};
});
Na OnPostConfirmationAsync, uma IdentityUser ( ApplicationUser ) é conectado ao aplicativo com SignInAsync.

Durante o logon no processo, o UserManager<TUser> pode armazenar um ApplicationUser de declaração para os
dados de usuário disponíveis no Principal.
No aplicativo de exemplo, OnPostConfirmationAsync (Account/ExternalLogin.cshtml.cs) estabelece uma Gender de
declaração para assinado no ApplicationUser :
public async Task<IActionResult> OnPostConfirmationAsync(
string returnUrl = null)
{
{
// Get the information about the user from the external login
// provider
var info = await _signInManager.GetExternalLoginInfoAsync();
if (info == null)
{
throw new ApplicationException(
"Error loading external login data during confirmation.");
}
var user = new ApplicationUser

{
Email = Input.Email
};
var result = await _userManager.CreateAsync(user);
{
result = await _userManager.AddLoginAsync(user, info);
{
// Copy over the gender claim
await _userManager.AddClaimAsync(user,
info.Principal.FindFirst(ClaimTypes.Gender));
// Include the access token in the properties

var props = new AuthenticationProperties();
props.StoreTokens(info.AuthenticationTokens);
await _signInManager.SignInAsync(user, props,

authenticationMethod: info.LoginProvider);
"User created an account using {Name} provider.",
info.LoginProvider);
return LocalRedirect(Url.GetLocalUrl(returnUrl));
}
}

{
}
}
ReturnUrl = returnUrl;
return Page();
}
Salve o token de acesso

SaveTokens Define se os tokens de acesso e de atualização devem ser armazenadas do AuthenticationProperties
após uma autorização bem-sucedida. SaveTokens é definido como false por padrão para reduzir o tamanho do
cookie de autenticação final.
O aplicativo de exemplo define o valor de SaveTokens à true em GoogleOptions:
{
{
{
});
};
});
Quando OnPostConfirmationAsync é executado, armazenar o token de acesso

(ExternalLoginInfo.AuthenticationTokens) do provedor externo no ApplicationUser do AuthenticationProperties .
O aplicativo de exemplo salva o token de acesso em:
OnPostConfirmationAsync – É executado para o novo registro do usuário.
OnGetCallbackAsync – Executa quando um usuário registrado anteriormente entra no aplicativo.
Account/ExternalLogin.cshtml.cs:
public async Task<IActionResult> OnPostConfirmationAsync(
string returnUrl = null)
{
{
// Get the information about the user from the external login
// provider
if (info == null)
{
throw new ApplicationException(
"Error loading external login data during confirmation.");
}
var user = new ApplicationUser

{
Email = Input.Email
};
var result = await _userManager.CreateAsync(user);
{
result = await _userManager.AddLoginAsync(user, info);
{
// Copy over the gender claim
await _userManager.AddClaimAsync(user,
info.Principal.FindFirst(ClaimTypes.Gender));
// Include the access token in the properties

await _signInManager.SignInAsync(user, props,

authenticationMethod: info.LoginProvider);
"User created an account using {Name} provider.",
info.LoginProvider);
}
}

{
}
}
return Page();
}
public async Task<IActionResult> OnGetCallbackAsync(
string returnUrl = null, string remoteError = null)
{
if (remoteError != null)
{
ErrorMessage = $"Error from external provider: {remoteError}";
return RedirectToPage("./Login");
}
if (info == null)
{
return RedirectToPage("./Login");
}
// Sign in the user with this external login provider if the user
// already has a login
var result = await _signInManager.ExternalLoginSignInAsync(
info.LoginProvider, info.ProviderKey, isPersistent: false,
bypassTwoFactor : true);
{
// Store the access token and resign in so the token is included in
// in the cookie
var user = await _userManager.FindByLoginAsync(info.LoginProvider,
info.ProviderKey);

await _signInManager.SignInAsync(user, props, info.LoginProvider);
"{Name} logged in with {LoginProvider} provider.",
info.Principal.Identity.Name, info.LoginProvider);
}
{
}
else
{
// If the user does not have an account, then ask the user to
// create an account
LoginProvider = info.LoginProvider;
if (info.Principal.HasClaim(c => c.Type == ClaimTypes.Email))

{
Input = new InputModel
{
Email = info.Principal.FindFirstValue(ClaimTypes.Email)
};
}
return Page();
}
}
Como adicionar tokens personalizados adicionais

Para demonstrar como adicionar um token personalizado, que é armazenado como parte da SaveTokens ,o
aplicativo de exemplo adiciona um AuthenticationToken com o atual DateTime para um AuthenticationToken.Name
de TicketCreated :
{
{
{
});
};
});
Instruções do aplicativo de exemplo

O aplicativo de exemplo demonstra como:
Obtenha o sexo do usuário do Google e armazene uma declaração de sexo com o valor.
Store o token de acesso do Google, o usuário AuthenticationProperties .
Para usar o aplicativo de exemplo:

1. Registrar o aplicativo e obter uma ID de cliente válido e o segredo do cliente para autenticação do Google. Para
obter mais informações, consulte Configuração de logon externo do Google no núcleo do ASP.NET.
2. Forneça a ID de cliente e o segredo do cliente para o aplicativo na GoogleOptions de Startup.ConfigureServices .
3. Execute o aplicativo e solicite a página Minhas declarações. Quando o usuário não estiver conectado, o aplicativo
redireciona para o Google. Entrar com o Google. Google redireciona o usuário retorne ao aplicativo (
/Home/MyClaims ). O usuário é autenticado e a página Minhas declarações é carregada. A declaração de gênero
esteja presente em declarações de usuário com o valor obtido do Google. O token de acesso será exibido na as
propriedades de autenticação.
User Claims
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
b36a7b09-9135-4810-b7a5-78697ff23e99
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
username@gmail.com
AspNet.Identity.SecurityStamp
29G2TB881ATCUQFJSRFG1S0QJ0OOAWVT
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender
female
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod
Google
Authentication Properties
.Token.access_token
bv42.Dgw...GQMv9ArLPs
.Token.token_type
Bearer
.Token.expires_at
2018-08-27T19:08:00.0000000+00:00
.Token.TicketCreated
8/27/2018 6:08:00 PM
.TokenNames
access_token;token_type;expires_at;TicketCreated
.issued
Mon, 27 Aug 2018 18:08:05 GMT
.expires
Mon, 10 Sep 2018 18:08:05 GMT
Autenticar usuários com o WS-Federation no núcleo
do ASP.NET
Este tutorial demonstra como habilitar usuários entrar com um provedor de autenticação do WS -Federation como
o Active Directory Federation Services (ADFS ) ou Active Directory do Azure (AAD ). Ele usa o aplicativo de
exemplo do ASP.NET Core 2.0 descrito em Facebook, Google e a autenticação do provedor externo.
Para aplicativos do ASP.NET Core 2.0, o suporte do WS -Federation é fornecido por
Microsoft.AspNetCore.Authentication.WsFederation. Esse componente é movido de
Microsoft.Owin.Security.WsFederation e compartilha muitas das mecânica do componente. No entanto, os
componentes são diferentes de duas maneiras importantes.
Por padrão, o middleware novo:
Não permitir logons não solicitados. Esse recurso do protocolo WS -Federation é vulnerável a ataques XSRF.
No entanto, ela pode ser habilitada com o AllowUnsolicitedLogins opção.
Não verifica cada postagem de formulário para mensagens de entrada. Somente solicitações para o
CallbackPath são verificados quanto à entrada-ins CallbackPath assume como padrão /signin-wsfed , mas
pode ser alterado por meio de herdadas RemoteAuthenticationOptions.CallbackPath propriedade do
WsFederationOptions classe. Esse caminho pode ser compartilhado com outros provedores de autenticação,
permitindo que o SkipUnrecognizedRequests opção.
Registrar o aplicativo com o Active Directory

Serviços de Federação do Active Directory
Abra o servidor terceira parte confiável Assistente para adicionar confiança no console de gerenciamento
do AD FS:
Escolha esta opção para inserir os dados manualmente:
Insira um nome para exibição para a terceira parte confiável. O nome não é importante para o aplicativo
ASP.NET Core.
Microsoft.AspNetCore.Authentication.WsFederation não tem suporte para criptografia de token, portanto,
não configurar um certificado de criptografia do token:
Habilite o suporte para o protocolo WS -Federation Passive, usando a URL do aplicativo. Verifique se que a
porta está correta para o aplicativo:
NOTE
Isso deve ser uma URL HTTPS. O IIS Express pode fornecer um certificado autoassinado ao hospedar o aplicativo durante o
desenvolvimento. Kestrel requer configuração manual do certificado. Consulte o documentação Kestrel para obter mais
detalhes.
Clique em próximo através do restante do assistente e fechar no final.

A identidade do ASP.NET Core requer um ID de nome de declaração. Adicione um do editar regras de
declaração caixa de diálogo:
No Adicionar Assistente de regra de declaração de transformação, deixe o padrão enviar atributos
LDAP como declarações modelo selecionado e clique em próximo. Adicionar um mapeamento de regra a
nome de conta SAM atributo LDAP para o ID de nome declaração de saída:
Clique em concluir > Okey no editar regras de declaração janela.
Navegue até a folha de registros de aplicativo do locatário do AAD. Clique em novo registro de aplicativo:
Insira um nome para o registro do aplicativo. Isso não é importante para o aplicativo ASP.NET Core.
Insira a URL do aplicativo escuta em que o URL de logon:
Clique em pontos de extremidade e observe o documento de metadados de Federação URL. Este é o
middleware de WS -Federation MetadataAddress :
Navegue até o novo registro de aplicativo. Clique em configurações > propriedades e anote o URI da ID do
aplicativo. Este é o middleware de WS -Federation Wtrealm :
Adicionar o WS-Federation como um provedor de logon externo para a
identidade do ASP.NET Core
Adicione uma dependência no Microsoft.AspNetCore.Authentication.WsFederation ao projeto.
Adicionar o WS -Federation para o Configure método Startup.cs:
.AddWsFederation(options =>
{
// MetadataAddress represents the Active Directory instance used to authenticate users.
options.MetadataAddress = "https://<ADFS FQDN or AAD tenant>/FederationMetadata/2007-
06/FederationMetadata.xml";
// Wtrealm is the app's identifier in the Active Directory instance.

// For ADFS, use the relying party's identifier, its WS-Federation Passive protocol URL:
options.Wtrealm = "https://localhost:44307/";
// For AAD, use the App ID URI from the app registration's Properties blade:
options.Wtrealm = "https://wsfedsample.onmicrosoft.com/bf0e7e6d-056e-4e37-b9a6-2c36797b9f01";
});
services.AddMvc()
// ...

Faça logon com o WS -Federation
Navegue até o aplicativo e clique no login link no cabeçalho de navegação. Há uma opção para fazer logon com
WsFederation:
Com o ADFS como o provedor, o botão redireciona para uma página de entrada do AD FS:
Com o Azure Active Directory como o provedor, o botão redireciona para uma página de entrada do AAD:
Um bem-sucedida entrar para um novo usuário redireciona para a página de registro de usuário do aplicativo:
Use o WS-Federation sem identidade do ASP.NET Core

O middleware de WS -Federation pode ser usado sem identidade. Por exemplo:
{
services.AddAuthentication(sharedOptions =>
{
sharedOptions.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
sharedOptions.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
sharedOptions.DefaultChallengeScheme = WsFederationDefaults.AuthenticationScheme;
})
.AddWsFederation(options =>
{
options.Wtrealm = Configuration["wsfed:realm"];
options.MetadataAddress = Configuration["wsfed:metadata"];
})
.AddCookie();
}

{
// …
}
Confirmação de conta e de recuperação de senha
no ASP.NET Core
Ver esse arquivo PDF para o ASP.NET Core 1.1 e a versão 2.1.
Este tutorial mostra como criar um aplicativo ASP.NET Core com a redefinição de senha e de confirmação de
email. Este tutorial é não um tópico de início. Você deve estar familiarizado com:
ASP.NET Core
Autenticação
Entity Framework Core
Pré-requisitos
Criar um aplicativo web e o scaffolding de identidade

Visual Studio
CLI do .NET Core
No Visual Studio, crie um novo aplicativo Web projeto chamado WebPWrecover.
Selecione ASP.NET Core 2.1.
Mantenha o padrão autenticação definido como sem autenticação. Autenticação é adicionada na próxima
etapa.
Na próxima etapa:
Definir a página de layout ~/Pages/Shared/_Layout.cshtml
Selecione conta/registro
Criar um novo classe de contexto de dados
Siga as instruções em habilitar a autenticação:
Adicionar app.UseAuthentication(); para Startup.Configure
Adicionar <partial name="_LoginPartial" /> ao arquivo de layout.
Novo registro de usuário de teste

Execute o aplicativo, selecione a registrar vincular e registrar um usuário. Neste ponto, a validação apenas no
email é com o [EmailAddress] atributo. Depois de enviar o registro, você está conectado ao aplicativo.
Posteriormente no tutorial, o código é atualizado para que novos usuários não podem fazer logon até que o
email é validado.
Exibir o banco de dados de identidade
Visual Studio
CLI do .NET Core
Dos modo de exibição menu, selecione Pesquisador de objetos do SQL Server (SSOX).
Navegue até (localdb) MSSQLLocalDB (SQL Server 13). Clique duas vezes em dbo. AspNetUsers >
exibir dados:
Observe a tabela EmailConfirmed campo é False .

Você talvez queira usar este email novamente na próxima etapa quando o aplicativo envia um email de
confirmação. Clique com botão direito na linha e selecione excluir. Excluir o alias de email torna mais fácil nas
etapas a seguir.
Exigir email de confirmação

É uma prática recomendada para confirmar o email de um novo registro de usuário. Ajuda a confirmação para
verificar se eles não estiver representando alguém de email (ou seja, eles ainda não registrados com o email de
outra pessoa). Suponha que você tinha um fórum de discussão e quisesse impedir "yli@example.com"de
registrar-se como"nolivetto@contoso.com". Sem email de confirmação "nolivetto@contoso.com" pode receber
emails indesejados de seu aplicativo. Suponha que o usuário registrado acidentalmente como
"ylo@example.com" e ainda não tenha notado o erro de ortografia de "yli". Eles não seria capazes de usar a
recuperação de senha porque o aplicativo não tiver seu email correto. Email de confirmação oferece proteção
limitada contra bots. Email de confirmação não fornece proteção contra usuários mal-intencionados com muitas
contas de email.
Geralmente você deseja impedir que novos usuários incluam dados em seu site até que eles tenham um email
confirmado.
Atualização Areas/Identity/IdentityHostingStartup.cs para exigir um email confirmado:
public class IdentityHostingStartup : IHostingStartup
{
public void Configure(IWebHostBuilder builder)
{
builder.ConfigureServices((context, services) => {
services.AddDbContext<WebPWrecoverContext>(options =>
context.Configuration.GetConnectionString("WebPWrecoverContextConnection")));
services.AddDefaultIdentity<IdentityUser>(config =>
{
config.SignIn.RequireConfirmedEmail = true;
})
.AddEntityFrameworkStores<WebPWrecoverContext>();
});
}
}
config.SignIn.RequireConfirmedEmail = true; impede que os usuários registrados entrar até que o email seja
confirmado.
Configurar o provedor de email
Neste tutorial SendGrid é usado para enviar email. Você precisa de uma conta do SendGrid e uma chave para
enviar email. Você pode usar outros provedores de email. ASP.NET Core 2.x inclui System.Net.Mail , que permite
que você enviar um email de seu aplicativo. É recomendável que usar o SendGrid ou outro serviço de email para
enviar email. SMTP é difícil proteger e configurado corretamente.
Crie uma classe para buscar a chave de email seguro. Para este exemplo, crie
Services/AuthMessageSenderOptions.cs:
public class AuthMessageSenderOptions

{
public string SendGridUser { get; set; }
public string SendGridKey { get; set; }
}
Configurar segredos de usuário do SendGrid

Adicionar um único <UserSecretsId> de valor para o <PropertyGroup> elemento do arquivo de projeto:
<PropertyGroup>
<UserSecretsId>aspnet-WebPWrecover-1234</UserSecretsId>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="SendGrid" Version="9.9.0" />
</ItemGroup>
</Project>
Defina as SendGridUser e SendGridKey com o ferramenta secret manager. Por exemplo:
C:/WebAppl>dotnet user-secrets set SendGridUser RickAndMSFT

info: Successfully saved SendGridUser = RickAndMSFT to the secret store.
No Windows, o Secret Manager armazena os pares de chaves/valor em uma Secrets arquivo no
%APPDATA%/Microsoft/UserSecrets/<WebAppName-userSecretsId> directory.
O conteúdo a Secrets arquivo não são criptografadas. O Secrets arquivo é mostrado abaixo (o SendGridKey valor
tiver sido removido.)
{
"SendGridUser": "RickAndMSFT",
"SendGridKey": "<key removed>"
}
Para obter mais informações, consulte o padrão de opções e configuração.

Instalar o SendGrid
Este tutorial mostra como adicionar notificações de email por meio SendGrid, mas você pode enviar emails
usando SMTP e outros mecanismos.
Instalar o SendGrid pacote do NuGet:
Visual Studio
CLI do .NET Core
No Console do Gerenciador de pacotes, digite o seguinte comando:
Install-Package SendGrid
Ver inicie gratuitamente com o SendGrid para se registrar para uma conta gratuita do SendGrid.
Implementar IEmailSender
Para implementar IEmailSender , crie Services/EmailSender.cs com um código semelhante ao seguinte:
using Microsoft.AspNetCore.Identity.UI.Services;
using Microsoft.Extensions.Options;
using SendGrid;
using SendGrid.Helpers.Mail;
namespace WebPWrecover.Services
{
public class EmailSender : IEmailSender
{
public EmailSender(IOptions<AuthMessageSenderOptions> optionsAccessor)
{
Options = optionsAccessor.Value;
}
public AuthMessageSenderOptions Options { get; } //set only via Secret Manager
public Task SendEmailAsync(string email, string subject, string message)

{
return Execute(Options.SendGridKey, subject, message, email);
}
public Task Execute(string apiKey, string subject, string message, string email)
{
var client = new SendGridClient(apiKey);
var msg = new SendGridMessage()
{
From = new EmailAddress("Joe@contoso.com", "Joe Smith"),
Subject = subject,
PlainTextContent = message,
HtmlContent = message
};
msg.AddTo(new EmailAddress(email));
// Disable click tracking.

// See https://sendgrid.com/docs/User_Guide/Settings/tracking.html
msg.SetClickTracking(false, false);
return client.SendEmailAsync(msg);
}
}
}
Configurar a inicialização para dar suporte a email

Adicione o seguinte código para o ConfigureServices método na Startup.cs arquivo:
Adicionar EmailSender como um serviço singleton.
Registrar o AuthMessageSenderOptions instância de configuração.
{
{
});
// requires
// using WebPWrecover.Services;
services.Configure<AuthMessageSenderOptions>(Configuration);
}
Habilitar a recuperação de confirmação e a senha da conta

O modelo tem o código para recuperação de confirmação e a senha da conta. Localizar o OnPostAsync método
no Areas/Identity/Pages/Account/Register.cshtml.cs.
Evitar que usuários recém-registrados seja registrada automaticamente comentando a linha a seguir:
O método complete é mostrado com a linha alterada realçada:

{
{
var user = new IdentityUser { UserName = Input.Email, Email = Input.Email };
{

pageHandler: null,

here</a>.");
// await _signInManager.SignInAsync(user, isPersistent: false);

}
{
}
}

return Page();
}
Registrar, confirme se o email e redefinição de senha

Executar o aplicativo web e testar o fluxo de recuperação de senha e confirmação de conta.
Execute o aplicativo e registrar um novo usuário
Verifique seu email para o link de confirmação de conta. Ver depurar email se você não receber o email.
Clique no link para confirmar seu email.
Faça logon com seu email e senha.
Faça logoff.
Exibir a página Gerenciar
Selecione seu nome de usuário no navegador:
Talvez seja necessário expandir a barra de navegação para ver o nome de usuário.
A página Gerenciar é exibida com o perfil guia selecionada. O Email mostra uma caixa de seleção que indica o
email foi confirmada.
Teste a redefinição de senha
Se você estiver conectado, selecione Logout.
Selecione o login link e selecione o esqueceu sua senha? link.
Insira o email usado para registrar a conta.
Um email com um link para redefinir sua senha é enviado. Verifique seu email e clique no link para redefinir
sua senha. Depois que sua senha foi redefinida com êxito, você pode entrar com seu email e a nova senha.
Depurar o email
Se você não é possível obter o trabalho de email:
Defina um ponto de interrupção no EmailSender.Execute para verificar SendGridClient.SendEmailAsync é
chamado.
Criar uma aplicativo de console para enviar email usando um código semelhante ao EmailSender.Execute .
Examine os atividade de Email página.
Verifique sua pasta de spam.
Tente outro alias de email em outro provedor de email (Microsoft, Yahoo, Gmail, etc.)
Tente enviar para contas de email diferente.
Uma prática recomendada de segurança é não use segredos de produção em desenvolvimento e teste. Se
você publicar o aplicativo no Azure, você pode definir os segredos do SendGrid como configurações de aplicativo
no portal do aplicativo Web do Azure. Configurar o sistema de configuração para ler as chaves de variáveis de
ambiente.
Combine as contas de logon social e local

Para concluir esta seção, você deve primeiro habilitar um provedor de autenticação externa. Ver Facebook,
Google e a autenticação de provedor externo.
Você pode combinar as contas locais e sociais clicando no link seu email. Na sequência a seguir,
"RickAndMSFT@gmail.com" é criado como um logon local; no entanto, você pode criar a conta como um logon
social primeiro e adicionar um logon local.
Clique no gerenciar link. Observe externo 0 (logons sociais) associado a essa conta.
Clique no link para outro serviço de logon e aceitar as solicitações do aplicativo. Na imagem a seguir, o Facebook
é o provedor de autenticação externa:
As duas contas foram combinadas. É possível fazer logon com qualquer uma das contas. Convém que os
usuários adicionem contas locais no caso de seu serviço de autenticação de logon social está inoperante ou, mais
provavelmente eles tiver perdido o acesso à sua conta social.
Habilitar confirmação de conta depois que um site tem usuários

Habilitando a confirmação de conta em um site com usuários bloqueia todos os usuários existentes. Os usuários
existentes estão bloqueados porque suas contas não são confirmadas. Para contornar o bloqueio de usuário
existente, use uma das seguintes abordagens:
Atualize o banco de dados para marcar todos os usuários existentes como sendo confirmada.
Confirme se os usuários existentes. Por exemplo, envio em lote-emails com links de confirmação.
Habilitar a geração de código QR TOTP para
aplicativos de autenticador no ASP.NET Core
Códigos QR exige o ASP.NET Core 2.0 ou posterior.

ASP.NET Core é fornecido com suporte para aplicativos de autenticador para autenticação individual. Dois
aplicativos de autenticador 2FA (autenticação) fator, usando uma baseada em tempo avulso senha algoritmo
TOTP (), são o setor de abordagem 2fa recomendado. 2FA usar TOTP é preferencial para SMS 2FA. Um aplicativo
autenticador fornece um código de 6 a 8 dígitos que os usuários devem inserir depois de confirmar seu nome de
usuário e senha. Normalmente, um aplicativo autenticador é instalado em um Smartphone.
Os modelos de aplicativo web ASP.NET Core autenticadores de suporte, mas não fornecem suporte para a
geração de QRCode. Geradores de QRCode facilitam a configuração do 2FA. Este documento o orientará durante
a adição código QR geração para a página de configuração 2FA.
Adicionar códigos QR para a página de configuração 2FA

Usam estas instruções qrcode.js do https://davidshimjs.github.io/qrcodejs/ repositório.
Baixe o biblioteca de javascript qrcode.js para o wwwroot\lib pasta em seu projeto.
Siga as instruções em identidade de Scaffold para gerar
/Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml.
Na /Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml, localize o Scripts seção no final do
arquivo:
Na Pages/Account/Manage/EnableAuthenticator.cshtml (páginas do Razor) ou
Views/Manage/EnableAuthenticator.cshtml (MVC ), localize o Scripts seção no final do arquivo:
@section Scripts {
@await Html.PartialAsync("_ValidationScriptsPartial")
}
Atualizar o Scripts seção para adicionar uma referência para o qrcodejs biblioteca que você adicionou e
uma chamada para gerar o código QR. Ele deve ser da seguinte maneira:
@section Scripts {
@await Html.PartialAsync("_ValidationScriptsPartial")
<script type="text/javascript" src="~/lib/qrcode.js"></script>

<script type="text/javascript">
new QRCode(document.getElementById("qrCode"),
{
text: "@Html.Raw(Model.AuthenticatorUri)",
width: 150,
height: 150
});
</script>
}
Exclua o parágrafo que links para essas instruções.

Executar seu aplicativo e certifique-se de que você pode digitalizar o código QR e validar o código que comprova
o autenticador.
Alterar o nome do site em que o código QR

O nome do site em que o código QR é obtido do nome do projeto que você escolher ao criar inicialmente o seu
projeto. Você pode alterá-lo procurando os GenerateQrCodeUri(string email, string unformattedKey) método na
/Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml.
O nome do site em que o código QR é obtido do nome do projeto que você escolher ao criar inicialmente o seu
projeto. Você pode alterá-lo procurando a GenerateQrCodeUri(string email, string unformattedKey) método na
Pages/Account/Manage/EnableAuthenticator.cshtml.cs arquivo (páginas do Razor) ou o
Controllers/ManageController.cs arquivo (MVC ).
O código padrão do modelo será semelhante ao seguinte:
private string GenerateQrCodeUri(string email, string unformattedKey)

{
return string.Format(
AuthenicatorUriFormat,
_urlEncoder.Encode("Razor Pages"),
_urlEncoder.Encode(email),
unformattedKey);
}
O segundo parâmetro na chamada para string.Format é o nome do site, obtido do nome da solução. Ele pode
ser alterado para qualquer valor, mas ele sempre deve ser codificado por URL.
Usando uma biblioteca diferente do código QR

Você pode substituir a biblioteca de código QR com sua biblioteca preferencial. O HTML não contém um qrCode
fornece de sua biblioteca de elemento no qual você pode colocar um código QR por qualquer mecanismo.
A URL formatada corretamente para o código QR está disponível na:
AuthenticatorUri propriedade do modelo.
data-url propriedade no qrCodeData elemento.
TOTP cliente e servidor distorção de tempo

Autenticação de TOTP (senha de uso único baseados em tempo) depende do dispositivo o servidor e o
autenticador, tendo a hora correta. Tokens duram por 30 segundos. Se os logons de 2FA TOTP estiverem
falhando, verifique se a hora do servidor é precisos e preferencialmente sincronizado a um serviço NTP preciso.
Autenticação de dois fatores com SMS no ASP.NET
Core
Por Rick Anderson e suíço desenvolvedores
WARNING
Dois aplicativos de autenticador 2FA (autenticação) fator, usando uma baseada em tempo avulso senha algoritmo TOTP (),
são o setor de abordagem 2fa recomendado. 2FA usar TOTP é preferencial para SMS 2FA. Para obter mais informações,
consulte geração de código de QR habilitar TOTP para aplicativos de autenticador no ASP.NET Core para ASP.NET Core 2.0 e
versões posteriores.
Este tutorial mostra como configurar a autenticação de dois fatores (2FA) usando o SMS. As instruções são
fornecidas para twilio e ASPSMS, mas você pode usar qualquer outro provedor SMS. Recomendamos que você
conclua confirmação de conta e recuperação de senha antes de iniciar este tutorial.
Exibir ou baixar o código de exemplo. Como baixar.
Criar um projeto ASP.NET Core

Criar um novo aplicativo web de ASP.NET Core chamado Web2FA com contas de usuário individuais. Siga as
instruções em impor o SSL em um aplicativo ASP.NET Core para configurar e exigir SSL.
Criar uma conta do SMS
Criar uma conta SMS, por exemplo, no twilio ou ASPSMS. Registre as credenciais de autenticação (para o twilio:
accountSid e authToken para ASPSMS: Userkey e senha).
Descobrir as credenciais do provedor de SMS
Twilio: da guia Painel de sua conta do Twilio, copie o Account SID e token de autenticação.
ASPSMS: em suas configurações de conta, navegue até Userkey e copie-o junto com seu senha.
Posteriormente, armazenaremos esses valores com a ferramenta secret manager nas chaves
SMSAccountIdentification e SMSAccountPassword .
Especificando SenderID / originador

Twilio: na guia números, copie seu Twilio número de telefone.
ASPSMS: dentro do Menu originadores de desbloqueio, desbloquear originadores de um ou mais ou escolha um
originador alfanumérico (não é suportado por todas as redes).
Posteriormente, armazenaremos esse valor com a ferramenta secret manager na chave do SMSAccountFrom .
Forneça credenciais para o serviço SMS
Vamos usar o padrão de opções para acessar as configurações de conta e chave de usuário.
Crie uma classe para buscar a chave segura do SMS. Para este exemplo, o SMSoptions classe é criada na
Services/SMSoptions.cs arquivo.
namespace Web2FA.Services
{
public class SMSoptions
{
public string SMSAccountIdentification { get; set; }
public string SMSAccountPassword { get; set; }
public string SMSAccountFrom { get; set; }
}
}
Defina as SMSAccountIdentification , SMSAccountPassword e SMSAccountFrom com o ferramenta secret manager. Por

exemplo:
C:/Web2FA/src/WebApp1>dotnet user-secrets set SMSAccountIdentification 12345

info: Successfully saved SMSAccountIdentification = 12345 to the secret store.
Adicione o pacote NuGet do provedor de SMS. Do Manager Console (PMC ) execute:

Twilio: Install-Package Twilio
ASPSMS: Install-Package ASPSMS
Adicione código a Services/MessageServices.cs arquivo para habilitar o SMS. Use o Twilio ou seção ASPSMS:
Twilio: [!code-csharp]
ASPSMS: [!code-csharp]
Configurar a inicialização para usar SMSoptions
Adicione SMSoptions ao contêiner de serviço na ConfigureServices método na Startup.cs:

services.Configure<SMSoptions>(Configuration);
}
Habilitar a autenticação de dois fatores

Abra o Views/Manage/Index.cshtml arquivo de exibição do Razor e remova o comentário caracteres (de modo
que nenhuma marcação é commnted out).
Faça logon com a autenticação de dois fatores

Execute o aplicativo e registrar um novo usuário
Toque em seu nome de usuário que ativa o Index método de ação no controlador de gerenciar. Em seguida,
toque no número de telefone adicionar link.
Adicionar um número de telefone que receberá o código de verificação e toque enviar código de verificação.
Você receberá uma mensagem de texto com o código de verificação. Insira-o e toque em enviar
Se você não receber uma mensagem de texto, consulte a página de registro do twilio.
O modo de gerenciar mostra que o número de telefone foi adicionado com êxito.
Toque habilitar para habilitar a autenticação de dois fatores.
Autenticação de dois fatores do teste

Faça logoff.
Iniciar sessão.
A conta de usuário tiver habilitado a autenticação de dois fatores, portanto, você precisa fornecer o
segundo fator de autenticação. Neste tutorial, você habilitou a verificação por telefone. Os modelos internos
permitem que você configure o email como o segundo fator. Você pode configurar os fatores adicionais de
segundo para autenticação, como códigos QR. Toque enviar.
Insira o código que você pode obter na mensagem SMS.

Clicar na lembrar deste navegador caixa de seleção serão isentos da necessidade de usar 2FA para fazer
logon usando o mesmo dispositivo e o navegador. Habilitar a 2FA e clicando em lembrar deste
navegador lhe fornecerá 2FA forte proteção contra usuários mal-intencionados que tentam acessar sua
conta, desde que não tiverem acesso ao seu dispositivo. Você pode fazer isso em qualquer dispositivo
privado que você usa regularmente. Definindo lembrar deste navegador, você obtém a segurança
adicional de 2FA de dispositivos que você não usa regularmente, e você obtém a conveniência em não ter
que passar por 2FA em seus próprios dispositivos.
Bloqueio de conta para proteção contra ataques de força bruta
Bloqueio de conta é recomendado com 2FA. Depois que um usuário faz logon por meio de uma conta local ou
social, cada tentativa com falha no 2FA é armazenada. Se as tentativas de acesso com falha máximo for atingido, o
usuário está bloqueado (padrão: bloqueio de 5 minutos após 5 falhas em tentativas de acesso). Uma autenticação
bem-sucedida redefine a contagem de tentativas de acesso com falha e redefine o relógio. O máximo falhas em
tentativas de acesso e tempo de bloqueio pode ser definido com MaxFailedAccessAttempts e
DefaultLockoutTimeSpan. O exemplo a seguir configura o bloqueio de conta por 10 minutos após 10 tentativas
de acesso:

{
services.AddMvc();
{
});

services.Configure<SMSoptions>(Configuration);
}
Confirme PasswordSignInAsync define lockoutOnFailure para true :

var result = await _signInManager.PasswordSignInAsync(
Input.Email, Input.Password, Input.RememberMe, lockoutOnFailure: true);
Usar autenticação de cookie sem o ASP.NET Core
Identity
Por Rick Anderson e Luke Latham

Como você viu nos tópicos anteriores de autenticação, ASP.NET Core Identity é um provedor de autenticação
completa e a versão completa para criar e manter os logons. No entanto, você talvez queira usar sua própria
lógica de autenticação personalizada com autenticação baseada em cookie às vezes. Você pode usar a
autenticação baseada em cookie como um provedor de autenticação autônomo sem o ASP.NET Core Identity.
Para fins de demonstração no aplicativo de exemplo, a conta de usuário para o usuário hipotético, Maria
Rodriguez, é codificados no aplicativo. Use o nome de usuário de Email "maria.rodriguez@contoso.com" e
nenhuma senha para a entrada do usuário. O usuário é autenticado na AuthenticateUser método na
Pages/Account/Login.cshtml.cs arquivo. Em um exemplo do mundo real, o usuário deve ser autenticado em
relação a um banco de dados.
Para obter informações sobre a autenticação baseada em cookie Migrando do ASP.NET Core 1.x para 2.0,
consulte migrar autenticação e identidade para o tópico do ASP.NET Core 2.0 (autenticação baseada em Cookie).
Para usar a identidade do ASP.NET Core, consulte o Introdução à identidade tópico.
Configuração
ASP.NET Core 2.x
ASP.NET Core 1.x
Se o aplicativo não usa o metapacote do Microsoft, criar uma referência de pacote no arquivo de projeto para o
Microsoft.AspNetCore.Authentication.Cookies pacote (versão 2.1.0 ou mais tarde).
No ConfigureServices método, crie o serviço de Middleware de autenticação com o AddAuthentication e
AddCookie métodos:
services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
.AddCookie();
AuthenticationScheme passado para AddAuthentication define o esquema de autenticação padrão para o

aplicativo. AuthenticationScheme é útil quando há várias instâncias de autenticação de cookie e você deseja
autorizar com um esquema específico. Definindo o AuthenticationScheme para
CookieAuthenticationDefaults.AuthenticationScheme fornece um valor de "Cookies" para o esquema. Você pode
fornecer qualquer valor de cadeia de caracteres que diferencia o esquema.
Esquema de autenticação do aplicativo é diferente do esquema de autenticação de cookie do aplicativo. Quando
um esquema de autenticação de cookie não é fornecido para AddCookie, ele usa
CookieAuthenticationDefaults.AuthenticationScheme ("Cookies").
No Configure método, use o UseAuthentication método para invocar o Middleware de autenticação define o
HttpContext.User propriedade. Chame o UseAuthentication método antes de chamar UseMvcWithDefaultRoute ou
UseMvc :
Opções de AddCookie
O CookieAuthenticationOptions classe é usada para configurar as opções de provedor de autenticação.
OPÇÃO DESCRIÇÃO
AccessDeniedPath Fornece o caminho para fornecer a uma 302 não encontrado

(redirecionamento de URL) quando disparado por
HttpContext.ForbidAsync . O valor padrão é
/Account/AccessDenied .
ClaimsIssuer O emissor a ser usado para o emissor propriedade em

quaisquer declarações criadas pelo serviço de autenticação de
cookie.
Cookie.Domain O nome de domínio no qual o cookie é atendido. Por padrão,

isso é o nome do host da solicitação. O navegador envia
apenas o cookie em solicitações para um nome de host
correspondente. Talvez você queira ajustar isso para ter
cookies disponíveis para qualquer host no seu domínio. Por
exemplo, definir o domínio do cookie .contoso.com
disponibiliza para contoso.com , www.contoso.com , e
staging.www.contoso.com .
Cookie.Expiration Obtém ou define o tempo de vida de um cookie. Atualmente,

essa opção não funciona e se tornará obsoleta no ASP.NET
Core 2.1 +. Use o ExpireTimeSpan opção para definir a
expiração do cookie. Para obter mais informações, consulte
esclarecer o comportamento de
CookieAuthenticationOptions.Cookie.Expiration.
Cookie.HttpOnly Um sinalizador que indica se o cookie deve ser acessível

somente aos servidores. A alteração desse valor para false
permite que os scripts do lado do cliente para acessar o
cookie e pode abrir seu aplicativo ao roubo de cookie deve ter
de seu aplicativo uma Cross-site scripting (XSS)
vulnerabilidade. O valor padrão é true .
Cookie.Name Define o nome do cookie.
Cookie.Path Usado para isolar aplicativos em execução no mesmo nome

de host. Se você tiver um aplicativo em execução no /app1 e
para restringir os cookies para o aplicativo, defina a
CookiePath propriedade /app1 . Ao fazer isso, o cookie só
está disponível em solicitações para /app1 e qualquer
aplicativo abaixo dela.
OPÇÃO DESCRIÇÃO
Cookie.SameSite Indica se o navegador deve permitir que o cookie a ser

anexado a somente solicitações do mesmo site (
SameSiteMode.Strict ) ou solicitações entre sites usando
métodos seguros de HTTP e as solicitações do mesmo site (
SameSiteMode.Lax ). Quando definido como
SameSiteMode.None , o valor do cabeçalho de cookie não
está definido. Observe que Middleware do Cookie política
pode substituir o valor fornecido por você. Para dar suporte à
autenticação OAuth, o valor padrão é SameSiteMode.Lax .
Para obter mais informações, consulte autenticação OAuth
interrompida devido à política de cookies SameSite.
Cookie.SecurePolicy Um sinalizador que indica se o cookie criado deve ser limitado

a HTTPS ( CookieSecurePolicy.Always ), HTTP ou HTTPS (
CookieSecurePolicy.None ), ou o mesmo protocolo usado
na solicitação ( CookieSecurePolicy.SameAsRequest ). O
valor padrão é CookieSecurePolicy.SameAsRequest .
DataProtectionProvider Define o DataProtectionProvider que é usado para criar o

padrão TicketDataFormat . Se o TicketDataFormat
propriedade for definida, o DataProtectionProvider opção
não é usada. Se não for fornecido, o provedor de proteção de
dados do aplicativo padrão é usado.
Eventos O manipulador chama métodos no provedor que fornecem o

controle de aplicativo em determinados pontos de
processamento. Se Events não são fornecidas, uma
instância padrão é fornecida que não faz nada quando os
métodos são chamados.
EventsType Usado como o tipo de serviço para obter o Events instância

em vez da propriedade.
ExpireTimeSpan O TimeSpan depois que o tíquete de autenticação

armazenado dentro do cookie expira. ExpireTimeSpan é
adicionado à hora atual para criar o tempo de expiração para
o tíquete. O ExpiredTimeSpan valor sempre entra no
AuthTicket criptografado verificado pelo servidor. Isso
também pode acontecer na Set-Cookie cabeçalho, mas
somente se IsPersistent está definido. Para definir
IsPersistent à true , configure o
AuthenticationProperties passado para SignInAsync . O
valor padrão de ExpireTimeSpan é de 14 dias.
LoginPath Fornece o caminho para fornecer a uma 302 não encontrado

(redirecionamento de URL) quando disparado por
HttpContext.ChallengeAsync . A URL atual que gerou o
401 é adicionada para o LoginPath como um parâmetro de
cadeia de caracteres de consulta nomeado pelo
ReturnUrlParameter . Uma vez uma solicitação para o
LoginPath concede uma nova entrada identidade, o
ReturnUrlParameter valor é usado para redirecionar o
navegador para a URL que causou o código de status não
autorizado original. O valor padrão é /Account/Login .
OPÇÃO DESCRIÇÃO
LogoutPath Se o LogoutPath é fornecido para o manipulador, em

seguida, redireciona uma solicitação para o caminho com base
no valor da ReturnUrlParameter . O valor padrão é
/Account/Logout .
ReturnUrlParameter Determina o nome do parâmetro de cadeia de consulta que é

acrescentado pelo manipulador para uma resposta 302 do
encontrado (redirecionamento de URL).
ReturnUrlParameter é usado quando uma solicitação chega
na LoginPath ou LogoutPath para retornar o navegador a
URL original depois que a ação de logon ou logoff é
executada. O valor padrão é ReturnUrl .
SessionStore Um contêiner opcional usado para armazenar a identidade

entre solicitações. Quando usado, somente um identificador
de sessão é enviado ao cliente. SessionStore pode ser
usado para atenuar problemas potenciais com identidades
grandes.
slidingExpiration Um sinalizador que indica se um novo cookie com um tempo

de expiração atualizados deve ser emitido dinamicamente.
Isso pode acontecer em qualquer solicitação em que o
período de expiração do cookie atual mais de 50% expirou. A
nova data de expiração é movida para frente até ser a data
atual mais o ExpireTimespan . Uma tempo de expiração do
cookie absoluto pode ser definida usando o
AuthenticationProperties classe ao chamar
SignInAsync . Um tempo de expiração absoluto pode
melhorar a segurança do seu aplicativo, limitando a
quantidade de tempo que o cookie de autenticação é válido.
O valor padrão é true .
TicketDataFormat O TicketDataFormat é usado para proteger e desproteger a

identidade e outras propriedades que são armazenadas no
valor do cookie. Se não for fornecido, um TicketDataFormat
é criado usando o DataProtectionProvider.
Validar Método que verifica que as opções são válidas.
Definir CookieAuthenticationOptions na configuração do serviço para autenticação no ConfigureServices método:
.AddCookie(options =>
{
...
});
Cookie de Middleware de política

Middleware do cookie política habilita recursos de política de cookie em um aplicativo. Adicionar o middleware ao
pipeline de processamento de aplicativos é a ordem de minúsculas; ela afeta apenas os componentes registrados
depois no pipeline.
app.UseCookiePolicy(cookiePolicyOptions);
O CookiePolicyOptions fornecido para o Cookie de Middleware de política permitem controlar características

globais do processamento de cookie e gancho em manipuladores de processamento do cookie quando os cookies
são acrescentados ou excluídos.
HttpOnly Afeta se os cookies devem ser HttpOnly, que é um sinalizador

que indica se o cookie deve ser acessível somente aos
servidores. O valor padrão é HttpOnlyPolicy.None .
MinimumSameSitePolicy Afeta o atributo de mesmo site do cookie (veja abaixo). O

valor padrão é SameSiteMode.Lax . Essa opção está
disponível para o ASP.NET Core 2.0 +.
OnAppendCookie Chamado quando um cookie será acrescentado.
OnDeleteCookie Chamado quando um cookie é excluído.
Proteger Afeta se os cookies devem ser seguro. O valor padrão é

CookieSecurePolicy.None .
MinimumSameSitePolicy (ASP.NET Core 2.0 ou posterior somente)

O padrão MinimumSameSitePolicy valor é SameSiteMode.Lax para permitir a autenticação OAuth2. Estritamente
impor uma política do mesmo site do SameSiteMode.Strict , defina o MinimumSameSitePolicy . Embora essa
configuração interrompe OAuth2 e outras esquemas de autenticação entre origens, ela eleva o nível de segurança
do cookie para outros tipos de aplicativos que não dependem de processamento de solicitação entre origens.
var cookiePolicyOptions = new CookiePolicyOptions

{
MinimumSameSitePolicy = SameSiteMode.Strict,
};
A configuração de Middleware de política de Cookie para MinimumSameSitePolicy pode afetar sua configuração de
Cookie.SameSite em CookieAuthenticationOptions configurações de acordo com a matriz a seguir.
CONFIGURAÇÃO DE COOKIE.SAMESITE
MINIMUMSAMESITEPOLICY COOKIE.SAMESITE RESULTANTE
SameSiteMode.None SameSiteMode.None SameSiteMode.None

SameSiteMode.Lax SameSiteMode.Lax
SameSiteMode.Strict SameSiteMode.Strict
SameSiteMode.Lax SameSiteMode.None SameSiteMode.Lax

SameSiteMode.Lax SameSiteMode.Lax
SameSiteMode.Strict SameSiteMode.None SameSiteMode.Strict

SameSiteMode.Lax SameSiteMode.Strict
Criar um cookie de autenticação

Para criar um cookie contendo informações de usuário, você precisa construir uma ClaimsPrincipal. As
informações do usuário são serializadas e armazenadas no cookie.
ASP.NET Core 2.x
ASP.NET Core 1.x
Criar uma ClaimsIdentity com qualquer necessárias declaraçãos e chame SignInAsync para a entrada do usuário:
var claims = new List<Claim>

{
new Claim(ClaimTypes.Name, user.Email),
new Claim("FullName", user.FullName),
new Claim(ClaimTypes.Role, "Administrator"),
};
var claimsIdentity = new ClaimsIdentity(

claims, CookieAuthenticationDefaults.AuthenticationScheme);
var authProperties = new AuthenticationProperties

{
//AllowRefresh = <bool>,
// Refreshing the authentication session should be allowed.
//ExpiresUtc = DateTimeOffset.UtcNow.AddMinutes(10),
// The time at which the authentication ticket expires. A
// value set here overrides the ExpireTimeSpan option of
// CookieAuthenticationOptions set with AddCookie.
//IsPersistent = true,
// Whether the authentication session is persisted across
// multiple requests. Required when setting the
// ExpireTimeSpan option of CookieAuthenticationOptions
// set with AddCookie. Also required when setting
// ExpiresUtc.
//IssuedUtc = <DateTimeOffset>,
// The time at which the authentication ticket was issued.
//RedirectUri = <string>
// The full path or absolute URI to be used as an http
// redirect response value.
};
await HttpContext.SignInAsync(
CookieAuthenticationDefaults.AuthenticationScheme,
new ClaimsPrincipal(claimsIdentity),
authProperties);
SignInAsync cria um cookie criptografado e o adiciona à resposta atual. Se você não especificar um
AuthenticationScheme , o esquema padrão é usado.
Nos bastidores, a criptografia usada é ASP.NET Core proteção de dados sistema. Se você estiver hospedando o
aplicativo em várias máquinas, balanceamento de carga entre aplicativos ou usar uma web farm, você deve
configurar a proteção de dados para usar o mesmo anel de chave e o identificador do aplicativo.
Sair
ASP.NET Core 2.x
ASP.NET Core 1.x
Para desconectar o usuário atual e excluir seus cookies, chame SignOutAsync:
await HttpContext.SignOutAsync(
CookieAuthenticationDefaults.AuthenticationScheme);
Se você não estiver usando CookieAuthenticationDefaults.AuthenticationScheme (ou "Cookies") como o esquema

(por exemplo, "ContosoCookie"), forneça o esquema usado ao configurar o provedor de autenticação. Caso
contrário, o esquema padrão é usado.
Reagir às alterações de back-end

Depois que um cookie é criado, ele se torna a única fonte de identidade. Mesmo se você desabilitar um usuário
em seus sistemas de back-end, o sistema de autenticação de cookie não tem conhecimento disso, e um usuário
permaneça conectado enquanto seu cookie é válido.
O ValidatePrincipal evento no ASP.NET Core 2.x ou o ValidateAsync método no ASP.NET Core 1.x pode ser
usado para interceptar e substituir a validação da identidade do cookie. Essa abordagem minimiza o risco de
usuários revogados acessando o aplicativo.
Uma abordagem de validação de cookie baseia-se em manter o controle de quando o banco de dados do usuário
foi alterado. Se o banco de dados não foi alterado desde que o cookie do usuário foi emitido, não é necessário
para autenticar o usuário novamente se o cookie ainda é válido. Para implementar este cenário, o banco de dados,
que é implementado no IUserRepository para este exemplo armazena um LastChanged valor. Quando nenhum
usuário é atualizado no banco de dados, o LastChanged valor é definido como a hora atual.
Para invalidar um cookie, quando as alterações de banco de dados com base nas LastChanged o valor, criar o
cookie com um LastChanged contendo atual de declaração LastChanged valor do banco de dados:
var claims = new List<Claim>

{
new Claim(ClaimTypes.Name, user.Email),
new Claim("LastChanged", {Database Value})
};
var claimsIdentity = new ClaimsIdentity(

claims,
new ClaimsPrincipal(claimsIdentity));
ASP.NET Core 2.x

ASP.NET Core 1.x
Para implementar uma substituição para o ValidatePrincipal eventos, escreva um método com a assinatura a
seguir em uma classe que você deriva CookieAuthenticationEvents:
ValidatePrincipal(CookieValidatePrincipalContext)
Um exemplo é semelhante ao seguinte:

using System.Linq;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
public class CustomCookieAuthenticationEvents : CookieAuthenticationEvents

{
private readonly IUserRepository _userRepository;
public CustomCookieAuthenticationEvents(IUserRepository userRepository)

{
// Get the database from registered DI services.
_userRepository = userRepository;
}
public override async Task ValidatePrincipal(CookieValidatePrincipalContext context)

{
var userPrincipal = context.Principal;
// Look for the LastChanged claim.

var lastChanged = (from c in userPrincipal.Claims
where c.Type == "LastChanged"
select c.Value).FirstOrDefault();
if (string.IsNullOrEmpty(lastChanged) ||
!_userRepository.ValidateLastChanged(lastChanged))
{
context.RejectPrincipal();
await context.HttpContext.SignOutAsync(
}
}
}
Registrar a instância de eventos durante o registro do serviço de cookie no ConfigureServices método. Fornecer
um registro de serviço com escopo para sua CustomCookieAuthenticationEvents classe:
{
options.EventsType = typeof(CustomCookieAuthenticationEvents);
});
services.AddScoped<CustomCookieAuthenticationEvents>();
Considere uma situação em que o nome do usuário é atualizado — uma decisão que não afeta a segurança de
qualquer forma. Se você quiser atualizar forma não destrutiva a entidade de usuário, chame
context.ReplacePrincipal e defina o context.ShouldRenew propriedade true .
WARNING
A abordagem descrita aqui é disparada em cada solicitação. Isso pode resultar em uma penalidade de desempenho grande
para o aplicativo.
Cookies persistentes
Talvez você queira que o cookie para persistir entre as sessões do navegador. Essa persistência deve ser habilitada
apenas com o consentimento do usuário explícito com um checkbox "Lembrar-Me" no logon ou um mecanismo
semelhante.
O trecho de código a seguir cria uma identidade e o cookie correspondente que sobrevive a por meio de
fechamentos de navegador. Quaisquer configurações de expiração deslizante configuradas anteriormente são
consideradas. Se o cookie expirar enquanto o navegador é fechado, o navegador limpa o cookie depois que ele
seja reiniciado.
ASP.NET Core 2.x
ASP.NET Core 1.x
new AuthenticationProperties
{
IsPersistent = true
});
O AuthenticationProperties classe reside no Microsoft.AspNetCore.Authentication namespace.
Expiração do cookie absoluto

Você pode definir um tempo de expiração absoluto com ExpiresUtc . Você também deve definir IsPersistent ;
caso contrário, ExpiresUtc será ignorado e um cookie de sessão único é criado. Quando ExpiresUtc é definida
em SignInAsync , ele substitui o valor da ExpireTimeSpan opção de CookieAuthenticationOptions , se definido.
O trecho de código a seguir cria uma identidade e o cookie correspondente que dura por 20 minutos. Isso ignora
as configurações de expiração deslizante configuradas anteriormente.
ASP.NET Core 2.x
ASP.NET Core 1.x
new AuthenticationProperties
{
IsPersistent = true,
ExpiresUtc = DateTime.UtcNow.AddMinutes(20)
});
Recursos adicionais
As alterações do AUTH 2.0 / migração comunicado
Autorizar com um esquema específico no ASP.NET Core
Autorização baseada em declarações no núcleo do ASP.NET
Verificações de função baseado em políticas
Azure Active Directory com o ASP.NET Core
Exemplos do Azure Active Directory V1

Os exemplos a seguir mostram como integrar o Azure Active Directory V1, permitindo que os usuários entrem
com uma conta corporativa ou de estudante:
Integrando o Azure AD em um aplicativo Web ASP.NET Core
Chamando uma API Web ASP.NET Core em um aplicativo do WPF usando o Azure AD
Chamando uma API Web em um aplicativo Web ASP.NET Core usando o Azure AD
Exemplos do Azure Active Directory V2

Os exemplos a seguir mostram como integrar o Azure Active Directory V2, permitindo que os usuários entrem
com uma conta corporativa ou de estudante ou com uma conta pessoal da Microsoft (antiga conta Live):
Integrando o Azure Active Directory V2 em um aplicativo Web ASP.NET Core 2.0:
Consulte este vídeo associado
Chamando uma API Web ASP.NET Core 2.0 em um aplicativo do WPF usando o Azure Active Directory
V2:
Consulte este vídeo associado
Exemplo do Azure Active Directory B2C

Este exemplo mostra como integrar o Azure Active Directory B2C, permitindo que os usuários entrem com contas
sociais (como Facebook, Google...)
Um aplicativo API Web ASP.NET Core com o Azure AD B2C
Autenticação de nuvem com o Azure Active
Directory B2C no ASP.NET Core
Por Cam Soper

Azure Active Directory B2C do diretório (Azure AD B2C ) é uma solução de gerenciamento de identidade de
nuvem para aplicativos web e móveis. O serviço fornece autenticação para aplicativos hospedados na nuvem e
locais. Tipos de autenticação incluem contas individuais, contas de rede social e contas corporativas de federado.
Além disso, o Azure AD B2C pode fornecer a autenticação multifator com configuração mínima.
TIP
Azure Active Directory (Azure AD) e o Azure AD B2C são ofertas de produtos separados. Um locatário do AD do Azure
representa uma organização, enquanto que um locatário do Azure AD B2C representa uma coleção de identidades a serem
usados com aplicativos de terceira parte confiável. Para obter mais informações, consulte do Azure AD B2C: perguntas
frequentes (FAQ).
Neste tutorial, saiba como:

Criar um locatário do Azure Active Directory B2C
Registrar um aplicativo no Azure B2C do AD
Usar o Visual Studio para criar um aplicativo web do ASP.NET Core configurado para usar o locatário do Azure
AD B2C para autenticação
Configurar políticas para controlar o comportamento do locatário do Azure AD B2C
Pré-requisitos
A seguir é necessários para este passo a passo:
Assinatura do Microsoft Azure
Visual Studio 2017 (qualquer edição)
Criar o locatário do Azure Active Directory B2C

Criar um locatário do Azure Active Directory B2C conforme descrito na documentação do. Quando solicitado,
associar o locatário com uma assinatura do Azure é opcional para este tutorial.
Registrar o aplicativo no Azure B2C do AD

No locatário do Azure AD B2C recém-criado, registre seu aplicativo usando as etapas na documentação do sob o
registrar um aplicativo web seção. Parar na criar um segredo do cliente de aplicativo web seção. Um
segredo do cliente não é necessário para este tutorial.
Use os seguintes valores:
CONFIGURAÇÃO VALOR OBSERVAÇÕES

Nome <Nome do aplicativo> Insira um nome para o aplicativo que

descrevem seu aplicativo para os
consumidores.
Incluir aplicativo web / API web Sim
Permitir fluxo implícito Sim
URL de resposta https://localhost:44300/signin- URLs de resposta são pontos de

oidc extremidade onde o Azure AD B2C
retornará os tokens que o aplicativo
solicitar. O Visual Studio fornece a URL
de resposta para usar. Por enquanto,
insira
https://localhost:44300/signin-
oidc
preencha o formulário.
URI da ID do aplicativo Deixe em branco Não é necessário para este tutorial.
Incluir cliente nativo Não
WARNING
Se estar ciente de como configurar uma URL de resposta não sejam localhost, o restrições sobre o que é permitido na lista de
URL de resposta.
Depois que o aplicativo é registrado, é exibida a lista de aplicativos no locatário. Selecione o aplicativo que acabou
de registrar. Selecione o cópia ícone à direita do ID do aplicativo campo para copiá-lo na área de transferência.
Nada mais podem ser configurado no locatário do Azure AD B2C neste momento, mas deixe a janela do
navegador aberta. Não há mais de configuração depois que o aplicativo ASP.NET Core é criado.
Criar um aplicativo ASP.NET Core no Visual Studio 2017

O modelo de aplicativo Web Visual Studio pode ser configurado para usar o locatário do Azure AD B2C para
autenticação.
No Visual Studio:
2. Selecione aplicativo Web da lista de modelos.
3. Selecione o alterar autenticação botão.
4. No alterar autenticação caixa de diálogo, selecione contas de usuário individuaise, em seguida,
selecione conectar-se ao repositório de usuário existente na nuvem na lista suspensa.
5. Preencha o formulário com os seguintes valores:
CONFIGURAÇÃO VALOR
Nome de domínio <o nome de domínio do seu locatário do B2C>

ID do aplicativo <Cole a ID do aplicativo da área de transferência>
Caminho de retorno de chamada <Use o valor padrão>
Política de inscrição ou entrada B2C_1_SiUpIn
Política de redefinição de senha B2C_1_SSPR
Editar política de perfil <Deixe em branco>
Selecione o cópia próximo ao link URI de resposta para copiar o URI de resposta para a área de
transferência. Selecione Okey para fechar o alterar autenticação caixa de diálogo. Selecione Okey para
criar o aplicativo web.
Concluir o registro do aplicativo B2C

Retornar à janela do navegador com as propriedades do aplicativo B2C ainda abertas. Alterar temporários URL de
resposta especificado anteriormente para o valor copiado do Visual Studio. Selecione salvar na parte superior da
janela.
TIP
Se você não copiar a URL de resposta, use o endereço SSL na guia Debug nas propriedades do projeto da web e acrescente o
CallbackPath o valor da appSettings. JSON.
Configurar políticas
Use as etapas na documentação do Azure AD B2C para criar uma política de inscrição ou entradae então criar uma
política de redefinição de senha. Use os valores de exemplo fornecidos na documentação do provedores de
identidade, atributos de inscrição, e declarações do aplicativo. Usando o executar agora botão para testar
as políticas, conforme descrito na documentação é opcional.
WARNING
Verifique se os nomes de política são exatamente como descrito na documentação, como essas políticas foram usadas na
alterar autenticação caixa de diálogo no Visual Studio. Os nomes de política podem ser verificados no appSettings. JSON.
No Visual Studio, pressione F5 para compilar e executar o aplicativo. Depois que o aplicativo web for iniciado,
selecione Accept para aceitar o uso de cookies (se solicitado) e, em seguida, selecione entrar.
O navegador é redirecionado para o locatário do Azure AD B2C. Entrar com uma conta existente (se uma foi
criada a testar as políticas) ou selecione Inscreva-se agora para criar uma nova conta. O esqueceu sua senha?
link é usado para redefinir uma senha esquecida.
Depois de entrar com êxito, o navegador é redirecionado para o aplicativo web.
Próximas etapas
Criar um locatário do Azure Active Directory B2C
Registrar um aplicativo no Azure B2C do AD
Usar o Visual Studio para criar um aplicativo Web do ASP.NET Core configurados para usar o locatário do
Azure AD B2C para autenticação
Configurar políticas para controlar o comportamento do locatário do Azure AD B2C
Agora que o aplicativo ASP.NET Core está configurado para usar o Azure AD B2C para autenticação, o atributo
Authorize pode ser usado para proteger seu aplicativo. Continue a desenvolver seu aplicativo aprendendo a:
Personalizar a interface do usuário do Azure AD B2C.
Configurar os requisitos de complexidade de senha.
Habilitar a autenticação multifator.
Configurar provedores de identidade adicional, como Microsoft, Facebook, Google, Amazon, do Twitter e
outros.
Usar a API do Graph do Azure AD para recuperar informações de usuário adicionais, como associação de
grupo, do locatário do Azure AD B2C.
Proteger um ASP.NET Core API da web usando o Azure AD B2C.
Chamar uma API web de um aplicativo web do .NET usando o Azure AD B2C.
Autenticação de nuvem em APIs web com o Azure
Active Directory B2C no ASP.NET Core
Por Cam Soper

Azure Active Directory B2C do diretório (Azure AD B2C ) é uma solução de gerenciamento de identidade de
nuvem para aplicativos web e móveis. O serviço fornece autenticação para aplicativos hospedados na nuvem e
locais. Tipos de autenticação incluem contas individuais, contas de rede social e contas corporativas de federado.
B2C do AD do Azure também fornece a autenticação multifator com configuração mínima.
Azure Active Directory (Azure AD ) e o Azure AD B2C são ofertas de produtos separados. Um locatário do AD do
Azure representa uma organização, enquanto que um locatário do Azure AD B2C representa uma coleção de
identidades a serem usados com aplicativos de terceira parte confiável. Para obter mais informações, consulte do
Azure AD B2C: perguntas frequentes (FAQ ).
Uma vez que as APIs da web não tem nenhuma interface do usuário, eles são não é possível redirecionar o
usuário a um serviço de token seguro, como o Azure AD B2C. Em vez disso, a API é passada um token de
portador do aplicativo de chamada, que já tiver autenticado o usuário com o Azure AD B2C. A API, em seguida,
valida o token sem interação direta do usuário.
Neste tutorial, saiba como:
Crie um locatário do Azure Active Directory B2C.
Registre uma API da Web no B2C do AD do Azure.
Use o Visual Studio para criar uma API da Web configurado para usar o locatário do Azure AD B2C para
autenticação.
Configure políticas para controlar o comportamento do locatário do Azure AD B2C.
Usar o Postman para simular um aplicativo web que apresenta uma caixa de diálogo de logon, recupera um
token e usa-o para fazer uma solicitação em relação a API da web.
Pré-requisitos
A seguir é necessários para este passo a passo:
Assinatura do Microsoft Azure
Visual Studio 2017 (qualquer edição)
Postman
Criar o locatário do Azure Active Directory B2C

Criar um locatário do Azure AD B2C conforme descrito na documentação do. Quando solicitado, associar o
locatário com uma assinatura do Azure é opcional para este tutorial.
Configurar uma política de inscrição ou entrada

Use as etapas na documentação do Azure AD B2C para criar uma política de inscrição ou entrada. Nomeie a
diretiva SiUpIn. Use os valores de exemplo fornecidos na documentação do provedores de identidade,
atributos de inscrição, e declarações do aplicativo. Usando o executar agora botão para testar a política
conforme descrito na documentação é opcional.
Registrar a API no B2C do AD do Azure
No locatário do Azure AD B2C recém-criado, registre sua API usando as etapas na documentação do sob o
registrar uma API web seção.
Nome {Nome da API} Insira um nome para o aplicativo que

descrevem seu aplicativo para os
consumidores.
URL de resposta https://localhost URLs de resposta são pontos de

extremidade onde o Azure AD B2C
retornará os tokens que o aplicativo
solicitar.
URI da ID do aplicativo api O URI não precisa resolver para um

endereço físico. Ele só precisa ser
exclusivo.
Depois que a API é registrada, é exibida a lista de aplicativos e APIs no locatário. Selecione a API que foi
registrada anteriormente. Selecione o cópia ícone à direita do ID do aplicativo campo para copiá-lo na área de
transferência. Selecione escopos publicados e verifique se o padrão user_impersonation escopo está presente.
Criar um aplicativo ASP.NET Core no Visual Studio 2017

O modelo de aplicativo Web Visual Studio pode ser configurado para usar o locatário do Azure AD B2C para
autenticação.
No Visual Studio:
2. Selecione API Web da lista de modelos.
3. Selecione o alterar autenticação botão.
4. No alterar autenticação caixa de diálogo, selecione contas de usuário individuais > conectar-se ao
repositório de usuário existente na nuvem.
5. Preencha o formulário com os seguintes valores:
Nome de domínio {o nome de domínio do seu locatário B2C}
ID do aplicativo {Colar a ID do aplicativo da área de transferência}
Política de inscrição ou entrada B2C_1_SiUpIn
Selecione Okey para fechar o alterar autenticação caixa de diálogo. Selecione Okey para criar o
aplicativo web.
O Visual Studio cria a API da web com um controlador chamado ValuesController.cs que retorna valores
embutidos para solicitações GET. A classe é decorada com o atributo Authorize, portanto, todas as solicitações
requerem autenticação.
Executar a API da web
No Visual Studio, execute a API. O Visual Studio inicia um navegador apontado na URL da raiz da API. Anote a
URL na barra de endereços e deixar a API em execução em segundo plano.
NOTE
Como não há nenhum controlador definido para a URL da raiz, o navegador pode exibir um erro 404 de (página não
encontrada). Esse comportamento é esperado.
Usar o Postman para obter um token e a API de teste

Postman é uma ferramenta para testar APIs web. Para este tutorial, carteiro simula um aplicativo web que acessa a
API da web em nome do usuário.
Registre o Postman como um aplicativo web
Uma vez que o Postman simula um aplicativo web que obtém tokens de locatário do Azure AD B2C, ele deve ser
registrado no locatário como um aplicativo web. Registrar o Postman usando as etapas na documentação do sob o
registrar um aplicativo web seção. Parar na criar um segredo do cliente de aplicativo web seção. Um
segredo do cliente não é necessário para este tutorial.
Nome Postman
URL de resposta https://getpostman.com/postman
URI da ID do aplicativo {Deixe em branco } Não é necessário para este tutorial.
O aplicativo web registrado recentemente precisa de permissão para acessar a API da web em nome do usuário.
1. Selecione Postman na lista de aplicativos e selecione acesso à API no menu à esquerda.
2. Selecione + adicionar.
3. No selecionar API lista suspensa, selecione o nome da API web.
4. No selecionar escopos lista suspensa, verifique se todos os escopos são selecionados.
5. Selecione Okey.
Observe a ID do aplicativo do aplicativo Postman, pois ele é necessário para obter um token de portador.
Criar uma solicitação do Postman
Inicie o Postman. Por padrão, o Postman exibe a criar novo caixa de diálogo após a inicialização. Se a caixa de
diálogo não for exibida, selecione a + novo botão no canto superior esquerdo.
Dos criar novo caixa de diálogo:
1. Selecione solicitar.
2. Insira obter valores na nome da solicitação caixa.
3. Selecione + Criar coleção para criar uma nova coleção para armazenar a solicitação. Nomear a coleção
tutoriais do ASP.NET Core e, em seguida, selecione a marca de seleção.
4. Selecione o salvar em tutoriais do ASP.NET Core botão.
Testar a API da web sem autenticação
Para verificar que a API da web requer autenticação, primeiro verifique uma solicitação sem autenticação.
1. No insira a URL da solicitação , digite a URL para ValuesController . A URL é o mesmo exibido no
navegador com api/valores acrescentado. Por exemplo, https://localhost:44375/api/values .
2. Selecione o enviar botão.
3. Observe o status da resposta é 401 não autorizado.
IMPORTANT
Se você receber um erro "Não foi possível obter qualquer resposta", você talvez precise desabilitar a verificação do certificado
SSL na configurações do Postman.
Obter um token de portador

Para fazer uma solicitação autenticada a API da web, é necessário um token de portador. Postman torna mais fácil
entrar no locatário do Azure AD B2C e obter um token.
1. Sobre o autorização guia da tipo lista suspensa, selecione OAuth 2.0. No adicionar dados de
autorização lista suspensa, selecione cabeçalhos de solicitação. Selecione obter Token de acesso
novo.
2. Conclua o obter novo TOKEN de acesso caixa de diálogo da seguinte maneira:
Nome do token {nome do token} Insira um nome descritivo para o

token.
Tipo de concessão Implícita
URL de retorno de chamada https://getpostman.com/postman
URL de autenticação Substitua {nome de domínio do

https://login.microsoftonline.com/{tenant
domain name}/oauth2/v2.0/authorize? locatário } com o nome de domínio
p=B2C_1_SiUpIn
do locatário. IMPORTANTE: essa
URL deve ter o mesmo nome de
domínio que o que for encontrado
no AzureAdB2C.Instance da API
web appSettings. JSON arquivo.
Consulte a Observação†.
ID do cliente {entrar no aplicativo de Postman ID

do aplicativo}
Escopo https://{tenant domain Substitua {nome de domínio do

name}/{api}/user_impersonation locatário } com o nome de domínio
openid offline_access
do locatário. Substitua {api} com o
URI da ID do aplicativo você deu a
API da web ao registrado pela
primeira vez (nesse caso, api ). O
padrão para a URL é:
https://{tenant}.onmicrosoft.com/{api-
id-uri}/{scope name}
.
Estado {Deixe em branco }
Autenticação de cliente Enviar as credenciais do cliente no

corpo
NOTE
† A caixa de diálogo de configurações de política no portal do Azure Active Directory B2C exibe duas URLs possíveis:
um no formato https://login.microsoftonline.com/ {nome de domínio do locatário} / {informações adicionais de
caminho} e o outro no formato https://{tenant name}.b2clogin.com/ {nome de domínio do locatário} /
{adicionais informações de caminho}. Ele tem críticos que o domínio encontrado na AzureAdB2C.Instance da API
web appSettings. JSON arquivo corresponde ao usado no aplicativo de web appSettings. JSON arquivo. Isso é o
mesmo domínio usado para o campo de URL do Auth no Postman. Observe que o Visual Studio usa um formato de
URL ligeiramente diferente que o que é exibido no portal. Desde que os domínios corresponderem, a URL funciona.
3. Selecione o solicitar Token botão.

4. Postman abre uma nova janela que contém o diálogo de logon do locatário do Azure AD B2C. Entrar com
uma conta existente (se uma foi criada a testar as políticas) ou selecione Inscreva-se agora para criar uma
nova conta. O esqueceu sua senha? link é usado para redefinir uma senha esquecida.
5. Depois de entrar com êxito, a janela será fechada e o gerenciar TOKENS de acesso caixa de diálogo é
exibida. Role para baixo até a parte inferior e selecione o uso Token botão.
A API da web com autenticação de teste

Selecione o enviar botão para enviar a solicitação novamente. Neste momento, o status de resposta estiver 200
Okey e o conteúdo do JSON está visível na resposta corpo guia.
Próximas etapas
Crie um locatário do Azure Active Directory B2C.
Registre uma API da Web no B2C do AD do Azure.
Use o Visual Studio para criar uma API da Web configurado para usar o locatário do Azure AD B2C para
autenticação.
Configure políticas para controlar o comportamento do locatário do Azure AD B2C.
Usar o Postman para simular um aplicativo web que apresenta uma caixa de diálogo de logon, recupera um
token e usa-o para fazer uma solicitação em relação a API da web.
Continue a desenvolver sua API pelo learning para:
Proteger um ASP.NET Core em aplicativo web usando o Azure AD B2C.
Chamar uma API web de um aplicativo web do .NET usando o Azure AD B2C.
Personalizar a interface do usuário do Azure AD B2C.
Configurar os requisitos de complexidade de senha.
Habilitar a autenticação multifator.
Configurar provedores de identidade adicional, como Microsoft, Facebook, Google, Amazon, do Twitter e
outros.
Usar a API do Graph do Azure AD para recuperar informações de usuário adicionais, como associação de
grupo, do locatário do Azure AD B2C.
Artigos baseados em projetos do ASP.NET Core
criados com contas de usuário individuais
O ASP.NET Core Identity é incluído nos modelos de projeto no Visual Studio com a opção "Contas de usuário
individuais".
Os modelos de autenticação estão disponíveis na CLI do .NET Core com -au Individual :

dotnet new webapp -au Individual

dotnet new razor -au Individual
Sem autenticação
Autenticação é especificada na CLI do .NET Core com o -au opção. No Visual Studio, o alterar autenticação
caixa de diálogo está disponível para novos aplicativos da web. É o padrão para novos aplicativos web no Visual
Studio sem autenticação.
Projetos criados com nenhuma autenticação:
Não contêm páginas da web e a interface do usuário para entrar e sair.
Não contêm o código de autenticação.
Autenticação do Windows é especificada para novos aplicativos web na CLI do .NET Core com o -au Windows
opção. No Visual Studio, o alterar autenticação caixa de diálogo fornece o autenticação do Windows opções.
Se a autenticação do Windows é selecionada, o aplicativo está configurado para usar o módulo do IIS da
autenticação Windows. Autenticação do Windows destina-se a sites da Intranet.
Recursos adicionais
Os artigos a seguir mostram como usar o código gerado em modelos do ASP.NET Core que usam contas de
usuário individual:
Criar um aplicativo ASP.NET Core com os dados de usuário protegidos por autorização
Introdução à autorização no núcleo do ASP.NET
Autorização é o processo que determina o que um usuário pode fazer. Por exemplo, um usuário administrativo
tem permissão para criar uma biblioteca de documentos e adicionar, editar e excluir documentos. Um usuário não
administrativo trabalhando com esta biblioteca só está autorizado a ler os documentos.
A autorização é ortogonal e independente da autenticação. No entanto, a autorização requer um mecanismo de
autenticação. Autenticação é o processo de verificação de quem é um usuário. A autenticação pode criar uma ou
mais identidades para o usuário atual.
Tipos de autorização
A autorização do ASP.NET Core fornece um modelo simples de funções declarativas baseado em políticas. Ela é
expressa em requisitos e os manipuladores avaliam as reivindicações de um usuário em relação aos requisitos.
Verificações imperativas podem ser baseadas em políticas simples ou políticas que avaliem a identidade do
usuário e propriedades do recurso que o usuário está tentando acessar.
Namespaces
Componentes de autorização, incluindo os atributo AuthorizeAttribute e AllowAnonymousAttribute , são
encontrados no namespace Microsoft.AspNetCore.Authorization .
Consulte a documentação em autorização simples.
Criar um aplicativo ASP.NET Core com os dados de
usuário protegidos por autorização

Ver esse PDF para a versão do ASP.NET Core MVC. A versão 1.1 do ASP.NET Core deste tutorial está nesta
pasta. O exemplo do ASP.NET Core 1.1 está em exemplos.
Consulte esse pdf
Este tutorial mostra como criar um aplicativo web do ASP.NET Core com dados de usuário protegidos por
autorização. Ele exibe uma lista de contatos criada por usuários autenticados (registrados). Há três grupos de
segurança:
Usuários registrados podem exibir todos os dados aprovados e podem editar/excluir seus próprios dados.
Gerenciadores de podem aprovar ou rejeitar dados de um contato. Apenas os contatos aprovados são
visíveis aos usuários.
Os administradores podem rejeitar/aprovar e editar/excluir todos os dados.
Na imagem a seguir, o usuário Rick ( rick@example.com ) está conectado. Rick só pode ver os contatos aprovados e
os links editar/excluir/criar novo de seus contatos. Somente o último registro criado por Rick exibe os links
editar e excluir. Outros usuários não verão o último registro até que um gerente ou administrador altere o
status para "Aprovado".
Na imagem a seguir, manager@contoso.com está conectado e na função de gerenciadores:

A imagem a seguir mostra a tela de exibição de detalhes de um contato dos gerentes:
O botões aprovar e rejeitar são exibidos somente para administradores e gerentes.

Na imagem a seguir, admin@contoso.com está conectado e na função de gerenciadores:
O administrador tem todos os privilégios. Ele pode ler/editar/excluir todos os contatos e alterar os status deles.
O aplicativo foi criado fazendo scaffolding do seguinte modelo de Contact :
public class Contact

{
public int ContactId { get; set; }
public string Address { get; set; }
public string Zip { get; set; }
[DataType(DataType.EmailAddress)]
}
O exemplo contém os seguintes manipuladores de autorização:

ContactIsOwnerAuthorizationHandler : Garante que um usuário só pode editar seus dados.
ContactManagerAuthorizationHandler : Permite que os gerentes aprovem ou rejeitem contatos.
ContactAdministratorsAuthorizationHandler : Permite aos administradores aprovar, rejeitar e editar/excluir
contatos.
Pré-requisitos
Este tutorial é avançado. Você deve estar familiarizado com:
ASP.NET Core
Autenticação
Autorização
No ASP.NET Core 2.1, User.IsInRole Falha ao usar AddDefaultIdentity . Este tutorial usa AddDefaultIdentity e,
portanto, exige o ASP.NET Core 2.2 ou posterior. Ver esse problema de GitHub para uma solução alternativa.
O aplicativo inicial e o concluído

Baixe as concluída aplicativo. Teste o aplicativo concluído para que você se familiarize com seus recursos de
segurança.
O aplicativo inicial
Baixe o aplicativo inicial.
Execute o aplicativo, clique em ContactManager e verifique se você pode criar, editar e excluir um contato.
Proteger os dados de usuário

As seções a seguir têm todas as principais etapas para criar um aplicativo com dados de usuários seguros. Talvez
seja útil para fazer referência ao projeto concluído.
Vincular os dados de contato ao usuário
Usar o ASP.NET identidade ID de usuário para garantir que os usuários pode editar seus dados, mas não outros
dados de usuários. Adicione OwnerID e ContactStatus para o Contact modelo:
public class Contact

{
public int ContactId { get; set; }
// user ID from AspNetUser table.

public string OwnerID { get; set; }

public string Address { get; set; }
public string Zip { get; set; }
[DataType(DataType.EmailAddress)]
public ContactStatus Status { get; set; }

}
public enum ContactStatus

{
Submitted,
Approved,
Rejected
}
OwnerID é a ID do usuário da tabela AspNetUser no banco de dados de identidade. O campo Status determina
se um contato pode ser visto por usuários gerais.
Criar uma nova migração e atualizar o banco de dados:
dotnet ef migrations add userID_Status

Adicionar serviços de função à identidade
Acrescente AddRoles para adicionar serviços de função:

{
{
});
services.AddDefaultIdentity<IdentityUser>().AddRoles<IdentityRole>()
Exigir usuários autenticados

Defina a política de autenticação padrão para exigir que os usuários sejam autenticados:

{
{
});
services.AddMvc(config =>
{
// using Microsoft.AspNetCore.Mvc.Authorization;
// using Microsoft.AspNetCore.Authorization;
var policy = new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build();
config.Filters.Add(new AuthorizeFilter(policy));
})
Você pode recusar a autenticação em nível de método de ação, controlador ou página Razor com o
[AllowAnonymous] atributo. Configurar a política de autenticação padrão para exigir que os usuários sejam
autenticados protege recém-adicionado páginas do Razor e controladores. Autenticação necessária por padrão é
mais segura do que contar com novos controladores e páginas do Razor para incluir o [Authorize] atributo.
Adicionar AllowAnonymousàs páginas Índice, Sobre e Contatos para que usuários anônimos possam obter
informações sobre o site antes de eles se registrarem.
namespace ContactManager.Pages
{
[AllowAnonymous]
{
public void OnGet()
{
}
}
}
Configurar a conta de teste

A classe SeedData cria duas contas: administrador e gerenciador. Use a ferramenta Gerenciador de segredo para
definir uma senha para essas contas. Defina a senha do diretório do projeto (o diretório que contém Program.cs):
dotnet user-secrets set SeedUserPW <PW>
Se uma senha forte não for especificada, uma exceção é gerada quando SeedData.Initialize é chamado.
Atualização Main para usar a senha de teste:

{
{

{
var context = services.GetRequiredService<ApplicationDbContext>();
// requires using Microsoft.Extensions.Configuration;

var config = host.Services.GetRequiredService<IConfiguration>();
// Set password with the Secret Manager tool.
// dotnet user-secrets set SeedUserPW <pw>
var testUserPw = config["SeedUserPW"];

try
{
SeedData.Initialize(services, testUserPw).Wait();
}
{
logger.LogError(ex.Message, "An error occurred seeding the DB.");
}
}
host.Run();
}

}
Criar as contas de teste e atualizar os contatos
Atualize o método Initialize na classe SeedData para criar as contas de teste:
public static async Task Initialize(IServiceProvider serviceProvider, string testUserPw)

{
using (var context = new ApplicationDbContext(
serviceProvider.GetRequiredService<DbContextOptions<ApplicationDbContext>>()))
{
// For sample purposes seed both with the same password.
// Password is set with the following:
// dotnet user-secrets set SeedUserPW <pw>
// The admin user can do anything
var adminID = await EnsureUser(serviceProvider, testUserPw, "admin@contoso.com");

await EnsureRole(serviceProvider, adminID, Constants.ContactAdministratorsRole);
// allowed user can create and edit contacts that they create
var managerID = await EnsureUser(serviceProvider, testUserPw, "manager@contoso.com");
await EnsureRole(serviceProvider, managerID, Constants.ContactManagersRole);
SeedDB(context, adminID);
}
}
private static async Task<string> EnsureUser(IServiceProvider serviceProvider,

string testUserPw, string UserName)
{
var userManager = serviceProvider.GetService<UserManager<IdentityUser>>();
var user = await userManager.FindByNameAsync(UserName);

if (user == null)
{
user = new IdentityUser { UserName = UserName };
await userManager.CreateAsync(user, testUserPw);
}
return user.Id;
}
private static async Task<IdentityResult> EnsureRole(IServiceProvider serviceProvider,

string uid, string role)
{
IdentityResult IR = null;
var roleManager = serviceProvider.GetService<RoleManager<IdentityRole>>();
if (roleManager == null)
{
throw new Exception("roleManager null");
}
if (!await roleManager.RoleExistsAsync(role))
{
IR = await roleManager.CreateAsync(new IdentityRole(role));
}
var userManager = serviceProvider.GetService<UserManager<IdentityUser>>();
var user = await userManager.FindByIdAsync(uid);
IR = await userManager.AddToRoleAsync(user, role);
return IR;
}
Adicione a ID de usuário de administrador e ContactStatus aos contatos. Torne um dos contatos "Enviado" e um
"Rejeitado". Adicione a ID de usuário e o status para todos os contatos. Somente um contato é exibido:
public static void SeedDB(ApplicationDbContext context, string adminID)

{
if (context.Contact.Any())
{
}
context.Contact.AddRange(
new Contact
{
Name = "Debra Garcia",
Address = "1234 Main St",
City = "Redmond",
State = "WA",
Zip = "10999",
Email = "debra@example.com",
Status = ContactStatus.Approved,
OwnerID = adminID
},
Criar o proprietário, manager e manipuladores de autorização do

administrador
Criar uma classe ContactIsOwnerAuthorizationHandler na pasta autorização. O
ContactIsOwnerAuthorizationHandler verifica que o usuário que atua em um recurso possui o recurso.
using ContactManager.Data;
using ContactManager.Models;
using Microsoft.AspNetCore.Authorization.Infrastructure;
namespace ContactManager.Authorization
{
public class ContactIsOwnerAuthorizationHandler
: AuthorizationHandler<OperationAuthorizationRequirement, Contact>
{
UserManager<IdentityUser> _userManager;
public ContactIsOwnerAuthorizationHandler(UserManager<IdentityUser>
userManager)
{
}
protected override Task

HandleRequirementAsync(AuthorizationHandlerContext context,
OperationAuthorizationRequirement requirement,
Contact resource)
{
if (context.User == null || resource == null)
{
// Return Task.FromResult(0) if targeting a version of
// .NET Framework older than 4.6:
}
// If we're not asking for CRUD permission, return.
if (requirement.Name != Constants.CreateOperationName &&

requirement.Name != Constants.ReadOperationName &&
requirement.Name != Constants.UpdateOperationName &&
requirement.Name != Constants.DeleteOperationName )
{
}
if (resource.OwnerID == _userManager.GetUserId(context.User))
{
context.Succeed(requirement);
}
}
}
}
O ContactIsOwnerAuthorizationHandler chamadas contexto. Êxito se o usuário autenticado atual for o proprietário

do contato. Manipuladores de autorização geralmente:
Retornar context.Succeed quando os requisitos sejam atendidos.
Retornar Task.CompletedTask quando os requisitos não forem atendidos. Task.CompletedTask não é sucesso
ou falha—permite que outros manipuladores de autorização executar.
Se você precisar fazer explicitamente, retornar contexto. Falha.
O aplicativo permite que proprietários de contato possam editar/excluir/criar seus dados.
ContactIsOwnerAuthorizationHandler não precisa verificar a operação passada no parâmetro de requisito.
Criar um manipulador de autorização do Gerenciador
Criar uma classe ContactManagerAuthorizationHandler na pasta autorização. O
ContactManagerAuthorizationHandler verifica o usuário atuando no recurso é um gerente. Somente gerentes
possam aprovar ou rejeitar as alterações de conteúdo (novas ou alteradas).
{
public class ContactManagerAuthorizationHandler :
AuthorizationHandler<OperationAuthorizationRequirement, Contact>
{
protected override Task
HandleRequirementAsync(AuthorizationHandlerContext context,
Contact resource)
{
if (context.User == null || resource == null)
{
}
// If not asking for approval/reject, return.

if (requirement.Name != Constants.ApproveOperationName &&
requirement.Name != Constants.RejectOperationName)
{
}
// Managers can approve or reject.

if (context.User.IsInRole(Constants.ContactManagersRole))
{
}
}
}
}
Crie um manipulador de autorização do administrador

Criar uma classe ContactAdministratorsAuthorizationHandler na pasta autorização. O
ContactAdministratorsAuthorizationHandler verifica se o usuário atuando no recurso é um administrador.
Administrador pode fazer todas as operações.
{
public class ContactAdministratorsAuthorizationHandler
: AuthorizationHandler<OperationAuthorizationRequirement, Contact>
{
protected override Task HandleRequirementAsync(
AuthorizationHandlerContext context,
Contact resource)
{
if (context.User == null)
{
}
// Administrators can do anything.

if (context.User.IsInRole(Constants.ContactAdministratorsRole))
{
}
}
}
}
O registro dos manipuladores de autorização

Serviços usando o Entity Framework Core devem ser registrados injeção de dependência usando AddScoped. O
ContactIsOwnerAuthorizationHandler usa o ASP.NET Core identidade, que se baseia no Entity Framework Core. O
registro dos manipuladores com a coleção de serviço para que eles estejam disponíveis para o
ContactsController por meio injeção de dependência. Adicione o seguinte código ao final da ConfigureServices :
{
{
});
services.AddMvc(config =>
{
// using Microsoft.AspNetCore.Mvc.Authorization;
// using Microsoft.AspNetCore.Authorization;
var policy = new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build();
config.Filters.Add(new AuthorizeFilter(policy));
})
// Authorization handlers.
services.AddScoped<IAuthorizationHandler,
ContactIsOwnerAuthorizationHandler>();
services.AddSingleton<IAuthorizationHandler,
ContactAdministratorsAuthorizationHandler>();
services.AddSingleton<IAuthorizationHandler,
ContactManagerAuthorizationHandler>();
}
ContactAdministratorsAuthorizationHandler e ContactManagerAuthorizationHandler são adicionados como

singletons. Eles são singletons porque eles não usam o EF e todas as informações necessárias na Context
parâmetro do HandleRequirementAsync método.
Suporte à autorização
Nesta seção, você atualize as páginas Razor e adicione uma classe de requisitos de operações.
Examine a classe de requisitos de operações de contato
Examine o ContactOperations classe. Essa classe contém os requisitos de aplicativo dá suporte:
{
public static class ContactOperations
{
public static OperationAuthorizationRequirement Create =
new OperationAuthorizationRequirement {Name=Constants.CreateOperationName};
public static OperationAuthorizationRequirement Read =
new OperationAuthorizationRequirement {Name=Constants.ReadOperationName};
public static OperationAuthorizationRequirement Update =
new OperationAuthorizationRequirement {Name=Constants.UpdateOperationName};
public static OperationAuthorizationRequirement Delete =
new OperationAuthorizationRequirement {Name=Constants.DeleteOperationName};
public static OperationAuthorizationRequirement Approve =
new OperationAuthorizationRequirement {Name=Constants.ApproveOperationName};
public static OperationAuthorizationRequirement Reject =
new OperationAuthorizationRequirement {Name=Constants.RejectOperationName};
}
public class Constants

{
public static readonly string CreateOperationName = "Create";
public static readonly string ReadOperationName = "Read";
public static readonly string UpdateOperationName = "Update";
public static readonly string DeleteOperationName = "Delete";
public static readonly string ApproveOperationName = "Approve";
public static readonly string RejectOperationName = "Reject";
public static readonly string ContactAdministratorsRole =

"ContactAdministrators";
public static readonly string ContactManagersRole = "ContactManagers";
}
}
Criar uma classe base para as páginas do Razor de contatos

Crie uma classe base que contém os serviços usados em contatos páginas do Razor. A classe base coloca o
código de inicialização em um único local:
using ContactManager.Data;
namespace ContactManager.Pages.Contacts
{
public class DI_BasePageModel : PageModel
{
protected ApplicationDbContext Context { get; }
protected IAuthorizationService AuthorizationService { get; }
protected UserManager<IdentityUser> UserManager { get; }
public DI_BasePageModel(
ApplicationDbContext context,
IAuthorizationService authorizationService,
UserManager<IdentityUser> userManager) : base()
{
Context = context;
UserManager = userManager;
AuthorizationService = authorizationService;
}
}
}
O código anterior:
Adiciona o serviço IAuthorizationService para acessar os manipuladores de autorização.
Adiciona o serviço de identidade UserManager .
Adicione a ApplicationDbContext .
Atualizar o CreateModel
Atualize o construtor de criar modelo de página para usar a classe base DI_BasePageModel :
public class CreateModel : DI_BasePageModel

{
public CreateModel(
UserManager<IdentityUser> userManager)
: base(context, authorizationService, userManager)
{
}
Atualize o método CreateModel.OnPostAsync para:

Adicione a ID de usuário ao modelo Contact .
Chame o manipulador de autorização para verificar se que o usuário tem permissão para criar contatos.

{
{
return Page();
}
Contact.OwnerID = UserManager.GetUserId(User);
// requires using ContactManager.Authorization;

var isAuthorized = await AuthorizationService.AuthorizeAsync(
User, Contact,
ContactOperations.Create);
if (!isAuthorized.Succeeded)
{
return new ChallengeResult();
}
Context.Contact.Add(Contact);
await Context.SaveChangesAsync();
}
Atualizar o IndexModel
Atualize o método OnGetAsync para que apenas os contatos aprovados sejam mostrados aos usuários gerais:
public class IndexModel : DI_BasePageModel
{
public IndexModel(
{
}
public IList<Contact> Contact { get; set; }

{
var contacts = from c in Context.Contact
select c;
var isAuthorized = User.IsInRole(Constants.ContactManagersRole) ||

User.IsInRole(Constants.ContactAdministratorsRole);
var currentUserId = UserManager.GetUserId(User);
// Only approved contacts are shown UNLESS you're authorized to see them
// or you are the owner.
if (!isAuthorized)
{
contacts = contacts.Where(c => c.Status == ContactStatus.Approved
|| c.OwnerID == currentUserId);
}
Contact = await contacts.ToListAsync();

}
}
Atualizar o EditModel
Adicione um manipulador de autorização para verificar se que o usuário é proprietária do contato. Como a
autorização de recursos está sendo validada, o [Authorize] atributo não é suficiente. O aplicativo não tiver
acesso ao recurso quando atributos são avaliados. Autorização baseada em recursos deve ser imperativa. As
verificações devem ser executadas depois que o aplicativo tem acesso ao recurso, carregá-los no modelo de
página ou carregá-los dentro do manipulador em si. Com frequência, você acessa o recurso, passando a chave de
recurso.
public class EditModel : DI_BasePageModel

{
public EditModel(
{
}
[BindProperty]
public Contact Contact { get; set; }

{
Contact = await Context.Contact.FirstOrDefaultAsync(
m => m.ContactId == id);
if (Contact == null)
{
return NotFound();
}
}

User, Contact,
ContactOperations.Update);
{
}
return Page();
}

{
{
return Page();
}
// Fetch Contact from DB to get OwnerID.

var contact = await Context
.Contact.AsNoTracking()
.FirstOrDefaultAsync(m => m.ContactId == id);
if (contact == null)
{
return NotFound();
}

User, contact,
ContactOperations.Update);
{
}
Contact.OwnerID = contact.OwnerID;
Context.Attach(Contact).State = EntityState.Modified;
if (contact.Status == ContactStatus.Approved)
{
// If the contact is updated after approval,
// and the user cannot approve,
// set the status back to submitted so the update can be
// checked and approved.
var canApprove = await AuthorizationService.AuthorizeAsync(User,
contact,
ContactOperations.Approve);
if (!canApprove.Succeeded)
{
contact.Status = ContactStatus.Submitted;
}
}
}
private bool ContactExists(int id)

{
return Context.Contact.Any(e => e.ContactId == id);
}
}
Atualizar o DeleteModel
Atualize o modelo de página de exclusão para usar o manipulador de autorização para verificar se que o usuário
tem permissão de exclusão no contato.
public class DeleteModel : DI_BasePageModel

{
public DeleteModel(
{
}
[BindProperty]

{
Contact = await Context.Contact.FirstOrDefaultAsync(
{
return NotFound();
}

User, Contact,
ContactOperations.Delete);
{
}
return Page();
}

{
Contact = await Context.Contact.FindAsync(id);
var contact = await Context

.Contact.AsNoTracking()
.FirstOrDefaultAsync(m => m.ContactId == id);
{
return NotFound();
}

User, contact,
ContactOperations.Delete);
{
}
Context.Contact.Remove(Contact);
}
}
Injetar o serviço de autorização em exibições
Atualmente, mostra a interface do usuário a edita e excluir links para os contatos, que o usuário não é possível
modificar.
Injetar o serviço de autorização no arquivo Views/_ViewImports.cshtml para que ele esteja disponível para todos
os modos de exibição:
@using ContactManager
@using ContactManager.Data
@namespace ContactManager.Pages
@using ContactManager.Authorization;
@using Microsoft.AspNetCore.Authorization
@using ContactManager.Models
@inject IAuthorizationService AuthorizationService
A marcação anterior adiciona várias using instruções.

Atualizar o editar e excluir vincula na Pages/Contacts/Index.cshtml para que eles sejam renderizados somente
para usuários com as permissões apropriadas:
@page
@model ContactManager.Pages.Contacts.IndexModel
@{
}
<h2>Index</h2>
<p>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Contact[0].Name)
</th>
<th>
@Html.DisplayNameFor(model => model.Contact[0].Address)
</th>
<th>
@Html.DisplayNameFor(model => model.Contact[0].City)
</th>
<th>
@Html.DisplayNameFor(model => model.Contact[0].State)
</th>
<th>
@Html.DisplayNameFor(model => model.Contact[0].Zip)
</th>
<th>
@Html.DisplayNameFor(model => model.Contact[0].Email)
</th>
<th>
@Html.DisplayNameFor(model => model.Contact[0].Status)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Contact)
{
{
<tr>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.Address)
</td>
<td>
@Html.DisplayFor(modelItem => item.City)
</td>
<td>
@Html.DisplayFor(modelItem => item.State)
</td>
<td>
@Html.DisplayFor(modelItem => item.Zip)
</td>
<td>
@Html.DisplayFor(modelItem => item.Email)
</td>
<td>
@Html.DisplayFor(modelItem => item.Status)
</td>
<td>
@if ((await AuthorizationService.AuthorizeAsync(
User, item,
ContactOperations.Update)).Succeeded)
{
<a asp-page="./Edit" asp-route-id="@item.ContactId">Edit</a>
<text> | </text>
}
<a asp-page="./Details" asp-route-id="@item.ContactId">Details</a>

User, item,
ContactOperations.Delete)).Succeeded)
{
<text> | </text>
<a asp-page="./Delete" asp-route-id="@item.ContactId">Delete</a>
}
</td>
</tr>
}
</tbody>
</table>
WARNING
Ocultar links de usuários que não tem permissão para alterar os dados não proteger o aplicativo. Ocultar links torna o
aplicativo mais fácil de usar, exibindo links só é válidas. Os usuários podem hack gerados URLs para invocar editar e excluir
operações em dados que não possuem. A página do Razor ou controlador deve impor verificações de acesso para proteger
os dados.
Detalhes da atualização
Atualize a exibição de detalhes para que os gerentes possam aprovar ou rejeitar contatos:
@*Precedng markup omitted for brevity.*@
<dt>
@Html.DisplayNameFor(model => model.Contact.Email)
</dt>
<dd>
@Html.DisplayFor(model => model.Contact.Email)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Contact.Status)
</dt>
<dd>
@Html.DisplayFor(model => model.Contact.Status)
</dd>
</dl>
</div>
@if (Model.Contact.Status != ContactStatus.Approved)

{
User, Model.Contact, ContactOperations.Approve)).Succeeded)
{
<form style="display:inline;" method="post">
<input type="hidden" name="id" value="@Model.Contact.ContactId" />
<input type="hidden" name="status" value="@ContactStatus.Approved" />
<button type="submit" class="btn btn-xs btn-success">Approve</button>
</form>
}
}
@if (Model.Contact.Status != ContactStatus.Rejected)

{
User, Model.Contact, ContactOperations.Reject)).Succeeded)
{
<form style="display:inline;" method="post">
<input type="hidden" name="id" value="@Model.Contact.ContactId" />
<input type="hidden" name="status" value="@ContactStatus.Rejected" />
<button type="submit" class="btn btn-xs btn-success">Reject</button>
</form>
}
}
<div>
User, Model.Contact,
ContactOperations.Update)).Succeeded)
{
<a asp-page="./Edit" asp-route-id="@Model.Contact.ContactId">Edit</a>
<text> | </text>
}
</div>
Atualize o modelo de página de detalhes:

public class DetailsModel : DI_BasePageModel
{
public DetailsModel(
{
}

{
Contact = await Context.Contact.FirstOrDefaultAsync(m => m.ContactId == id);
{
return NotFound();
}
var isAuthorized = User.IsInRole(Constants.ContactManagersRole) ||

User.IsInRole(Constants.ContactAdministratorsRole);
var currentUserId = UserManager.GetUserId(User);
if (!isAuthorized
&& currentUserId != Contact.OwnerID
&& Contact.Status != ContactStatus.Approved)
{
}
return Page();
}
public async Task<IActionResult> OnPostAsync(int id, ContactStatus status)

{
var contact = await Context.Contact.FirstOrDefaultAsync(
{
return NotFound();
}
var contactOperation = (status == ContactStatus.Approved)

? ContactOperations.Approve
: ContactOperations.Reject;
var isAuthorized = await AuthorizationService.AuthorizeAsync(User, contact,

contactOperation);
{
}
contact.Status = status;
Context.Contact.Update(contact);
}
}
Adicionar ou remover um usuário a uma função

Ver esse problema para obter informações sobre:
Remoção de privilégios de um usuário. Por exemplo um silenciament um usuário em um aplicativo de bate-
papo.
Adicionando privilégios a um usuário.
Testar o aplicativo concluído

Se o aplicativo tem contatos:
Excluir todos os registros da tabela Contact .
Reinicie o aplicativo para propagar o banco de dados.
Registre um usuário para os contatos de navegação.
Uma maneira fácil de testar o aplicativo concluído é iniciar três diferentes navegadores (ou versões de janela
anônima/InPrivate). Em um navegador, registre um novo usuário (por exemplo, test@example.com ). Entrar para
cada navegador com um usuário diferente. Verifique se as seguintes operações:
Usuários registrados podem exibir todos os dados de contato aprovados.
Os usuários registrados podem editar/excluir seus próprios dados.
Os gerentes podem aprovar ou rejeitar contatos. A tela Details mostra os botões aprovar e rejeitar.
Os administradores podem Aprovar/rejeitar e editar/excluir todos os dados.
USER OPÇÕES
test@example.com Pode editar/excluir possuem dados
manager@contoso.com Podem Aprovar/rejeitar e Editar/Excluir proprietário dados
admin@contoso.com Pode editar/excluir e Aprovar/rejeitar todos os dados
Crie um contato no navegador do administrador. Copie a URL para excluir e editar a partir do contato do
administrador. Cole esses links no navegador do usuário de teste para verificar se que o usuário de teste não é
possível executar essas operações.
Criar o aplicativo inicial

Criar um aplicativo páginas Razor denominado "ContactManager"
Criar o aplicativo com contas de usuário individuais.
O nome "ContactManager" para o namespace coincida com o namespace usado no exemplo.
-uld Especifica o LocalDB em vez do SQLite
dotnet new webapp -o ContactManager -au Individual -uld
Adicione Models\Contact.cs:
Scaffold o Contact modelo.

Criar a migração inicial e atualizar o banco de dados:
dotnet aspnet-codegenerator razorpage -m Contact -udl -dc ApplicationDbContext -outDir Pages\Contacts --
dotnet ef database drop -f
dotnet ef migrations add initial
Atualizar o link de ContactManager no arquivo Pages/_Layout.cshtml:
<a asp-page="/Contacts/Index" class="navbar-brand">ContactManager</a>
Testar o aplicativo criando, editando e excluindo um contato

Adicione a SeedData de classe para o dados pasta.
Chame SeedData.Initialize de Main :

{
{

{
try
{
var context = services.GetRequiredService<ApplicationDbContext>();
SeedData.Initialize(services, "not used");
}
{
}
}
host.Run();
}

}
Se o aplicativo propagado o banco de dados de teste. Se não houver nenhuma linha no banco de dados de
contato, o método de propagação não será executado.
Recursos adicionais
Criar um aplicativo web .NET Core e o banco de dados SQL no serviço de aplicativo do Azure
Laboratório de autorização do ASP.NET Core. Este laboratório apresenta mais detalhes sobre os recursos de
segurança introduzidos neste tutorial.
Introdução à autorização no núcleo do ASP.NET
Autorização baseada em política personalizada
Convenções de autorização de páginas do Razor no
ASP.NET Core
Por Luke Latham

Uma maneira de controlar o acesso em seu aplicativo de páginas do Razor é usar as convenções de autorização na
inicialização. Essas convenções permitem que você autorizar usuários e permitir que usuários anônimos acessem
páginas individuais ou pastas de páginas. Aplicam as convenções descritas neste tópico automaticamente filtros de
autorização para controlar o acesso.
O aplicativo de exemplo usa autenticação de Cookie sem o ASP.NET Core Identity. A conta de usuário para o
usuário hipotético, Maria Rodriguez, é codificados no aplicativo. Use o nome de usuário de Email
"maria.rodriguez@contoso.com" e nenhuma senha para a entrada do usuário. O usuário é autenticado na
AuthenticateUser método na Pages/Account/Login.cshtml.cs arquivo. Em um exemplo do mundo real, o usuário
deve ser autenticado em relação a um banco de dados. Para usar o ASP.NET Core Identity, siga as diretrizes a
Introdução à identidade no ASP.NET Core tópico. Os conceitos e os exemplos mostrados neste tópico se aplicam
igualmente a aplicativos que usam o ASP.NET Core Identity.
Exigir autorização para acessar uma página

Use o AuthorizePage convenção via AddRazorPagesOptions para adicionar um AuthorizeFilter para a página no
caminho especificado:
services.AddMvc()
{
options.Conventions.AuthorizePage("/Contact");
options.Conventions.AuthorizeFolder("/Private");
options.Conventions.AllowAnonymousToPage("/Private/PublicPage");
options.Conventions.AllowAnonymousToFolder("/Private/PublicPages");
})
O caminho especificado é o caminho de mecanismo de exibição, que é o caminho relativo de raiz de páginas do
Razor sem uma extensão e que contém apenas barras "/".
Uma AuthorizePage sobrecarga estará disponível se você precisa especificar uma política de autorização.
NOTE
Uma AuthorizeFilter pode ser aplicado a uma classe de modelo de página com o [Authorize] atributo de filtro. Para
obter mais informações, consulte atributo de filtro Authorize.
Exigir autorização para acessar uma pasta de páginas

Use o AuthorizeFolder convenção via AddRazorPagesOptions para adicionar um AuthorizeFilter para todas as
páginas em uma pasta no caminho especificado:
services.AddMvc()
{
})
Razor.
Uma AuthorizeFolder sobrecarga estará disponível se você precisa especificar uma política de autorização.
Exigir autorização para acessar uma página de área

Use o AuthorizeAreaPage convenção via AddRazorPagesOptions para adicionar um AuthorizeFilter para a página
de área no caminho especificado:
options.Conventions.AuthorizeAreaPage("Identity", "/Manage/Accounts");
O nome da página é o caminho do arquivo sem uma extensão relativo ao diretório raiz páginas para a área
especificada. Por exemplo, o nome da página para o arquivo Areas/Identity/Pages/Manage/Accounts.cshtml é
contas/gerenciar/.
Uma AuthorizeAreaPage sobrecarga estará disponível se você precisa especificar uma política de autorização.
Exigir autorização para acessar uma pasta de áreas

Use o AuthorizeAreaFolder convenção via AddRazorPagesOptions para adicionar um AuthorizeFilter para todas
as áreas em uma pasta no caminho especificado:
options.Conventions.AuthorizeAreaFolder("Identity", "/Manage");
O caminho da pasta é o caminho da pasta, relativo ao diretório raiz páginas para a área especificada. Por exemplo,
o caminho da pasta para os arquivos sob áreas/identidade/páginas/gerenciar/ é /gerenciar.
Uma AuthorizeAreaFolder sobrecarga estará disponível se você precisa especificar uma política de autorização.
Permitir o acesso anônimo para uma página

Use o AllowAnonymousToPage convenção via AddRazorPagesOptions para adicionar um AllowAnonymousFilter
para uma página no caminho especificado:
services.AddMvc()
{
})
Razor sem uma extensão e que contém apenas barras "/".
Permitir o acesso anônimo para uma pasta de páginas

Use o AllowAnonymousToFolder convenção via AddRazorPagesOptions para adicionar um
AllowAnonymousFilter para todas as páginas em uma pasta no caminho especificado:
services.AddMvc()
{
})
Razor.
Observação sobre combinação autorizada e acesso anônimo

É perfeitamente válido para especificar que uma pasta de páginas exigem autorização e especificar uma página
dentro da pasta permite o acesso anônimo:
// This works.
.AuthorizeFolder("/Private").AllowAnonymousToPage("/Private/Public")
O inverso, no entanto, não é verdadeiro. Você não pode declarar uma pasta de páginas para acesso anônimo e
especificar uma página dentro de autorização:
// This doesn't work!

.AllowAnonymousToFolder("/Public").AuthorizePage("/Public/Private")
Exigir autorização na página privada não funcionará porque quando tanto o AllowAnonymousFilter e
AuthorizeFilter filtros são aplicados para a página, o AllowAnonymousFilter wins e controla o acesso.
Recursos adicionais
Provedores de modelo personalizado de página e rota de Páginas Razor
PageConventionCollection classe
Simples de autorização no núcleo do ASP.NET
No MVC é controlada por meio de AuthorizeAttribute atributo e seus vários parâmetros. Em sua forma mais
simples, aplicando o AuthorizeAttribute de atributo para um controlador ou ação limites acesse o controlador
ou ação para qualquer usuário autenticado.
Por exemplo, o código a seguir limita o acesso para o AccountController para qualquer usuário autenticado.
[Authorize]
{
public ActionResult Login()
{
}
public ActionResult Logout()

{
}
}
Se você deseja aplicar a autorização para uma ação em vez do controlador, aplique a AuthorizeAttribute de
atributo para a ação em si:

{
{
}
[Authorize]
{
}
}
Agora, somente usuários autenticados podem acessar o Logout função.

Você também pode usar o AllowAnonymous atributo para permitir o acesso por usuários não autenticados para
ações individuais. Por exemplo:
[Authorize]
{
[AllowAnonymous]
{
}

{
}
}
Isso permitiria que somente usuários autenticados para o AccountController , exceto para o Login ação, que
pode ser acessada por todos os usuários, independentemente de seu status de autenticado ou anônimo / não
autenticado.
WARNING
[AllowAnonymous] Ignora todas as declarações de autorização. Se você combinar [AllowAnonymous] e [Authorize]
atributo, o [Authorize] atributos são ignorados. Por exemplo, se você aplicar [AllowAnonymous] no nível do
controlador, qualquer [Authorize] atributos no mesmo controlador (ou em qualquer ação dentro dele) é ignorada.
Autorização baseada em função no ASP.NET Core
Quando uma identidade é criada ele pode pertencer a uma ou mais funções. Por exemplo, Tracy pode pertencer
às funções de administrador e usuário, embora Scott só pode pertencer à função de usuário. Como essas funções
são criadas e gerenciadas dependem do repositório de backup do processo de autorização. As funções são
expostas para o desenvolvedor por meio de IsInRole método na ClaimsPrincipal classe.
IMPORTANT
Este tópico não se aplica a Páginas Razor. Dá suporte a páginas do Razor IPageFilter e IAsyncPageFilter. Para obter mais
informações, confira Métodos de filtro para Páginas Razor.
Adicionar verificações de função

Verificações de autorização baseado em função são declarativas—o desenvolvedor incorpora-los dentro de seu
código, em relação a um controlador ou uma ação dentro de um controlador, especificando as funções que o
usuário atual deve ser um membro de acessar o recurso solicitado.
Por exemplo, o código a seguir limita o acesso a quaisquer ações sobre o AdministrationController aos usuários
que são membros do Administrator função:
[Authorize(Roles = "Administrator")]
public class AdministrationController : Controller
{
}
Você pode especificar várias funções como uma lista separada por vírgulas:
[Authorize(Roles = "HRManager,Finance")]
public class SalaryController : Controller
{
}
Esse controlador seria apenas ser acessado por usuários que são membros do HRManager função ou o Finance
função.
Se você aplicar vários atributos de um usuário ao acessar deve ser um membro de todas as funções especificadas;
o exemplo a seguir requer que um usuário deve ser um membro de ambos os PowerUser e ControlPanelUser
função.
[Authorize(Roles = "PowerUser")]
[Authorize(Roles = "ControlPanelUser")]
public class ControlPanelController : Controller
{
}
Você pode limitar o acesso ainda mais aplicando atributos de autorização de função adicionais em nível de ação:
[Authorize(Roles = "Administrator, PowerUser")]
{
public ActionResult SetTime()
{
}
[Authorize(Roles = "Administrator")]
public ActionResult ShutDown()
{
}
}
Nos membros de trecho de código anterior do Administrator função ou o PowerUser função pode acessar o
controlador e o SetTime ação, mas somente os membros dos Administrator função pode acessar o ShutDown
ação.
Você também pode bloquear um controlador mas permitir o acesso anônimo, não autenticado a ações individuais.
[Authorize]
{
public ActionResult SetTime()
{
}
[AllowAnonymous]
{
}
}
Verificações de função baseada em política

Requisitos da função também podem ser expressos usando a nova sintaxe de diretiva, em que um desenvolvedor
registra uma política na inicialização como parte da configuração do serviço de autorização. Isso normalmente
ocorre ConfigureServices() em seu Startup.cs arquivo.

{
services.AddMvc();
services.AddAuthorization(options =>
{
options.AddPolicy("RequireAdministratorRole", policy => policy.RequireRole("Administrator"));
});
}
As políticas são aplicadas usando o Policy propriedade no AuthorizeAttribute atributo:
[Authorize(Policy = "RequireAdministratorRole")]
public IActionResult Shutdown()
{
return View();
}
Se você deseja especificar várias funções permitidas em um requisito, você pode especificá-los como parâmetros
para o RequireRole método:
options.AddPolicy("ElevatedRights", policy =>
policy.RequireRole("Administrator", "PowerUser", "BackupAdministrator"));
Este exemplo autoriza usuários que pertencem à Administrator , PowerUser ou BackupAdministrator funções.
Autorização baseada em declarações no núcleo do
ASP.NET
Quando uma identidade é criada ele pode ser atribuído uma ou mais declarações emitidas por um terceiro
confiável. Uma declaração é um par nome-valor que representa o assunto, não que a entidade pode fazer. Por
exemplo, você pode ter de motorista uma carteira, emitida por uma autoridade de licença de um local. Licença do
driver tem sua data de nascimento. Nesse caso seria o nome da declaração DateOfBirth , o valor da declaração
seria sua data de nascimento, por exemplo 8th June 1970 e o emissor de um autoridade de licença. Autorização
baseada em declarações, em sua forma mais simples, verifica o valor de uma declaração e permite o acesso a um
recurso com base no valor. Por exemplo, se você quiser que o processo de autorização de acesso para uma
sociedade noite poderia ser:
A analista de segurança de porta deve avaliar o valor da sua data de nascimento declaração e se elas têm
confiança do emissor (de um autoridade de licença) antes de conceder a que você acessar.
Uma identidade pode conter várias declarações com vários valores e pode conter várias declarações do mesmo
tipo.
Adicionar declarações verificações

Declaração de verificações de autorização com base são declarativas - o desenvolvedor incorpora dentro de seu
código, em relação a um controlador ou uma ação dentro de um controlador, especificando que o usuário atual
deve ter, e, opcionalmente, o valor de declaração deve conter para acessar o recurso solicitado. Declarações de
requisitos são baseada em política, o desenvolvedor deve criar e registrar uma política de expressar os requisitos
de declarações.
O tipo mais simples de política procura a presença de uma declaração de declaração e não verifica o valor.
Primeiro você precisa criar e registrar a política. Isso ocorre como parte da configuração do serviço de
autorização, que normalmente faz parte do ConfigureServices() no seu Startup.cs arquivo.

{
services.AddMvc();
{
options.AddPolicy("EmployeeOnly", policy => policy.RequireClaim("EmployeeNumber"));
});
}
Nesse caso o EmployeeOnly política verifica a presença de um EmployeeNumber de declaração de identidade atual.
Em seguida, aplique a política usando o Policy propriedade no AuthorizeAttribute atributo para especificar o
nome da política
[Authorize(Policy = "EmployeeOnly")]
public IActionResult VacationBalance()
{
return View();
}
O AuthorizeAttribute atributo pode ser aplicado a um controlador de inteiro, nesta instância, somente a política
de correspondência de identidades terão acesso permitidas para qualquer ação no controlador.
public class VacationController : Controller
{
public ActionResult VacationBalance()
{
}
}
Se você tiver um controlador que é protegido pelo AuthorizeAttribute de atributo, mas deseja permitir acesso
anônimo a ações específicas que você aplicar o AllowAnonymousAttribute atributo.
public class VacationController : Controller
{
public ActionResult VacationBalance()
{
}
[AllowAnonymous]
public ActionResult VacationPolicy()
{
}
}
A maioria das declarações vem com um valor. Você pode especificar uma lista de valores permitido ao criar a
política. O exemplo a seguir seria êxito apenas para os funcionários cujo número de funcionário foi 1, 2, 3, 4 ou 5.

{
services.AddMvc();
{
options.AddPolicy("Founders", policy =>
policy.RequireClaim("EmployeeNumber", "1", "2", "3", "4", "5"));
});
}
Adicionar uma verificação de declaração genérico

Se o valor da declaração não é um valor único ou uma transformação é necessária, use RequireAssertion. Para
obter mais informações, consulte usando um func para atender a uma política de.
Vários avaliação de política

Se você aplicar várias políticas para um controlador ou ação, todas as políticas devem passar antes que o acesso é
concedido. Por exemplo:
public class SalaryController : Controller
{
public ActionResult Payslip()
{
}
[Authorize(Policy = "HumanResources")]
public ActionResult UpdateSalary()
{
}
}
No exemplo acima qualquer identidade que atende a EmployeeOnly política pode acessar o Payslip ação como
essa política é aplicada no controlador. No entanto para chamar o UpdateSalary ação de identidade deve ser
atendidos ambos o EmployeeOnly política e o HumanResources política.
Se você quiser políticas mais complicadas, como colocar uma data de nascimento declaração, calcular uma idade
dele e verificando a idade for 21 ou anterior, você precisa gravar manipuladores de política personalizada.
Autorização baseada em política no ASP.NET Core
Nos bastidores, autorização baseada em função e autorização baseada em declarações usam um requisito, um
manipulador de requisito e uma política de pré-configurada. Esses blocos de construção oferecem suporte a
expressão de avaliações de autorização no código. O resultado é uma estrutura de autorização mais
sofisticados, reutilizáveis e testáveis.
Uma política de autorização consiste em um ou mais requisitos. Ele é registrado como parte da configuração do
serviço de autorização no Startup.ConfigureServices método:

{
services.AddMvc();
{
options.AddPolicy("AtLeast21", policy =>
policy.Requirements.Add(new MinimumAgeRequirement(21)));
});
}
No exemplo anterior, uma política de "AtLeast21" é criada. Ele tem um requisito—de idade mínima, que é
fornecida como um parâmetro para o requisito.
As políticas são aplicadas usando o [Authorize] atributo com o nome da política. Por exemplo:
[Authorize(Policy = "AtLeast21")]
public class AlcoholPurchaseController : Controller
{
public IActionResult Login() => View();
public IActionResult Logout() => View();

}
Requisitos
Um requisito de autorização é uma coleção de parâmetros de dados que uma política pode usar para avaliar a
entidade de segurança do usuário atual. Em nossa política de "AtLeast21", o requisito é um único parâmetro—a
idade mínima. Implementa um requisito IAuthorizationRequirement, que é uma interface de marcador vazio.
Um requisito de idade mínima com parâmetros pode ser implementado da seguinte maneira:
public class MinimumAgeRequirement : IAuthorizationRequirement

{
public int MinimumAge { get; private set; }
public MinimumAgeRequirement(int minimumAge)

{
MinimumAge = minimumAge;
}
}
NOTE
Um requisito não precisa ter dados ou propriedades.
Manipuladores de autorização
Um manipulador de autorização é responsável pela avaliação de propriedades de um requisito. O manipulador
de autorização avalia os requisitos em relação a um fornecido AuthorizationHandlerContext para determinar se
o acesso é permitido.
Pode ter um requisito vários manipuladores. Um manipulador pode herdar
AuthorizationHandler<TRequirement >, onde TRequirement é o requisito para ser tratada. Como alternativa,
um manipulador pode implementar IAuthorizationHandler para lidar com mais de um tipo de requisito.
Usar um manipulador de um requisito
Este é um exemplo de uma relação um para um no qual um manipulador de idade mínima utiliza um requisito:
using PoliciesAuthApp1.Services.Requirements;
using System;
using System.Security.Claims;
public class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>

{
protected override Task HandleRequirementAsync(AuthorizationHandlerContext context,
MinimumAgeRequirement requirement)
{
if (!context.User.HasClaim(c => c.Type == ClaimTypes.DateOfBirth &&
c.Issuer == "http://contoso.com"))
{
//TODO: Use the following if targeting a version of
//.NET Framework older than 4.6:
// return Task.FromResult(0);
}
var dateOfBirth = Convert.ToDateTime(

context.User.FindFirst(c => c.Type == ClaimTypes.DateOfBirth &&
c.Issuer == "http://contoso.com").Value);
int calculatedAge = DateTime.Today.Year - dateOfBirth.Year;

if (dateOfBirth > DateTime.Today.AddYears(-calculatedAge))
{
calculatedAge--;
}
if (calculatedAge >= requirement.MinimumAge)

{
}

}
}
O código anterior determina se a entidade de usuário atual tem uma data de nascimento de declaração que foi
emitido por um emissor confiável e conhecido. A autorização não pode ocorrer quando a declaração está
ausente, caso em que uma tarefa concluída é retornada. Quando uma declaração estiver presente, a duração do
usuário é calculada. Se o usuário atende a idade mínima definida pelo requisito de autorização é considerada
bem-sucedido. Quando a autorização for bem-sucedido, context.Succeed é invocado com o requisito satisfeito
como seu único parâmetro.
Usar um manipulador para várias necessidades
Este é um exemplo de uma relação um-para-muitos em que um manipulador de permissão utiliza três
requisitos:
public class PermissionHandler : IAuthorizationHandler

{
public Task HandleAsync(AuthorizationHandlerContext context)
{
var pendingRequirements = context.PendingRequirements.ToList();
foreach (var requirement in pendingRequirements)

{
if (requirement is ReadPermission)
{
if (IsOwner(context.User, context.Resource) ||
IsSponsor(context.User, context.Resource))
{
}
}
else if (requirement is EditPermission ||
requirement is DeletePermission)
{
if (IsOwner(context.User, context.Resource))
{
}
}
}

}
private bool IsOwner(ClaimsPrincipal user, object resource)

{
return true;
}
private bool IsSponsor(ClaimsPrincipal user, object resource)

{
return true;
}
}
O código anterior atravessa PendingRequirements—uma propriedade que contém requisitos não marcada
como bem-sucedido. Se o usuário tem permissão de leitura, ele deve ser um proprietário ou um patrocinador
para acessar o recurso solicitado. Se o usuário editar ou excluir permissão, deve ser um proprietário para
acessar o recurso solicitado. Quando a autorização for bem-sucedido, context.Succeed é invocado com o
requisito satisfeito como seu único parâmetro.
Registro do manipulador
Manipuladores são registrados na coleção de serviços durante a configuração. Por exemplo:
{
services.AddMvc();
{
options.AddPolicy("AtLeast21", policy =>
policy.Requirements.Add(new MinimumAgeRequirement(21)));
});
services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();
}
Cada manipulador é adicionado à coleção de serviços invocando

services.AddSingleton<IAuthorizationHandler, YourHandlerClass>(); .
O que deve retornar um manipulador?

Observe que o Handle método o exemplo manipulador não retorna nenhum valor. Como é um status de êxito
ou falha indicado?
Um manipulador indica êxito chamando context.Succeed(IAuthorizationRequirement requirement) ,
passando o requisito de que foi validada com êxito.
Um manipulador não precisa lidar com falhas em geral, como outros manipuladores para o mesmo
requisito podem ser bem-sucedida.
Para garantir a falha, mesmo se outros manipuladores de requisito tenha êxito, chame context.Fail .
Quando definido como false , o InvokeHandlersAfterFailure propriedade (disponível no ASP.NET Core 1.1 e
posterior) reduz a execução de manipuladores quando context.Fail é chamado. InvokeHandlersAfterFailure o
padrão será a true , caso em que todos os manipuladores são chamados. Isso permite que os requisitos
produzir efeitos colaterais, como o registro em log, que sempre ocorrem mesmo se context.Fail foi chamado
no manipulador de outro.
Por que eu quero vários manipuladores para um requisito?

Em casos onde você deseja evaluation para estar em um ou base, implementar vários manipuladores para um
requisito. Por exemplo, a Microsoft tem portas que apenas abrir com cartões de chave. Se você deixar o seu
cartão de chave em casa, o recepcionista imprime uma etiqueta temporária e abre a porta para você. Nesse
cenário, você teria um requisito, BuildingEntry, mas vários manipuladores, cada um deles examinando um
requisito.
BuildingEntryRequirement.cs
public class BuildingEntryRequirement : IAuthorizationRequirement

{
}
BadgeEntryHandler.cs
public class BadgeEntryHandler : AuthorizationHandler<BuildingEntryRequirement>

{
BuildingEntryRequirement requirement)
{
if (context.User.HasClaim(c => c.Type == ClaimTypes.BadgeId &&
c.Issuer == "http://microsoftsecurity"))
{
}

}
}
TemporaryStickerHandler.cs
public class TemporaryStickerHandler : AuthorizationHandler<BuildingEntryRequirement>

{
BuildingEntryRequirement requirement)
{
if (context.User.HasClaim(c => c.Type == ClaimTypes.TemporaryBadgeId &&
c.Issuer == "https://microsoftsecurity"))
{
// We'd also check the expiration date on the sticker.
}

}
}
Certifique-se de que ambos os manipuladores são registrado. Se o manipulador é bem-sucedida quando uma
política avalia o BuildingEntryRequirement , a avaliação de política for bem-sucedida.
Usando uma função para atender a uma política

Pode haver situações nas quais que atendem a uma política é simple de expressar em código. É possível
fornecer uma Func<AuthorizationHandlerContext, bool> ao configurar a política com o RequireAssertion criador
de políticas.
Por exemplo, o anterior BadgeEntryHandler poderia ser reescrito da seguinte maneira:
{
options.AddPolicy("BadgeEntry", policy =>
policy.RequireAssertion(context =>
context.User.HasClaim(c =>
(c.Type == ClaimTypes.BadgeId ||
c.Type == ClaimTypes.TemporaryBadgeId) &&
c.Issuer == "https://microsoftsecurity")));
});
Acessando o contexto de solicitação do MVC em manipuladores

O HandleRequirementAsync método implementar um manipulador de autorização tem dois parâmetros: um
AuthorizationHandlerContext e o TRequirement manipulada. Estruturas como MVC ou Jabbr serão livres para
adicionar qualquer objeto para o Resource propriedade o AuthorizationHandlerContext para passar
informações adicionais.
Por exemplo, o MVC passa uma instância de AuthorizationFilterContext no Resource propriedade. Esta
propriedade fornece acesso a HttpContext , RouteData e tudo pessoa forneceu MVC e páginas Razor.
O uso do Resource é de propriedade específicos da estrutura. Usando informações de Resource propriedade
limita suas políticas de autorização para estruturas específicas. Você deve converter o Resource propriedade
usando o as palavra-chave e, em seguida, confirme a conversão tenha êxito para garantir que seu código não
falha com um InvalidCastException quando executado em outras estruturas:
// Requires the following import:

// using Microsoft.AspNetCore.Mvc.Filters;
if (context.Resource is AuthorizationFilterContext mvcContext)
{
// Examine MVC-specific things like routing data.
}
Provedores de política de autorização personalizados
usando IAuthorizationPolicyProvider no ASP.NET
Core
Por Mike Rousos

Normalmente ao usar baseado em políticas de autorização, as políticas são registradas por meio da chamada
AuthorizationOptions.AddPolicy como parte da configuração do serviço de autorização. Em alguns cenários, pode
não ser possível (ou desejável) para registrar todas as políticas de autorização dessa maneira. Nesses casos, você
pode usar um personalizado IAuthorizationPolicyProvider para controlar como as políticas de autorização são
fornecidas.
Exemplos de cenários onde um personalizado IAuthorizationPolicyProvider podem ser úteis incluem:
Usando um serviço externo para fornecer a avaliação da política.
Usando uma grande variedade de diretivas (para números de sala de diferentes ou com as idades, por
exemplo), portanto, não faz sentido adicionar cada política de autorização individuais com um
AuthorizationOptions.AddPolicy chamar.
Criação de políticas em tempo de execução com base nas informações em uma fonte de dados externa (como
um banco de dados) ou determinar os requisitos de autorização dinamicamente por meio de outro mecanismo.
Exibir ou baixar o código de exemplo do repositório do GitHub aspnet/AuthSamples. Baixe o arquivo ZIP do
repositório aspnet/AuthSamples. Descompacte o AuthSamples Master arquivo. Navegue até a
amostras/CustomPolicyProvider pasta do projeto.
Personalizar a recuperação da política

Aplicativos ASP.NET Core usam uma implementação do IAuthorizationPolicyProvider interface para recuperar as
políticas de autorização. Por padrão, DefaultAuthorizationPolicyProvider registrado e usado.
DefaultAuthorizationPolicyProvider Retorna as políticas do AuthorizationOptions fornecidas em um
IServiceCollection.AddAuthorization chamar.
Você pode personalizar esse comportamento, registrando um diferentes IAuthorizationPolicyProvider

implementação do aplicativo injeção de dependência contêiner.
O IAuthorizationPolicyProvider interface contém duas APIs:
GetPolicyAsync retorna uma política de autorização para um determinado nome.
GetDefaultPolicyAsync retorna a política de autorização padrão (a política usada para [Authorize] atributos
sem uma política especificada).
Implementando essas duas APIs, você pode personalizar como as políticas de autorização são fornecidas.
Parametrizadas autorizar o exemplo de atributo

Um cenário em que IAuthorizationPolicyProvider é útil é a habilitação do personalizado [Authorize] atributos
cujos requisitos dependem de um parâmetro. Por exemplo, na autorização baseada em política documentação,
uma com base em idade ("AtLeast21") política foi usada como um exemplo. Se as ações de controlador diferente
em um aplicativo devem ser disponibilizadas para os usuários do diferentes há séculos, pode ser útil ter muitas
políticas diferentes com base em idade. Em vez de registrar todas as diferentes com base em idade políticas que o
aplicativo será necessário em AuthorizationOptions , você pode gerar as políticas dinamicamente com um
personalizado IAuthorizationPolicyProvider . Para tornar o uso de políticas mais fácil, você pode anotar as ações
com o atributo de autorização personalizado, como [MinimumAgeAuthorize(20)] .
Atributos de autorização personalizada

Políticas de autorização são identificadas por seus nomes. Personalizado MinimumAgeAuthorizeAttribute descrito
anteriormente, precisa mapear argumentos em uma cadeia de caracteres que pode ser usada para recuperar a
política de autorização correspondente. Você pode fazer isso, derivando de AuthorizeAttribute e fazer a Age
quebra automática de propriedade a AuthorizeAttribute.Policy propriedade.
internal class MinimumAgeAuthorizeAttribute : AuthorizeAttribute

{
const string POLICY_PREFIX = "MinimumAge";
public MinimumAgeAuthorizeAttribute(int age) => Age = age;
// Get or set the Age property by manipulating the underlying Policy property
public int Age
{
get
{
if (int.TryParse(Policy.Substring(POLICY_PREFIX.Length), out var age))
{
return age;
}
return default(int);
}
set
{
Policy = $"{POLICY_PREFIX}{value.ToString()}";
}
}
}
Esse tipo de atributo tem um Policy cadeia de caracteres com base no prefixo embutido em código (
"MinimumAge" ) e um número inteiro passado por meio do construtor.
Você pode aplicá-lo às ações da mesma maneira que outras Authorize atributos, exceto que assume um inteiro
como um parâmetro.
[MinimumAgeAuthorize(10)]
public IActionResult RequiresMinimumAge10()
IAuthorizationPolicyProvider personalizado
Personalizado MinimumAgeAuthorizeAttribute facilita a políticas de autorização da solicitação para qualquer idade
mínima desejada. O próximo problema a resolver é verificar se as políticas de autorização estão disponíveis para
todas as idades diferentes. É aí que um IAuthorizationPolicyProvider é útil.
Ao usar MinimumAgeAuthorizationAttribute , os nomes de política de autorização seguirá o padrão
"MinimumAge" + Age , então personalizado IAuthorizationPolicyProvider deve gerar diretivas de autorização por:
A idade do nome da política de análise.

Usando AuthorizationPolicyBuilder para criar um novo AuthorizationPolicy
Adicionar requisitos para a política com base na idade com AuthorizationPolicyBuilder.AddRequirements . Em
outros cenários, você pode usar RequireClaim , RequireRole , ou RequireUserName em vez disso.
internal class MinimumAgePolicyProvider : IAuthorizationPolicyProvider

{
const string POLICY_PREFIX = "MinimumAge";
// Policies are looked up by string name, so expect 'parameters' (like age)

// to be embedded in the policy names. This is abstracted away from developers
// by the more strongly-typed attributes derived from AuthorizeAttribute
// (like [MinimumAgeAuthorize()] in this sample)
public Task<AuthorizationPolicy> GetPolicyAsync(string policyName)
{
if (policyName.StartsWith(POLICY_PREFIX, StringComparison.OrdinalIgnoreCase) &&
int.TryParse(policyName.Substring(POLICY_PREFIX.Length), out var age))
{
var policy = new AuthorizationPolicyBuilder();
policy.AddRequirements(new MinimumAgeRequirement(age));
return Task.FromResult(policy.Build());
}
return Task.FromResult<AuthorizationPolicy>(null);
}
}
Vários provedores de política de autorização

Quando usar custom IAuthorizationPolicyProvider implementações, tenha em mente que o ASP.NET Core usa
apenas uma instância de IAuthorizationPolicyProvider . Se um provedor personalizado não é capaz de fornecer
políticas de autorização para todos os nomes de política, ele deve fazer fallback para um provedor de backup.
Nomes de política podem incluir aqueles que vêm de uma política padrão para [Authorize] atributos sem um
nome.
Por exemplo, considere que um aplicativo precisar de políticas personalizadas de idade e recuperação de política
baseada em função mais tradicional. Esse aplicativo poderia usar um provedor de diretivas de autorização
personalizada que:
Tenta analisar nomes de política.
Chamadas para um provedor de política diferente (como DefaultAuthorizationPolicyProvider ) se o nome da
política não contiver uma idade.
Política padrão
Além de fornecer políticas de autorização nomeado, um personalizado IAuthorizationPolicyProvider precisa
implementar GetDefaultPolicyAsync para fornecer uma política de autorização para [Authorize] atributos sem um
nome de política especificado.
Em muitos casos, esse atributo de autorização requer apenas um usuário autenticado, portanto, você pode fazer a
diretiva necessária com uma chamada para RequireAuthenticatedUser :
public Task<AuthorizationPolicy> GetDefaultPolicyAsync() =>

Task.FromResult(new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build());
Assim como acontece com todos os aspectos de um personalizado IAuthorizationPolicyProvider , você pode
personalizá-lo, conforme necessário. Em alguns casos:
Políticas de autorização padrão não podem ser usadas.
Recuperando a política padrão pode ser designado como um fallback IAuthorizationPolicyProvider .
Use um IAuthorizationPolicyProvider personalizado
Para usar políticas personalizadas de um IAuthorizationPolicyProvider , você deve:
Registrar apropriado AuthorizationHandler tipos de injeção de dependência (descrito na autorização baseada
em política), assim como acontece com todos os cenários de autorização baseada em política.
Registrar personalizado IAuthorizationPolicyProvider tipo na coleção de serviço de injeção de dependência do
aplicativo (em Startup.ConfigureServices ) para substituir o provedor de política padrão.
services.AddSingleton<IAuthorizationPolicyProvider, MinimumAgePolicyProvider>();
Um personalizado completo IAuthorizationPolicyProvider exemplo está disponível na repositório do GitHub

aspnet/AuthSamples.
Injeção de dependência em manipuladores de
requisito no ASP.NET Core
Manipuladores de autorização devem ser registrados na coleção durante a configuração do serviço (usando
injeção de dependência).
Suponha que você tenha um repositório de regras que você queira avaliar dentro de um manipulador de
autorização e esse repositório foi registrado na coleção de serviço. A autorização será resolver e inseri-los em seu
construtor.
Por exemplo, se você quiser usar o ASP. NET do log a infraestrutura que você deseja injetar ILoggerFactory em
seu manipulador. Um manipulador desse tipo pode parecer com:
public class LoggingAuthorizationHandler : AuthorizationHandler<MyRequirement>

{
ILogger _logger;
public LoggingAuthorizationHandler(ILoggerFactory loggerFactory)

{
_logger = loggerFactory.CreateLogger(this.GetType().FullName);
}
protected override Task HandleRequirementAsync(AuthorizationHandlerContext context, MyRequirement

requirement)
{
_logger.LogInformation("Inside my handler");
// Check if the requirement is fulfilled.
}
}
Você deve registrar o manipulador com services.AddSingleton() :
services.AddSingleton<IAuthorizationHandler, LoggingAuthorizationHandler>();
Uma instância do manipulador será criado quando o aplicativo for iniciado e será de DI injetar registrado
ILoggerFactory em seu construtor.
NOTE
Manipuladores que usam o Entity Framework não devem ser registrados como singletons.
Autorização baseada em recursos no ASP.NET Core
Estratégia de autorização depende do recurso que está sendo acessado. Considere um documento que tem uma
propriedade de autor. Somente o autor tem permissão para atualizar o documento. Consequentemente, o
documento deve ser recuperado do armazenamento de dados antes que a avaliação de autorização pode ocorrer.
Avaliação de atributo ocorre antes da vinculação de dados e antes da execução do manipulador de página ou ação
que carrega o documento. Por esses motivos, a autorização declarativa com um [Authorize] atributo não serão
suficientes. Em vez disso, você pode invocar um método de autorização personalizada—um estilo conhecido como
autorização imperativa.
Criar um aplicativo ASP.NET Core com os dados de usuário protegidos por autorização contém um aplicativo de
exemplo que usa a autorização baseada em recursos.
Usar a autorização obrigatória

Autorização é implementada como um IAuthorizationService de serviço e é registrado na coleção de serviço
dentro de Startup classe. O serviço é disponibilizado por meio injeção de dependência para manipuladores de
página ou de ações.
public class DocumentController : Controller

{
private readonly IAuthorizationService _authorizationService;
private readonly IDocumentRepository _documentRepository;
public DocumentController(IAuthorizationService authorizationService,

IDocumentRepository documentRepository)
{
_authorizationService = authorizationService;
_documentRepository = documentRepository;
}
IAuthorizationService tem dois AuthorizeAsync sobrecargas de método: uma aceitando o recurso e o nome da
política e a outra aceitando o recurso e uma lista de requisitos para avaliar.
ASP.NET Core 2.x
ASP.NET Core 1.x
Task<AuthorizationResult> AuthorizeAsync(ClaimsPrincipal user,

object resource,
IEnumerable<IAuthorizationRequirement> requirements);
Task<AuthorizationResult> AuthorizeAsync(ClaimsPrincipal user,
object resource,
string policyName);
O exemplo a seguir, o recurso a ser protegido é carregado em um personalizado Document objeto. Um

AuthorizeAsync sobrecarga é invocada para determinar se o usuário atual tem permissão para editar o
documento. Uma política de autorização personalizada "EditPolicy" é acrescentada a uma decisão. Ver autorização
de baseado em políticas personalizadas para obter mais informações sobre como criar políticas de autorização.
NOTE
O código a seguir exemplos pressupõem que a autenticação foi executada e o conjunto de User propriedade.
ASP.NET Core 2.x

ASP.NET Core 1.x
public async Task<IActionResult> OnGetAsync(Guid documentId)

{
Document = _documentRepository.Find(documentId);
if (Document == null)
{
return new NotFoundResult();
}
var authorizationResult = await _authorizationService

.AuthorizeAsync(User, Document, "EditPolicy");
if (authorizationResult.Succeeded)
{
return Page();
}
else if (User.Identity.IsAuthenticated)
{
return new ForbidResult();
}
else
{
}
}
Escrever um Gerenciador de recursos

Escrevendo um manipulador para a autorização baseada em recursos não é muito diferente escrevendo um
manipulador de requisitos simples. Criar uma classe de requisito personalizado e implementar uma classe de
manipulador de requisito. A classe de manipulador Especifica o requisito e o tipo de recurso. Por exemplo, uma
utilização de manipulador uma SameAuthorRequirement requisito e um Document recursos será semelhante ao
seguinte:
ASP.NET Core 2.x
ASP.NET Core 1.x
public class DocumentAuthorizationHandler :
AuthorizationHandler<SameAuthorRequirement, Document>
{
SameAuthorRequirement requirement,
Document resource)
{
if (context.User.Identity?.Name == resource.Author)
{
}
}
}
public class SameAuthorRequirement : IAuthorizationRequirement { }
Registrar o requisito e o manipulador no Startup.ConfigureServices método:
services.AddMvc();
{
options.AddPolicy("EditPolicy", policy =>
policy.Requirements.Add(new SameAuthorRequirement()));
});
services.AddSingleton<IAuthorizationHandler, DocumentAuthorizationHandler>();
services.AddSingleton<IAuthorizationHandler, DocumentAuthorizationCrudHandler>();
services.AddScoped<IDocumentRepository, DocumentRepository>();
Requisitos operacionais
Se você estiver fazendo decisões com base nos resultados de operações CRUD (Create, Read, Update, Delete), use
o OperationAuthorizationRequirement classe auxiliar. Essa classe permite que você escreva um único manipulador
em vez de uma classe individual para cada tipo de operação. Para usá-lo, forneça alguns nomes de operação:
public static class Operations

{
public static OperationAuthorizationRequirement Create =
new OperationAuthorizationRequirement { Name = nameof(Create) };
public static OperationAuthorizationRequirement Read =
new OperationAuthorizationRequirement { Name = nameof(Read) };
public static OperationAuthorizationRequirement Update =
new OperationAuthorizationRequirement { Name = nameof(Update) };
public static OperationAuthorizationRequirement Delete =
new OperationAuthorizationRequirement { Name = nameof(Delete) };
}
O manipulador é implementado da seguinte maneira, usando um OperationAuthorizationRequirement requisito e

um Document recursos:
ASP.NET Core 2.x
ASP.NET Core 1.x
public class DocumentAuthorizationCrudHandler :
AuthorizationHandler<OperationAuthorizationRequirement, Document>
{
Document resource)
{
if (context.User.Identity?.Name == resource.Author &&
requirement.Name == Operations.Read.Name)
{
}
}
}
O manipulador anterior valida a operação usando o recurso, a identidade do usuário e o requisito Name
propriedade.
Para chamar um manipulador de recursos operacionais, especifique a operação ao invocar AuthorizeAsync em seu
manipulador de página ou ação. O exemplo a seguir determina se o usuário autenticado tem permissão para exibir
o documento.
NOTE
O código a seguir exemplos pressupõem que a autenticação foi executada e o conjunto de User propriedade.
ASP.NET Core 2.x

ASP.NET Core 1.x
public async Task<IActionResult> OnGetAsync(Guid documentId)

{
Document = _documentRepository.Find(documentId);
if (Document == null)
{
return new NotFoundResult();
}
var authorizationResult = await _authorizationService

.AuthorizeAsync(User, Document, Operations.Read);
if (authorizationResult.Succeeded)
{
return Page();
}
else if (User.Identity.IsAuthenticated)
{
return new ForbidResult();
}
else
{
}
}
Se a autorização for bem-sucedida, a página para exibir o documento é retornada. Se falhar de autorização, mas o
usuário é autenticado, o retorno de ForbidResult informa qualquer middleware de autenticação que houve falha
na autorização. Um ChallengeResult é retornado quando a autenticação deve ser executada. Para clientes de
navegador interativo, ele pode ser apropriado redirecionar o usuário para uma página de logon.
Autorização baseada em modo de exibição no
ASP.NET Core MVC
Um desenvolvedor geralmente deseja mostrar, ocultar ou modificar uma interface do usuário com base na
identidade do usuário atual. Você pode acessar o serviço de autorização em modos de exibição do MVC por meio
injeção de dependência. Para injetar o serviço de autorização em um modo de exibição do Razor, use o @inject
diretiva:
@using Microsoft.AspNetCore.Authorization
@inject IAuthorizationService AuthorizationService
Se você quiser que o serviço de autorização em cada exibição, coloque o @inject diretiva na viewimports. cshtml
arquivo do exibições directory. Para obter mais informações, consulte Injeção de dependência em exibições.
Usar o serviço de autorização injetado para invocar AuthorizeAsync exatamente da mesma forma que você
poderia verificar durante autorização baseada em recursos:
ASP.NET Core 2.x
ASP.NET Core 1.x
@if ((await AuthorizationService.AuthorizeAsync(User, "PolicyName")).Succeeded)

{
<p>This paragraph is displayed because you fulfilled PolicyName.</p>
}
Em alguns casos, o recurso será o seu modelo de exibição. Invocar AuthorizeAsync exatamente da mesma forma
que você poderia verificar durante autorização baseada em recursos:
ASP.NET Core 2.x
ASP.NET Core 1.x
@if ((await AuthorizationService.AuthorizeAsync(User, Model, Operations.Edit)).Succeeded)

{
<p><a class="btn btn-default" role="button"
href="@Url.Action("Edit", "Document", new { id = Model.Id })">Edit</a></p>
}
No código anterior, o modelo é passado como um recurso de que avaliação da política deve levar em consideração.
WARNING
Não confie na alternância de visibilidade de elementos de interface do usuário do seu aplicativo como a verificação de
autorização única. Ocultar um elemento de interface do usuário pode completamente impede o acesso a sua ação de
controlador associado. Por exemplo, considere o botão no trecho de código anterior. Um usuário pode invocar o Edit é de
URL do método de ação, se ele ou ela sabe que o recurso relativo /Document/Edit/1. Por esse motivo, o Edit método de
ação deve realizar sua própria verificação de autorização.
Autorizar com um esquema específico no ASP.NET
Core
Em alguns cenários, como aplicativos de página única (SPAs), é comum usar vários métodos de autenticação. Por
exemplo, o aplicativo pode usar a autenticação baseada em cookies para fazer logon e autenticação do portador
do JWT para solicitações de JavaScript. Em alguns casos, o aplicativo pode ter várias instâncias de um
manipulador de autenticação. Por exemplo, dois manipuladores de cookie em que um contém uma identidade
básica e o outro é criado quando a autenticação multifator (MFA) foi acionada. MFA pode ser acionado porque o
usuário solicitou uma operação que exige segurança extra.
ASP.NET Core 2.x
ASP.NET Core 1.x
Um esquema de autenticação é chamado quando o serviço de autenticação é configurado durante a autenticação.
Por exemplo:

{
.AddCookie(options => {
options.LoginPath = "/Account/Unauthorized/";
options.AccessDeniedPath = "/Account/Forbidden/";
})
.AddJwtBearer(options => {
options.Audience = "http://localhost:5001/";
options.Authority = "http://localhost:5000/";
});
No código anterior, foram adicionados dois manipuladores de autenticação: um para cookies e outro para o
portador.
NOTE
Especificar o esquema padrão resulta no HttpContext.User propriedade sendo definida como essa identidade. Se esse
comportamento não for desejado, desabilitá-lo, invocando o formulário sem parâmetros de AddAuthentication .
Selecionar o esquema com o atributo Authorize

No ponto de autorização, o aplicativo indica o manipulador a ser usado. Selecione o manipulador com a qual o
aplicativo autorizará passando uma lista delimitada por vírgulas de esquemas de autenticação para [Authorize] .
O [Authorize] atributo especifica o esquema de autenticação ou esquemas de usar, independentemente de um
padrão é configurado. Por exemplo:
ASP.NET Core 2.x
ASP.NET Core 1.x
[Authorize(AuthenticationSchemes = AuthSchemes)]
public class MixedController : Controller
// Requires the following imports:
// using Microsoft.AspNetCore.Authentication.Cookies;
// using Microsoft.AspNetCore.Authentication.JwtBearer;
private const string AuthSchemes =
CookieAuthenticationDefaults.AuthenticationScheme + "," +
JwtBearerDefaults.AuthenticationScheme;
No exemplo anterior, o cookie e o portador manipuladores execute em tenham a oportunidade de criar e

acrescentar uma identidade para o usuário atual. Ao especificar um único esquema, o manipulador
correspondente é executado.
ASP.NET Core 2.x
ASP.NET Core 1.x
[Authorize(AuthenticationSchemes =
JwtBearerDefaults.AuthenticationScheme)]
public class MixedController : Controller
No código anterior, somente o manipulador com o esquema de "Bearer" é executado. Todas as identidades
baseadas em cookies serão ignoradas.
Selecionar o esquema com as políticas

Se você preferir especificar os esquemas de desejada diretiva, você pode definir o AuthenticationSchemes coleção
ao adicionar sua política:
{
options.AddPolicy("Over18", policy =>
{
policy.AuthenticationSchemes.Add(JwtBearerDefaults.AuthenticationScheme);
policy.RequireAuthenticatedUser();
policy.Requirements.Add(new MinimumAgeRequirement());
});
});
No exemplo anterior, a política de "Over18" só é executada em relação a identidade criada pelo manipulador de
"Portador". Usar a política, definindo o [Authorize] do atributo Policy propriedade:
[Authorize(Policy = "Over18")]
public class RegistrationController : Controller
Usar vários esquemas de autenticação

Alguns aplicativos talvez seja necessário dar suporte a vários tipos de autenticação. Por exemplo, seu aplicativo
pode autenticar os usuários do Active Directory do Azure e de um banco de dados de usuários. Outro exemplo é
um aplicativo que autentica os usuários do Active Directory Federation Services e o Azure Active Directory B2C.
Nesse caso, o aplicativo deve aceitar um token de portador JWT de vários emissores.
Adicione todos os esquemas de autenticação que você gostaria de aceitar. Por exemplo, o código a seguir no
Startup.ConfigureServices adiciona dois esquemas de autenticação de portador JWT com emissores diferentes:
{
services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
{
options.Audience = "https://localhost:5000/";
options.Authority = "https://localhost:5000/identity/";
})
.AddJwtBearer("AzureAD", options =>
{
options.Audience = "https://localhost:5000/";
options.Authority = "https://login.microsoftonline.com/eb971100-6f99-4bdc-8611-1bc8edd7f436/";
});
}
NOTE
Apenas uma autenticação de portador JWT está registrada com o esquema de autenticação padrão
JwtBearerDefaults.AuthenticationScheme . Autenticação adicional deve ser registrado com um esquema de autenticação
exclusiva.
A próxima etapa é atualizar a política de autorização padrão para aceitar os dois esquemas de autenticação. Por
exemplo:

{
{
var defaultAuthorizationPolicyBuilder = new AuthorizationPolicyBuilder(
JwtBearerDefaults.AuthenticationScheme,
"AzureAD");
defaultAuthorizationPolicyBuilder =
defaultAuthorizationPolicyBuilder.RequireAuthenticatedUser();
options.DefaultPolicy = defaultAuthorizationPolicyBuilder.Build();
});
}
Como a política de autorização padrão é substituída, é possível usar um simples [Authorize] atributo em
controladores. O controlador, em seguida, aceita solicitações com JWT emitido pelo emissor do primeiro ou
segundo.
Proteção de dados do ASP.NET Core
Aplicativos da Web geralmente precisam armazenar dados confidenciais de segurança. Windows fornece
DPAPI para aplicativos da área de trabalho, mas isso é inadequado para aplicativos da web. A pilha de proteção
de dados do ASP.NET Core fornecem uma API de criptografia simple e fácil de usar um desenvolvedor pode
usar para proteger dados, incluindo rotação e gerenciamento de chaves.
A pilha de proteção de dados do ASP.NET Core foi projetada para servir como a substituição de longo prazo
para o <machineKey> elemento no ASP.NET 1. x - 4. x. Ele foi projetado para resolver muitos dos problemas
da pilha de criptografia antigo, fornecendo uma solução para a maioria dos casos de uso, os aplicativos
modernos têm probabilidade de encontrar.
Declaração do problema
A declaração do problema geral pode ser declarada em uma única sentença sucintamente: eu preciso manter
informações confiáveis para recuperação posterior, mas eu não confio o mecanismo de persistência. Em termos
de web, isso pode ser escrito como "Eu preciso de ida e volta estado confiável por meio de um cliente não
confiável."
O exemplo canônico disso é um cookie de autenticação ou portador token. O servidor gera um "Estou Groot e
ter permissões de xyz" de token e entrega-o para o cliente. Em uma data futura, o cliente apresentará esse
token de volta para o servidor, mas o servidor precisa de algum tipo de garantia de que o cliente não foi forjada
o token. Portanto, o primeiro requisito: autenticidade (também conhecido como integridade e à prova de
adulteração).
Uma vez que o estado persistente é confiável pelo servidor, estimamos que esse estado pode conter
informações específicas para o ambiente operacional. Isso pode ser na forma de um caminho de arquivo, uma
permissão, um identificador ou outra referência indireta, ou alguma outra parte dos dados específicos do
servidor. Essas informações, em geral, não deveriam ser divulgadas para um cliente não confiável. Portanto, o
segundo requisito: confidencialidade.
Por fim, como aplicativos modernos são divididos em componentes, o que vimos é componentes individuais
vai querer tirar proveito desse sistema sem levar em consideração outros componentes no sistema. Por
exemplo, se um componente de token de portador é usando essa pilha, ele deve operar sem interferência de
um mecanismo de anti-CSRF que também pode usar a mesma pilha. Portanto, o requisito final: isolamento.
Podemos fornecer ainda mais as restrições para limitar o escopo de nossos requisitos. Vamos supor que todos
os serviços que operam com o sistema de criptografia são igualmente confiáveis e que os dados não precisam
ser gerado ou consumido fora os serviços sob nosso controle direto. Além disso, exigimos que as operações
são tão rápidas quanto possível, pois cada solicitação ao serviço web pode percorrer o sistema criptográfico
uma ou mais vezes. Isso torna a criptografia simétrica ideal para o nosso cenário, e podemos pode desconto
criptografia assimétrica até que tal uma vez que ele é necessário.
Filosofia de design
Começamos por meio da identificação de problemas com a pilha existente. Depois que tivermos, nós
pesquisamos o panorama das soluções existentes e concluiu que não há solução existente teve muito os
recursos que são procurados. Em seguida, projetamos uma solução baseada em vários princípios de
orientação.
O sistema deve oferecer a simplicidade da configuração. O ideal é que o sistema seria sem nenhuma
configuração e os desenvolvedores poderiam parta para a ação. Em situações em que os
desenvolvedores precisam configurar um aspecto específico (como o repositório de chaves),
consideração deve ser fornecida a fazer essas configurações específicas simples.
Oferecem uma API voltado ao consumidor simples. As APIs devem ser fáceis de usar corretamente e
difícil de usar incorretamente.
Os desenvolvedores não devem aprender os princípios de gerenciamento de chaves. O sistema deve
lidar com a seleção de algoritmo e a vida útil da chave em nome do desenvolvedor. O ideal é que o
desenvolvedor nunca mesmo deve ter acesso ao material da chave bruto.
As chaves devem ser protegidas em repouso quando possível. O sistema deve descobrir um mecanismo
de proteção padrão apropriado e aplicá-la automaticamente.
Com esses princípios em mente, desenvolvemos um simples fácil de usar pilha da proteção de dados.
As APIs de proteção de dados do ASP.NET Core não destinam principalmente para persistência indefinida de
cargas confidenciais. Outras tecnologias, como DPAPI do Windows CNG e do Azure Rights Management são
mais adequados para o cenário de armazenamento indefinido, e eles têm recursos de gerenciamento de chave
forte de forma correspondente. Dito isso, não há nada proibindo um desenvolvedor que usa as APIs de
proteção de dados do ASP.NET Core para proteção de longo prazo de dados confidenciais.
Público-alvo
O sistema de proteção de dados é dividido em cinco pacotes principais. Vários aspectos dessas APIs três
principal públicos-alvo; de destino
1. O visão geral das APIs de consumidor os desenvolvedores de aplicativo e estrutura de destino.
"Quero saber mais sobre como funciona a pilha de ou sobre como ela é configurada. Simplesmente
quero executar alguma operação no tão simples uma maneira possível com a alta probabilidade de usar
as APIs com êxito".
2. O APIs de configuração os desenvolvedores de aplicativos e administradores de sistema de destino.
"Eu preciso informar ao sistema de proteção de dados de que meu ambiente requer configurações ou os
caminhos não padrão."
3. Os desenvolvedores de destino APIs de extensibilidade responsável pela implementação de política
personalizada. O uso dessas APIs seria limitado a situações raras e experientes, os desenvolvedores de
reconhecimento de segurança.
"Eu preciso substituir um componente inteiro dentro do sistema porque tenho requisitos
comportamentais realmente exclusivos. Desejo saber usados raramente partes da superfície de API a
fim de criar um plug-in que atenda aos meus requisitos."
Layout do pacote
A pilha da proteção de dados consiste em cinco pacotes.
Microsoft.AspNetCore.DataProtection.Abstractions contém o IDataProtectionProvider e IDataProtector
interfaces para criar serviços de proteção de dados. Ele também contém métodos de extensão úteis para
trabalhar com esses tipos (por exemplo, IDataProtector.Protect). Se o sistema de proteção de dados é
instanciado em outro lugar e você está consumindo a API, referência
Microsoft.AspNetCore.DataProtection.Abstractions .
Microsoft.AspNetCore.DataProtection contém a implementação principal do sistema de proteção de

dados, incluindo operações criptográficas de núcleo, gerenciamento de chaves, configuração e
extensibilidade. Para instanciar o sistema de proteção de dados (por exemplo, adicioná-lo para um
IServiceCollection) ou fazer referência a modificar ou estender seu comportamento,
Microsoft.AspNetCore.DataProtection .
Microsoft.AspNetCore.DataProtection.Extensions contém APIs adicionais que os desenvolvedores

podem ser úteis, mas que não cabem no pacote principal. Por exemplo, este pacote contém métodos de
fábrica para instanciar o sistema de proteção de dados para armazenar chaves em um local no sistema
de arquivos sem injeção de dependência (consulte DataProtectionProvider). Ele também contém
métodos de extensão para limitar o tempo de vida de cargas protegidas (consulte
ITimeLimitedDataProtector).
Microsoft.AspNetCore.DataProtection.SystemWeb pode ser instalado em um aplicativo existente do
ASP.NET 4.x para redirecionar seu <machineKey> operações para usar a nova pilha de proteção de dados
do ASP.NET Core. Para obter mais informações, consulte Substitua o machineKey ASP.NET no núcleo
do ASP.NET.
Microsoft.AspNetCore.Cryptography.KeyDerivation fornece uma implementação da rotina de hash de
senha de PBKDF2 e podem ser usadas por sistemas que precisam lidar com as senhas de usuário com
segurança. Para obter mais informações, consulte Hash de senhas no ASP.NET Core.
Recursos adicionais
Comece com as APIs de proteção de dados no
ASP.NET Core
Em seus dados mais simples, protegendo consiste as seguintes etapas:

1. Crie dados de um protetor de um provedor de proteção de dados.
2. Chamar o Protect método com os dados que você deseja proteger.
3. Chamar o Unprotect método com os dados que você deseja transformar de volta em texto sem
formatação.
A maioria das estruturas e modelos de aplicativo, como o ASP.NET Core ou SignalR, já que configurar o sistema
de proteção de dados e adicioná-lo a um contêiner de serviço que você acessa por meio da injeção de
dependência. O exemplo a seguir demonstra Configurando um contêiner de serviço para injeção de dependência
e registrando a pilha da proteção de dados, recebendo o provedor de proteção de dados por meio da DI, criando
um protetor e desproteção em seguida, proteção de dados.
using System;
using Microsoft.AspNetCore.DataProtection;

{
{
// add data protection services
var serviceCollection = new ServiceCollection();
serviceCollection.AddDataProtection();
var services = serviceCollection.BuildServiceProvider();
// create an instance of MyClass using the service provider

var instance = ActivatorUtilities.CreateInstance<MyClass>(services);
instance.RunSample();
}

{
IDataProtector _protector;
// the 'provider' parameter is provided by DI

public MyClass(IDataProtectionProvider provider)
{
_protector = provider.CreateProtector("Contoso.MyClass.v1");
}
public void RunSample()

{
Console.Write("Enter input: ");
string input = Console.ReadLine();
// protect the payload

string protectedPayload = _protector.Protect(input);
Console.WriteLine($"Protect returned: {protectedPayload}");
// unprotect the payload

string unprotectedPayload = _protector.Unprotect(protectedPayload);
Console.WriteLine($"Unprotect returned: {unprotectedPayload}");
}
}
}
/*
* SAMPLE OUTPUT
*
* Enter input: Hello world!
* Protect returned: CfDJ8ICcgQwZZhlAlTZT...OdfH66i1PnGmpCR5e441xQ
* Unprotect returned: Hello world!
*/
Quando você cria um protetor deve fornecer um ou mais cadeias de caracteres de finalidade. Uma cadeia de
caracteres de finalidade fornece isolamento entre os consumidores. Por exemplo, um protetor criado com uma
cadeia de caracteres de finalidade de "verde" seria capaz de Desproteger dados fornecidos por um protetor, com a
finalidade de "roxo".
TIP
Instâncias do IDataProtectionProvider e IDataProtector sejam thread-safe para chamadores vários. Ele deve que
depois que um componente obtém uma referência a um IDataProtector por meio de uma chamada para
CreateProtector , ele usará essa referência para várias chamadas para Protect e Unprotect .
Uma chamada para Unprotect lançará CryptographicException se o conteúdo protegido não pode ser verificado ou
decifrado. Alguns componentes talvez queira ignorar erros durante a Desproteger operações; um componente que lê os
cookies de autenticação pode manipular esse erro e tratar a solicitação como se ele não tinha nenhum cookie em todos os
em vez de falhar a solicitação imediatamente. Componentes que desejam esse comportamento devem especificamente
capturar CryptographicException em vez de assimilação de todas as exceções.
Visão geral APIs do consumidor do ASP.NET Core
O IDataProtectionProvider e IDataProtector interfaces são as interfaces básicas por meio do qual os

consumidores usam o sistema de proteção de dados. Eles estão localizados no
Microsoft.AspNetCore.DataProtection.Abstractions pacote.
IDataProtectionProvider
A interface de provedor representa a raiz do sistema de proteção de dados. Ele não pode ser usado diretamente
para proteger ou desproteger dados. Em vez disso, o consumidor deve obter uma referência a um
IDataProtector chamando IDataProtectionProvider.CreateProtector(purpose) , onde o objetivo é uma cadeia de
caracteres que descreve o caso de uso pretendido do consumidor. Consulte cadeias de caracteres de finalidade
para obter mais informações sobre a intenção deste parâmetro e como escolher um valor apropriado.
IDataProtector
A interface de protetor é retornada por uma chamada para CreateProtector e ele essa interface que os
consumidores podem usar para executar proteger e Desproteger as operações.
Para proteger uma parte dos dados, transmitir os dados para o Protect método. A interface básica define um
método que byte converte [] -> byte [], mas há também uma sobrecarga (fornecida como um método de
extensão), que converte a cadeia de caracteres -> a cadeia de caracteres. A segurança oferecida pelos dois
métodos é idêntica; o desenvolvedor deve escolher qualquer sobrecarga é mais conveniente para seu caso de uso.
Independentemente da sobrecarga escolhida, o valor retornado pelo Proteja método agora está protegido
(enciphered e à prova de adulteração) e o aplicativo pode enviá-lo para um cliente não confiável.
Para desproteger uma parte anteriormente protegido dos dados, passar os dados protegidos para o Unprotect
método. (Há byte []-sobrecargas com base e baseada em cadeia de caracteres para conveniência do
desenvolvedor.) Se a carga protegida foi gerada por uma chamada anterior para Protect esse mesmo
IDataProtector , o Unprotect método retornará a carga desprotegida original. Se a carga protegida tenha sido
violada ou foi produzida por outro IDataProtector , o Unprotect método lançará CryptographicException.
O conceito de mesmo versus diferentes IDataProtector vínculos de volta para o conceito de finalidade. Se dois
IDataProtector instâncias foram geradas a partir da mesma raiz IDataProtectionProvider mas por meio de
cadeias de caracteres de finalidade diferente na chamada para IDataProtectionProvider.CreateProtector , em
seguida, elas são consideradas protetores diferentes, e um não será possível desproteger cargas geradas por
outros.
Essas interfaces de consumo

Para um componente com reconhecimento de injeção de dependência, o uso pretendido é que o componente
levar uma IDataProtectionProvider parâmetro em seu construtor e que o sistema DI fornece automaticamente
esse serviço quando o componente é instanciado.
NOTE
Alguns aplicativos (como aplicativos de console ou aplicativos do ASP.NET 4. x) podem não ser DI com reconhecimento de
forma não é possível usar o mecanismo descrito aqui. Para esses cenários consulte o cenários com reconhecimento de DI
não documento para obter mais informações sobre a obtenção de uma instância de um IDataProtection provedor sem
passar por DI.
O exemplo a seguir demonstra três conceitos:

1. Adicione o sistema de proteção de dados ao contêiner de serviço,
2. Usando DI para receber uma instância de um IDataProtectionProvider ,e
3. Criando um IDataProtector de um IDataProtectionProvider e usá-lo para proteger e Desproteger dados.
using System;

{
{
// create an instance of MyClass using the service provider

var instance = ActivatorUtilities.CreateInstance<MyClass>(services);
instance.RunSample();
}

{
IDataProtector _protector;
// the 'provider' parameter is provided by DI

public MyClass(IDataProtectionProvider provider)
{
_protector = provider.CreateProtector("Contoso.MyClass.v1");
}
public void RunSample()

{

string protectedPayload = _protector.Protect(input);

string unprotectedPayload = _protector.Unprotect(protectedPayload);
}
}
}
/*
* SAMPLE OUTPUT
*
* Protect returned: CfDJ8ICcgQwZZhlAlTZT...OdfH66i1PnGmpCR5e441xQ
*/
O pacote Microsoft.AspNetCore.DataProtection.Abstractions contém um método de extensão

IServiceProvider.GetDataProtector como uma conveniência de desenvolvedor. Ele encapsula como uma única
operação ambos recuperando uma IDataProtectionProvider do provedor de serviços e chamar
IDataProtectionProvider.CreateProtector . O exemplo a seguir demonstra o uso.
using System;

{
{
// get an IDataProtector from the IServiceProvider

var protector = services.GetDataProtector("Contoso.Example.v2");

string protectedPayload = protector.Protect(input);

string unprotectedPayload = protector.Unprotect(protectedPayload);
}
}
TIP
Instâncias do IDataProtectionProvider e IDataProtector são thread-safe para chamadores vários. Ele foi desenvolvido
que depois que um componente obtém uma referência a um IDataProtector por meio de uma chamada para
CreateProtector , ele usará essa referência para várias chamadas para Protect e Unprotect . Uma chamada para
Unprotect lançará CryptographicException se a carga protegida não pode ser verificada ou decifrada. Alguns
componentes poderá ignorar erros durante Desproteger operações; um componente que lê os cookies de autenticação
pode manipular esse erro e tratar a solicitação, como não se tivesse nenhum cookie de em vez de falhar a solicitação.
Componentes que deseja que esse comportamento especificamente devem capturar CryptographicException em vez de
assimilação todas as exceções.
Cadeias de caracteres de finalidade no núcleo do
ASP.NET
Componentes que consomem IDataProtectionProvider deve passar em uma única fins parâmetro para o
CreateProtector método. A finalidade parâmetro é inerente à segurança do sistema de proteção de dados,
como ele fornece isolamento entre consumidores de criptografia, mesmo se as chaves de criptografia de raiz são
as mesmas.
Quando um consumidor Especifica a finalidade, a cadeia de caracteres de finalidade é usada junto com as chaves
de criptografia de raiz para derivar criptográficas subchaves exclusivas para que o consumidor. Isso isola o
consumidor de todos os outros consumidores criptográficos do aplicativo: nenhum outro componente pode ler
suas cargas de e não pode ler cargas do qualquer outro componente. Esse isolamento também processa inviável
categorias inteiras de ataque em relação ao componente.
No diagrama acima, IDataProtector instâncias A e B não é possível ler umas das outras cargas, somente seus
próprios.
A cadeia de caracteres de fim não precisa ser segredo. Ele simplesmente deve ser exclusivo no sentido de que
nenhum outro componente com bom comportamento já fornecem a mesma cadeia de caracteres de finalidade.
TIP
Usando o nome de namespace e o tipo do componente consumindo as APIs de proteção de dados é uma boa regra geral,
como prática que essas informações nunca entrarão em conflito.
Um componente de autoria do Contoso que é responsável por minting tokens de portador pode usar
Contoso.Security.BearerToken como cadeia de caracteres sua finalidade. Ou - ainda melhor - ele pode usar
Contoso.Security.BearerToken.v1 como cadeia de caracteres sua finalidade. Anexar o número de versão permite que uma
versão futura usar Contoso.Security.BearerToken.v2 como sua finalidade e as versões diferentes seria completamente
isoladas uma da outra quanto cargas ir.
Desde o parâmetro fins CreateProtector é uma matriz de cadeia de caracteres, acima poderiam ter sido em vez
disso, especificadas como [ "Contoso.Security.BearerToken", "v1" ] . Isso permite o estabelecimento de uma
hierarquia de propósitos e abre a possibilidade de cenários de multilocação com o sistema de proteção de
dados.
WARNING
Componentes não devem permitir que a entrada do usuário não confiável ser a única origem de entrada para a cadeia de
fins.
Por exemplo, considere um componente Contoso.Messaging.SecureMessage que é responsável por armazenar mensagens
seguras. Se o componente de mensagens seguro chamar CreateProtector([ username ]) , em seguida, um usuário
mal-intencionado pode criar uma conta com o nome de usuário "Contoso.Security.BearerToken" em uma tentativa de
obter o componente para chamar CreateProtector([ "Contoso.Security.BearerToken" ]) , inadvertidamente
provocando mensagens seguras sistema cargas Menta que pode ser considerada como tokens de autenticação.
Uma cadeia de fins melhor para o componente de mensagens seria
CreateProtector([ "Contoso.Messaging.SecureMessage", "User: username" ]) , que fornece isolamento apropriado.
O isolamento fornecido pelos e comportamentos de IDataProtectionProvider , IDataProtector , e fins é o

seguinte:
Para um determinado IDataProtectionProvider objeto, o CreateProtector método criará uma
IDataProtector objeto vinculado exclusivamente para ambos os IDataProtectionProvider objeto que
criou e o parâmetro de fins que foi passado para o método.
O parâmetro de fim não deve ser nulo. (Se fins é especificado como uma matriz, isso significa que a
matriz não deve ser de comprimento zero e todos os elementos da matriz devem ser não-nulo.) Uma
finalidade de cadeia de caracteres vazia é tecnicamente permitida, mas não é recomendada.
Argumentos de duas finalidades são equivalentes se e somente se eles contêm as mesmas cadeias de
caracteres (usando um comparador ordinal) na mesma ordem. Um argumento de finalidade única é
equivalente à matriz de elemento único fins correspondente.
Dois IDataProtector objetos são equivalentes e apenas se eles são criados a partir equivalente
IDataProtectionProvider objetos com parâmetros de fins equivalente.
Para um determinado IDataProtector objeto, uma chamada para Unprotect(protectedData) retornará
original unprotectedData se e somente se protectedData := Protect(unprotectedData) para um
equivalente IDataProtector objeto.
NOTE
Não estamos considerando o caso onde algum componente intencionalmente escolhe uma cadeia de caracteres de
finalidade que é conhecida em conflito com outro componente. Esse componente essencialmente seria considerado mal-
intencionados e este sistema não se destina a fornecer garantias de segurança que um código mal-intencionado já está
em execução dentro do processo de trabalho.
Hierarquia de finalidade e a multilocação no ASP.NET
Core
Uma vez que um IDataProtector também é implicitamente um IDataProtectionProvider , fins podem ser
encadeada juntos. Nesse sentido provider.CreateProtector([ "purpose1", "purpose2" ]) é equivalente a
provider.CreateProtector("purpose1").CreateProtector("purpose2") .
Isso permite que algumas relações hierárquicas interessantes através do sistema de proteção de dados. No
exemplo anterior de Contoso.Messaging.SecureMessage, o componente SecureMessage pode chamar
provider.CreateProtector("Contoso.Messaging.SecureMessage") iniciais de uma vez e armazenar em cache o
resultado em uma particular _myProvider campo. Protetores de futuros, em seguida, podem ser criadas por meio
de chamadas para _myProvider.CreateProtector("User: username") , e os protetores seriam usados para proteger as
mensagens individuais.
Isso também pode ser invertido. Considere um único aplicativo lógico que hospeda vários locatários (um CMS
parece razoável) e cada locatário podem ser configurado com seu próprio sistema de gerenciamento de
autenticação e o estado. O aplicativo guarda-chuva tem um único provedor mestre e, em seguida, chama
provider.CreateProtector("Tenant 1") e provider.CreateProtector("Tenant 2") para fornecer seu próprio fatia
isolada do sistema de proteção de dados de cada locatário. Os locatários, em seguida, pode derivar seus próprios
protetores individuais com base em suas necessidades, mas, independentemente de como eles tentam eles não é
possível criar protetores que entrem em conflito com qualquer outro locatário no sistema. Graficamente, isso é
representado como abaixo.
WARNING
Isso pressupõe que a cobertura do controles de aplicativo, quais APIs estão disponíveis para locatários individuais e que os
locatários não podem executar código arbitrário no servidor. Se um locatário pode executar código arbitrário, eles poderiam
executar a reflexão privada para quebrar as garantias de isolamento, ou pode apenas ler o material de chave mestra
diretamente e derivar qualquer subchaves que desejarem.
Na verdade, o sistema de proteção de dados usa uma espécie de multilocação em sua configuração de out-of-the-
box do padrão. Por padrão, o material de chave mestra é armazenado na pasta de perfil do usuário da conta de
processo do operador (ou o registro, para identidades do pool de aplicativos IIS ). Mas é, na verdade, bastante
comum usar uma única conta para executar vários aplicativos e, portanto, todos esses aplicativos seriam acabam
compartilhando a material da chave mestra. Para resolver isso, o sistema de proteção de dados insere
automaticamente um identificador exclusivo por aplicativo como o primeiro elemento na cadeia de finalidade
geral. Que serve para essa finalidade implícita isolar aplicativos individuais uns dos outros, tratando efetivamente
cada aplicativo como um locatário exclusivo no sistema e o processo de criação de protetor parece idêntico na
imagem acima.
Hash de senhas no ASP.NET Core
A base de código do proteção de dados inclui um pacote Microsoft.AspNetCore.Cryptography.KeyDerivation que

contém funções de derivação de chave de criptografia. Esse pacote é um componente autônomo e não tem
nenhuma dependência no restante do sistema de proteção de dados. Ele pode ser usado independentemente
completamente. A origem existe junto com o código de proteção de dados base como uma conveniência.
O pacote no momento, oferece um método KeyDerivation.Pbkdf2 que permite o hash de uma senha usando o
PBKDF2 algoritmo. Essa API é muito semelhante à existente do .NET Framework Rfc2898DeriveBytes tipo, mas
há três diferenças importantes:
1. O KeyDerivation.Pbkdf2 método dá suporte ao consumo PRFs vários (atualmente HMACSHA1 , HMACSHA256 ,
e HMACSHA512 ), enquanto o Rfc2898DeriveBytes digite dá suporte apenas à HMACSHA1 .
2. O KeyDerivation.Pbkdf2 método detecta o sistema operacional atual e tenta escolher a implementação
mais otimizada de rotina, fornecendo um desempenho muito melhor em alguns casos. (No Windows 8, ele
oferece cerca de 10 vezes a taxa de transferência Rfc2898DeriveBytes .)
3. O KeyDerivation.Pbkdf2 método requer que o chamador especificar todos os parâmetros (salt, PRF e
contagem de iteração). O Rfc2898DeriveBytes tipo fornece valores padrão para eles.
using System;
using System.Security.Cryptography;
using Microsoft.AspNetCore.Cryptography.KeyDerivation;

{
{
Console.Write("Enter a password: ");
string password = Console.ReadLine();
// generate a 128-bit salt using a secure PRNG

byte[] salt = new byte[128 / 8];
using (var rng = RandomNumberGenerator.Create())
{
rng.GetBytes(salt);
}
Console.WriteLine($"Salt: {Convert.ToBase64String(salt)}");
// derive a 256-bit subkey (use HMACSHA1 with 10,000 iterations)

string hashed = Convert.ToBase64String(KeyDerivation.Pbkdf2(
password: password,
salt: salt,
prf: KeyDerivationPrf.HMACSHA1,
iterationCount: 10000,
numBytesRequested: 256 / 8));
Console.WriteLine($"Hashed: {hashed}");
}
}
/*
* SAMPLE OUTPUT
*
* Enter a password: Xtw9NMgx
* Salt: NZsP6NnmfBuYeJrrAKNuVQ==
* Hashed: /OOoOer10+tGwTRDTrQSoeCxVTFr6dtYly7d0cPxIak=
*/
Consulte a código-fonte para o ASP.NET Core Identity PasswordHasher caso de uso de tipo para um mundo real.
Limite o tempo de vida das cargas protegidos no
núcleo do ASP.NET
Há cenários onde quer que o desenvolvedor do aplicativo para criar uma carga protegida que expira após um
período de tempo definido. Por exemplo, a carga protegida pode representar um token de redefinição de senha
que deve ser válido somente por uma hora. É certamente possível para o desenvolvedor criar seu próprio formato
de carga que contém uma data de expiração incorporados e os desenvolvedores avançados talvez queira fazer isso
mesmo assim, mas para a maioria dos desenvolvedores gerenciar esses expirações pode crescer entediante.
Para facilitar isso para nossos público de desenvolvedor, o pacote
Microsoft.AspNetCore.DataProtection.Extensions contém APIs do utilitário para criar cargas expirarem
automaticamente após um período de tempo definido. Essas APIs de suspensão do ITimeLimitedDataProtector
tipo.
Uso de API
O ITimeLimitedDataProtector interface é a interface principal para proteger e ao desproteger cargas de tempo
limitado / expiração automática. Para criar uma instância de um ITimeLimitedDataProtector , você precisará de uma
instância de uma expressão IDataProtector construído com uma finalidade específica. Uma vez o IDataProtector
instância estiver disponível, chame o IDataProtector.ToTimeLimitedDataProtector método de extensão para retornar
um protetor com recursos internos de expiração.
ITimeLimitedDataProtector apresenta os seguintes métodos de extensão e de superfície de API:
CreateProtector (objetivo de cadeia de caracteres): ITimeLimitedDataProtector - esta API é semelhante à
existente IDataProtectionProvider.CreateProtector em que ele pode ser usado para criar finalidade cadeias
de um protetor de tempo limite de raiz.
Proteger (byte [] texto sem formatação, expiração de DateTimeOffset): byte]
Proteger (texto sem formatação do byte [], tempo de vida de TimeSpan): byte]
Proteger (byte [] texto sem formatação): byte]
Proteger (cadeia de caracteres em texto sem formatação, expiração de DateTimeOffset): cadeia de
caracteres
Proteger (texto sem formatação de cadeia de caracteres, tempo de vida de TimeSpan): cadeia de caracteres
Proteger (cadeia de caracteres em texto sem formatação): cadeia de caracteres
Além das principais Protect métodos que levam apenas o texto não criptografado, não há novas sobrecargas que
permitem especificar a data de validade da carga. A data de validade pode ser especificada como uma data
absoluta (por meio de um DateTimeOffset ) ou como uma hora relativa (do sistema atual de tempo, por meio de
um TimeSpan ). Se uma sobrecarga que não tem uma expiração é chamada, a carga será considerada nunca para
expirar.
Desproteger (byte [] protectedData, limite de expiração de DateTimeOffset): byte]
Desproteger (byte [] protectedData): byte]
Desproteger (protectedData de cadeia de caracteres, limite de expiração de DateTimeOffset): cadeia de
caracteres
Desproteger (cadeia de caracteres protectedData): cadeia de caracteres
O Unprotect métodos retornam os dados desprotegidos originais. Se a carga ainda não tiver expirado, a expiração
absoluta é retornada como um parâmetro junto com os dados desprotegidos originais out opcional. Se a carga
tiver expirada, todas as sobrecargas do método Desproteger lançará CryptographicException.
WARNING
Ele não tem recomendável usar essas APIs para proteger cargas que requerem a persistência de longo prazo ou indefinida.
"Pode suportar para as cargas protegidas sejam irrecuperáveis permanentemente após um mês?" pode servir como uma boa
regra prática; Se a resposta for nenhum desenvolvedores, em seguida, considere APIs alternativas.
O exemplo abaixo usa o caminhos de código não DI para instanciar o sistema de proteção de dados. Para executar
este exemplo, certifique-se de que você adicionou uma referência ao pacote
Microsoft.AspNetCore.DataProtection.Extensions primeiro.
using System;
using System.IO;
using System.Threading;

{
{
// create a protector for my application
var provider = DataProtectionProvider.Create(new DirectoryInfo(@"c:\myapp-keys\"));

var baseProtector = provider.CreateProtector("Contoso.TimeLimitedSample");
// convert the normal protector into a time-limited protector

var timeLimitedProtector = baseProtector.ToTimeLimitedDataProtector();
// get some input and protect it for five seconds

string protectedData = timeLimitedProtector.Protect(input, lifetime: TimeSpan.FromSeconds(5));
Console.WriteLine($"Protected data: {protectedData}");
// unprotect it to demonstrate that round-tripping works properly

string roundtripped = timeLimitedProtector.Unprotect(protectedData);
Console.WriteLine($"Round-tripped data: {roundtripped}");
// wait 6 seconds and perform another unprotect, demonstrating that the payload self-expires
Console.WriteLine("Waiting 6 seconds...");
Thread.Sleep(6000);
timeLimitedProtector.Unprotect(protectedData);
}
}
/*
* SAMPLE OUTPUT
*
* Enter input: Hello!
* Protected data: CfDJ8Hu5z0zwxn...nLk7Ok
* Round-tripped data: Hello!
* Waiting 6 seconds...
* <<throws CryptographicException with message 'The payload expired at ...'>>
*/
Desproteger cargas cujas chaves foram revogadas no
ASP.NET Core
As APIs de proteção de dados do ASP.NET Core não destinam principalmente para persistência indefinida de
cargas confidenciais. Outras tecnologias, como DPAPI do Windows CNG e do Azure Rights Management são mais
adequados para o cenário de armazenamento indefinido, e eles têm recursos de gerenciamento de chave forte de
forma correspondente. Dito isso, não há nada proibindo um desenvolvedor que usa as APIs de proteção de dados
do ASP.NET Core para proteção de longo prazo de dados confidenciais. As chaves nunca são removidas do anel
de chave, portanto, IDataProtector.Unprotect sempre pode recuperar conteúdos existentes desde que as chaves
estão disponíveis e válido.
No entanto, um problema surge quando o desenvolvedor tenta desproteger os dados que foi protegidos com uma
chave revogada, como IDataProtector.Unprotect lançará uma exceção, nesse caso. Isso pode ser adequado para
cargas de curta duração ou transitórias (como tokens de autenticação), pois esses tipos de cargas podem ser
facilmente recriados pelo sistema e, na pior das hipóteses, o visitante do site pode ser necessário fazer logon
novamente. Mas para cargas persistentes, tendo Unprotect throw pode levar à perda de dados inaceitável.
IPersistedDataProtector
Para suportar o cenário de permitir que os conteúdos a serem desprotegidos mesmo diante de chaves revogadas,
o sistema de proteção de dados contém um IPersistedDataProtector tipo. Para obter uma instância de
IPersistedDataProtector , simplesmente obtém uma instância do IDataProtector no modo normal e tente
conversão a IDataProtector para IPersistedDataProtector .
NOTE
Nem todos os IDataProtector instâncias podem ser convertidas em IPersistedDataProtector . Os desenvolvedores
devem usar o C# operador ou semelhante ou evitar exceções de tempo de execução causado por conversões inválidas, e eles
devem estar preparados para tratar o caso de falha de forma adequada.
IPersistedDataProtector expõe a superfície de API a seguir:
DangerousUnprotect(byte[] protectedData, bool ignoreRevocationErrors,

out bool requiresMigration, out bool wasRevoked) : byte[]
Essa API usa o conteúdo protegido (como uma matriz de bytes) e retorna a carga desprotegida. Não há nenhuma
sobrecarga baseada em cadeia de caracteres. Os dois parâmetros de saída são da seguinte maneira.
requiresMigration: será ser definido como true se a chave usada para proteger esse conteúdo não é mais a
chave padrão do Active Directory, por exemplo, a chave usada para proteger essa carga é antiga e uma
chave sem interrupção operação tem desde ocorrido. O chamador poderá considerar o proteger novamente
a carga, dependendo de suas necessidades de negócios.
wasRevoked : será definido como true se a chave usada para proteger este conteúdo foi revogada.
WARNING
Tenha bastante cuidado ao passar ignoreRevocationErrors: true para o DangerousUnprotect método. Se, depois de
chamar esse método o wasRevoked valor for true, em seguida, a chave usada para proteger este conteúdo foi revogada e
autenticidade do conteúdo deve ser tratada como suspeito. Nesse caso, apenas continue a operar na carga de desprotegidos
se você tiver alguma garantia separada que é autêntico, por exemplo, se ele é proveniente de um banco de dados seguro em
vez de que está sendo enviada por um cliente da web não confiável.
using System;
using System.IO;
using System.Text;
using Microsoft.AspNetCore.DataProtection.KeyManagement;

{
{
serviceCollection.AddDataProtection()
// point at a specific folder and use DPAPI to encrypt keys
.PersistKeysToFileSystem(new DirectoryInfo(@"c:\temp-keys"))
.ProtectKeysWithDpapi();
// get a protector and perform a protect operation

var protector = services.GetDataProtector("Sample.DangerousUnprotect");
Console.Write("Input: ");
byte[] input = Encoding.UTF8.GetBytes(Console.ReadLine());
var protectedData = protector.Protect(input);
Console.WriteLine($"Protected payload: {Convert.ToBase64String(protectedData)}");
// demonstrate that the payload round-trips properly

var roundTripped = protector.Unprotect(protectedData);
Console.WriteLine($"Round-tripped payload: {Encoding.UTF8.GetString(roundTripped)}");
// get a reference to the key manager and revoke all keys in the key ring
var keyManager = services.GetService<IKeyManager>();
Console.WriteLine("Revoking all keys in the key ring...");
keyManager.RevokeAllKeys(DateTimeOffset.Now, "Sample revocation.");
// try calling Protect - this should throw

Console.WriteLine("Calling Unprotect...");
try
{
var unprotectedPayload = protector.Unprotect(protectedData);
Console.WriteLine($"Unprotected payload: {Encoding.UTF8.GetString(unprotectedPayload)}");
}
{
Console.WriteLine($"{ex.GetType().Name}: {ex.Message}");
}
// try calling DangerousUnprotect

Console.WriteLine("Calling DangerousUnprotect...");
try
{
IPersistedDataProtector persistedProtector = protector as IPersistedDataProtector;
if (persistedProtector == null)
{
throw new Exception("Can't call DangerousUnprotect.");
}
bool requiresMigration, wasRevoked;

bool requiresMigration, wasRevoked;
var unprotectedPayload = persistedProtector.DangerousUnprotect(
protectedData: protectedData,
ignoreRevocationErrors: true,
requiresMigration: out requiresMigration,
wasRevoked: out wasRevoked);
Console.WriteLine($"Unprotected payload: {Encoding.UTF8.GetString(unprotectedPayload)}");
Console.WriteLine($"Requires migration = {requiresMigration}, was revoked = {wasRevoked}");
}
{
Console.WriteLine($"{ex.GetType().Name}: {ex.Message}");
}
}
}
/*
* SAMPLE OUTPUT
*
* Input: Hello!
* Protected payload: CfDJ8LHIzUCX1ZVBn2BZ...
* Round-tripped payload: Hello!
* Revoking all keys in the key ring...
* Calling Unprotect...
* CryptographicException: The key {...} has been revoked.
* Calling DangerousUnprotect...
* Unprotected payload: Hello!
* Requires migration = True, was revoked = True
*/
Configuração da Proteção de Dados no ASP.NET
Core
Consulte estes tópicos para obter informações sobre a configuração da Proteção de Dados no ASP.NET Core:
Configurar a proteção de dados do ASP.NET Core
Uma visão geral sobre como configurar a Proteção de Dados do ASP.NET Core.
Tempo de vida e gerenciamento de chaves da Proteção de Dados
Informações sobre tempo de vida e gerenciamento de chaves da Proteção de Dados.
Política de suporte da Proteção de Dados em todo o computador
Detalhes de como definir uma política padrão em todo o computador para todos os aplicativos que usam a
Proteção de Dados.
Cenários sem reconhecimento de DI para a Proteção de Dados no ASP.NET Core
Como usar o tipo concreto DataProtectionProvider para usar a Proteção de Dados sem passar por
caminhos de código específicos de DI.
Configurar a proteção de dados do ASP.NET
Core
Quando o sistema de proteção de dados é inicializado, ele se aplica as configurações padrão com base no
ambiente operacional. Essas configurações são geralmente apropriadas para aplicativos em execução em
um único computador. Há casos em que um desenvolvedor talvez queira alterar as configurações padrão:
O aplicativo é distribuído entre várias máquinas.
Por motivos de conformidade.
Para esses cenários, o sistema de proteção de dados oferece uma API de configuração avançada.
WARNING
Semelhante aos arquivos de configuração, o anel de chave de proteção de dados devem ser protegido usando as
permissões apropriadas. Você pode optar por criptografar as chaves em repouso, mas isso não impede que os
invasores desde a criação de novas chaves. Consequentemente, a segurança desse aplicativo é afetada. O local de
armazenamento configurado com proteção de dados deve ter seu acesso limitado ao próprio aplicativo, semelhante
à forma como você protegerá os arquivos de configuração. Por exemplo, se você optar por armazenar seu token de
autenticação no disco, use as permissões do sistema de arquivos. Certifique-se apenas a identidade sob a qual seu
aplicativo web é executado tem ler, gravar e criar acesso a esse diretório. Se você usar o armazenamento de tabelas
do Azure, apenas o aplicativo web deve ter a capacidade de ler, gravar ou criar novas entradas no repositório de
tabela, etc.
O método de extensão AddDataProtection retorna um IDataProtectionBuilder. IDataProtectionBuilder expõe
métodos de extensão que você pode encadear configurar a proteção de dados de opções.
ProtectKeysWithAzureKeyVault
Para armazenar as chaves na Azure Key Vault, configure o sistema com ProtectKeysWithAzureKeyVault no
Startup classe:

{
services.AddDataProtection()
.PersistKeysToAzureBlobStorage(new Uri("<blobUriWithSasToken>"))
.ProtectKeysWithAzureKeyVault("<keyIdentifier>", "<clientId>", "<clientSecret>");
}
Defina o local de armazenamento do anel de chave (por exemplo, PersistKeysToAzureBlobStorage). O local

deve ser definido porque chamando ProtectKeysWithAzureKeyVault implementa uma IXmlEncryptor que
desabilita as configurações de proteção automática de dados, incluindo o local de armazenamento do anel
de chave. O exemplo anterior usa o armazenamento de BLOBs do Azure para persistir o anel de chave.
Para obter mais informações, consulte principais provedores de armazenamento: o Azure e Redis. Também
é possível persistir o token de autenticação localmente com PersistKeysToFileSystem.
O keyIdentifier é o identificador de chave de Cofre de chaves usado para criptografia de chave (por
exemplo, https://contosokeyvault.vault.azure.net/keys/dataprotection/ ).
ProtectKeysWithAzureKeyVault sobrecargas:
ProtectKeysWithAzureKeyVault (IDataProtectionBuilder, KeyVaultClient, String) permite o uso de um
KeyVaultClient para permitir que o sistema de proteção de dados usar o Cofre de chaves.
ProtectKeysWithAzureKeyVault (IDataProtectionBuilder, cadeia de caracteres, cadeia de caracteres,
X509Certificate2) permite o uso de um ClientId e X509Certificate para permitir que o sistema de
proteção de dados usar o Cofre de chaves.
ProtectKeysWithAzureKeyVault (IDataProtectionBuilder, String, String, String) permite o uso de um
ClientId e ClientSecret para permitir que o sistema de proteção de dados usar o Cofre de chaves.
PersistKeysToFileSystem
Para armazenar chaves em um compartilhamento UNC, em vez da a % LOCALAPPDATA % local padrão,
configure o sistema com PersistKeysToFileSystem:

{
.PersistKeysToFileSystem(new DirectoryInfo(@"\\server\share\directory\"));
}
WARNING
Se você alterar o local de persistência de chave, o sistema não criptografa automaticamente os chaves em repouso,
já que ele não sabe se o DPAPI é um mecanismo de criptografia apropriado.
ProtectKeysWith*
Você pode configurar o sistema para proteger as chaves em repouso chamando o ProtectKeysWith* APIs
de configuração. Considere o exemplo a seguir, que armazena as chaves em um compartilhamento UNC e
criptografa essas chaves em repouso com um certificado x. 509 específico:

{
.PersistKeysToFileSystem(new DirectoryInfo(@"\\server\share\directory\"))
.ProtectKeysWithCertificate("thumbprint");
}
No ASP.NET Core 2.1 ou posterior, você pode fornecer um X509Certificate2 à ProtectKeysWithCertificate,

tais como carregar um certificado de um arquivo:

{
.ProtectKeysWithCertificate(
new X509Certificate2("certificate.pfx", "password"));
}
Ver chave de criptografia em repouso para obter mais exemplos e uma discussão sobre os mecanismos de
criptografia de chave interna.
UnprotectKeysWithAnyCertificate
No ASP.NET Core 2.1 ou posterior, você pode girar certificados e descriptografar chaves em repouso
usando uma matriz de X509Certificate2 certificados com UnprotectKeysWithAnyCertificate:

{
.ProtectKeysWithCertificate(
new X509Certificate2("certificate.pfx", "password"));
.UnprotectKeysWithAnyCertificate(
new X509Certificate2("certificate_old_1.pfx", "password_1"),
new X509Certificate2("certificate_old_2.pfx", "password_2"));
}
SetDefaultKeyLifetime
Para configurar o sistema para usar uma vida útil de 14 dias, em vez do padrão 90 dias, use
SetDefaultKeyLifetime:

{
.SetDefaultKeyLifetime(TimeSpan.FromDays(14));
}
SetApplicationName
Por padrão, o sistema de proteção de dados isola os aplicativos uns dos outros, mesmo que compartilham
o mesmo repositório de chave físico. Isso impede que os aplicativos Noções básicas sobre cargas
protegidas uns dos outros. Para compartilhar cargas protegidas entre dois aplicativos, use
SetApplicationName com o mesmo valor para cada aplicativo:

{
.SetApplicationName("shared app name");
}
DisableAutomaticKeyGeneration
Você pode ter um cenário onde você não deseja que um aplicativo para reverter automaticamente chaves
(criar novas chaves), como eles abordam a expiração. Um exemplo disso pode ser configurados em uma
relação primária/secundária, em que apenas o aplicativo principal é responsável por questões de
gerenciamento de chaves e aplicativos secundários simplesmente tem uma exibição somente leitura do
anel de chave de aplicativos. Os aplicativos secundários podem ser configurados para tratar o anel de
chave como somente leitura ao configurar o sistema com DisableAutomaticKeyGeneration:

{
.DisableAutomaticKeyGeneration();
}
Isolamento por aplicativo

Quando o sistema de proteção de dados é fornecido por um host do ASP.NET Core, ele automaticamente
isola os aplicativos uns dos outros, mesmo que esses aplicativos estão em execução na mesma conta de
processo de trabalho e estiver usando o mesmo material de chave mestra. Isso é um pouco semelhante ao
modificador IsolateApps partir do System. Web <machineKey > elemento.
O mecanismo de isolamento funciona considerando cada aplicativo no computador local como um
locatário exclusivo, portanto, o IDataProtector com raiz para qualquer aplicativo em particular
automaticamente inclui a ID do aplicativo como um discriminador. A ID do aplicativo exclusivo vem de um
dos dois locais:
1. Se o aplicativo estiver hospedado no IIS, o identificador exclusivo é o caminho de configuração do
aplicativo. Se um aplicativo é implantado em um ambiente de farm da web, esse valor deve ser
estável, supondo que os ambientes de IIS são configurados da mesma forma em todas as máquinas
no web farm.
2. Se o aplicativo não está hospedado no IIS, o identificador exclusivo é o caminho físico do aplicativo.
O identificador exclusivo é projetado para sobreviver a reinicializações — do aplicativo individual e a
própria máquina.
Esse mecanismo de isolamento pressupõe que os aplicativos não são mal-intencionados. Um aplicativo
mal-intencionado sempre pode afetar qualquer outro aplicativo em execução sob a mesma conta de
processo de trabalho. Em um ambiente de hospedagem compartilhado em que os aplicativos são
mutuamente não confiáveis, o provedor de hospedagem deve tomar medidas para garantir o isolamento
do nível de sistema operacional entre aplicativos, incluindo a separação de repositórios de chave de base
de aplicativos.
Se o sistema de proteção de dados não é fornecido por um host do ASP.NET Core (por exemplo, se você
instanciá-la por meio de DataProtectionProvider tipo concreto) isolamento de aplicativo está desabilitado
por padrão. Quando o isolamento de aplicativo está desabilitado, todos os aplicativos de apoio com o
mesmo material de chaveamento podem compartilhar cargas desde que eles fornecem apropriado fins.
Para fornecer isolamento de aplicativo nesse ambiente, chame o SetApplicationName método na
configuração do objeto e forneça um nome exclusivo para cada aplicativo.
Alterando os algoritmos com UseCryptographicAlgorithms

A pilha da proteção de dados permite que você altere o algoritmo padrão usado por chaves recentemente
geradas. A maneira mais simples de fazer isso é chamar UseCryptographicAlgorithms do retorno de
chamada de configuração:
ASP.NET Core 2.x
ASP.NET Core 1.x
.UseCryptographicAlgorithms(
new AuthenticatedEncryptorConfiguration()
{
EncryptionAlgorithm = EncryptionAlgorithm.AES_256_CBC,
ValidationAlgorithm = ValidationAlgorithm.HMACSHA256
});
O padrão EncryptionAlgorithm é AES -256-CBC e o padrão ValidationAlgorithm é HMACSHA256. A

política padrão pode ser definida por um administrador do sistema por meio de um política de todo o
computador, mas uma chamada explícita para UseCryptographicAlgorithms substitui a política padrão.
Chamar UseCryptographicAlgorithms permite que você especifique o algoritmo desejado em uma lista
predefinida de interna. Você não precisa se preocupar sobre a implementação do algoritmo. No cenário
acima, o sistema de proteção de dados tenta usar a implementação de CNG do AES se em execução no
Windows. Caso contrário, ele reverterá para o gerenciado System.Security.Cryptography.Aes classe.
Você pode especificar manualmente uma implementação por meio de uma chamada para
UseCustomCryptographicAlgorithms.
TIP
Algoritmos a alteração não afeta as chaves existentes do anel de chave. Ela afeta apenas as chaves recentemente
geradas.
Especificando algoritmos gerenciados personalizados

ASP.NET Core 2.x
ASP.NET Core 1.x
Para especificar algoritmos gerenciados personalizados, crie uma
ManagedAuthenticatedEncryptorConfiguration instância que aponta para os tipos de implementação:
.UseCustomCryptographicAlgorithms(
new ManagedAuthenticatedEncryptorConfiguration()
{
// A type that subclasses SymmetricAlgorithm
EncryptionAlgorithmType = typeof(Aes),
// Specified in bits
EncryptionAlgorithmKeySize = 256,
// A type that subclasses KeyedHashAlgorithm

ValidationAlgorithmType = typeof(HMACSHA256)
});
Geralmente, o *propriedades de tipo devem apontar para concreto, implementações que pode ser
instanciadas (por meio de um construtor sem parâmetros público) de SymmetricAlgorithm e
KeyedHashAlgorithm, embora o sistema classifica como caso especial, como alguns valores typeof(Aes)
para sua conveniência.
NOTE
O SymmetricAlgorithm deve ter um comprimento de chave de 128 bits ≥ e um tamanho de bloco de 64 bits do ≥,
e ele deve oferecer suporte à criptografia de modo CBC com preenchimento PKCS #7. O KeyedHashAlgorithm deve
ter um tamanho de resumo de > = 128 bits, e ele deve oferecer suporte a chaves de comprimento igual ao
comprimento do resumo do algoritmo de hash. O KeyedHashAlgorithm não é estritamente necessária para ser
HMAC.
Especificando algoritmos personalizados da CNG do Windows

ASP.NET Core 2.x
ASP.NET Core 1.x
Para especificar um algoritmo personalizado do CNG do Windows usando a criptografia de modo CBC
com validação do HMAC, crie uma CngCbcAuthenticatedEncryptorConfiguration instância que contém as
informações de algoritmos:
new CngCbcAuthenticatedEncryptorConfiguration()
{
// Passed to BCryptOpenAlgorithmProvider
EncryptionAlgorithm = "AES",
EncryptionAlgorithmProvider = null,
EncryptionAlgorithmKeySize = 256,
HashAlgorithm = "SHA256",
HashAlgorithmProvider = null
});
NOTE
O algoritmo de criptografia de bloco simétricas deve ter um comprimento de chave de > = 128 bits, um tamanho
de bloco de > = 64 bits, e ele deve oferecer suporte à criptografia de modo CBC com preenchimento PKCS #7. O
algoritmo de hash deve ter um tamanho de resumo de > = 128 bits e deve oferecer suporte a que está sendo
aberto com o BCRYPT_ALG_MANIPULAR_HMAC_sinalizador de sinalizador. O *propriedades do provedor podem
ser definidas como nulas para usar o provedor padrão para o algoritmo especificado. Consulte a
BCryptOpenAlgorithmProvider documentação para obter mais informações.
ASP.NET Core 2.x

ASP.NET Core 1.x
Para especificar um algoritmo personalizado do CNG do Windows usando a criptografia de modo
Galois/contador com a validação, crie uma CngGcmAuthenticatedEncryptorConfiguration instância que
contém as informações de algoritmos:
new CngGcmAuthenticatedEncryptorConfiguration()
{
EncryptionAlgorithm = "AES",
EncryptionAlgorithmProvider = null,
EncryptionAlgorithmKeySize = 256
});
NOTE
O algoritmo de criptografia de bloco simétricas deve ter um comprimento de chave de > = 128 bits, um tamanho
de bloco de exatamente de 128 bits, e ele deve oferecer suporte a criptografia do GCM. Você pode definir as
EncryptionAlgorithmProvider propriedade como nulo para usar o provedor padrão para o algoritmo especificado.
Consulte a BCryptOpenAlgorithmProvider documentação para obter mais informações.
Especificar outros algoritmos personalizados

Embora não é exposta como uma API de primeira classe, o sistema de proteção de dados é extensível o
suficiente para permitir a especificação de praticamente qualquer tipo de algoritmo. Por exemplo, é
possível manter todas as chaves contidas dentro do módulo de segurança um Hardware (HSM ) e fornecer
uma implementação personalizada do núcleo rotinas de criptografia e descriptografia. Ver
IAuthenticatedEncryptor na principais de extensibilidade da criptografia para obter mais informações.
Chaves persistentes ao hospedar em um contêiner do Docker

Ao hospedar em um Docker contêiner, as chaves devem ser mantidas em qualquer um:
Uma pasta que é um volume do Docker que persiste além do tempo de vida do contêiner, como um
volume compartilhado ou um volume montado pelo host.
Um provedor externo, como Azure Key Vault ou Redis.
Consulte também
Cenários de reconhecimento não DI para proteção de dados no ASP.NET Core
Suporte a política de máquina de proteção de dados no ASP.NET Core
Gerenciamento de chaves de proteção de dados e o
tempo de vida no ASP.NET Core
Por Rick Anderson
O aplicativo tenta detectar seu ambiente operacional e lidar com a configuração de chave por conta própria.
1. Se o aplicativo estiver hospedado em aplicativos do Azure, as chaves são persistidas para o
%HOME%\ASP.NET\DataProtection-Keys pasta. Essa pasta é apoiada pelo repositório de rede e é
sincronizada em todos os computadores que hospedam o aplicativo.
As chaves não são protegidas em repouso.
O DataProtection chaves pasta fornece o anel de chave a todas as instâncias de um aplicativo em um
único slot de implantação.
Slots de implantação separados, como de preparo e produção, não compartilham um anel de chave.
Quando você alternar entre os slots de implantação, por exemplo, trocar o preparo e produção ou
usando um teste a / B, qualquer aplicativo usando a proteção de dados não será capaz de
descriptografar dados armazenados usando o anel de chave dentro do slot anterior. Isso leva a
usuários que estão sendo conectados fora de um aplicativo que usa a autenticação de cookie padrão
do ASP.NET Core, pois ele usa a proteção de dados para proteger seus cookies. Se desejar que os
anéis de chave independente de slot, use um provedor de anel de chave externo, como o
armazenamento de BLOBs Azure, Azure Key Vault, um repositório SQL ou do cache Redis.
2. Se o perfil do usuário estiver disponível, as chaves são persistidas para o
%LOCALAPPDATA%\ASP.NET\DataProtection-Keys pasta. Se o sistema operacional for Windows, as
chaves são criptografadas em repouso usando a DPAPI.
3. Se o aplicativo estiver hospedado no IIS, as chaves são mantidas no registro HKLM em uma chave de
registro especial que tem a ACL acessível apenas para a conta de processo de trabalho. As chaves são
criptografadas em repouso usando a DPAPI.
4. Se nenhuma dessas condições corresponderem, as chaves não são persistidas fora do processo atual.
Quando o processo é encerrado, todas geradas chaves forem perdidas.
O desenvolvedor está sempre no controle total e pode substituir como e onde as chaves são armazenadas. As
três primeiras opções acima devem fornecer bons padrões para a maioria dos aplicativos de forma semelhante a
como o ASP.NET <machineKey > rotinas de geração automática funcionavam no passado. A opção de fallback
final é o único cenário que exige que o desenvolvedor especifique configuração antecipado se quiserem
persistência de chave, mas essa fallback só ocorre em situações raras.
Ao hospedar em um contêiner do Docker, as chaves devem ser persistentes em uma pasta que é um volume do
Docker (um volume compartilhado ou um volume montado de host que persiste além do tempo de vida do
contêiner) ou em um provedor externo, como Azure Key Vault ou Redis. Um provedor externo também é útil em
cenários de web farm se os aplicativos não podem acessar um volume compartilhado de rede (consulte
PersistKeysToFileSystem para obter mais informações).
WARNING
Se o desenvolvedor substitui as regras descritas acima e aponta o sistema de proteção de dados em um repositório de
chave específico, a criptografia automática de chaves em repouso está desabilitada. Proteção em repouso pode ser
reabilitada por meio configuração.
Vida útil da chave

Por padrão, as chaves têm um tempo de vida de 90 dias. Quando uma chave expira, o aplicativo gera uma nova
chave automaticamente e define a nova chave como a chave ativa. Chaves obsoletos permanecerão no sistema,
desde que seu aplicativo pode descriptografar todos os dados protegidos com eles. Ver gerenciamento de
chaves para obter mais informações.
Algoritmos padrão
O algoritmo de proteção de conteúdo padrão usado é AES -256-CBC para confidencialidade e HMACSHA256
autenticidade. Uma chave mestra de 512 bits, alterada a cada 90 dias, é usada para derivar as duas chaves de
subpropriedades usadas para esses algoritmos em uma base por carga. Ver subchave derivação para obter mais
informações.
Recursos adicionais
Extensibilidade de gerenciamento de chaves no ASP.NET Core
Suporte a política de máquina de proteção de
dados no ASP.NET Core
Por Rick Anderson

Quando em execução no Windows, o sistema de proteção de dados tem suporte limitado para definir uma
política de todo o computador padrão para todos os aplicativos que consomem a proteção de dados do
ASP.NET Core. A ideia geral é que um administrador pode querer alterar uma configuração padrão, como os
algoritmos usados ou a vida útil da chave, sem a necessidade de atualizar manualmente cada aplicativo no
computador.
WARNING
O administrador do sistema pode definir a política padrão, mas eles não é possível impor a ele. O desenvolvedor do
aplicativo sempre pode substituir qualquer valor com um dos seus próprios escolhendo. A política padrão afeta somente os
aplicativos em que o desenvolvedor não foi especificado um valor explícito para uma configuração.
Configuração de política padrão

Para definir a política padrão, um administrador pode definir os valores conhecidos no registro do sistema na
seguinte chave do registro:
HKLM\SOFTWARE\Microsoft\DotNetPackages\Microsoft.AspNetCore.DataProtection
Se você estiver em um sistema operacional de 64 bits e quiser afetar o comportamento de aplicativos de 32 bits,
lembre-se de configurar o equivalente Wow6432Node a chave acima.
Os valores com suporte são mostrados abaixo.
VALOR TIPO DESCRIÇÃO
EncryptionType cadeia de caracteres Especifica os algoritmos que devem ser

usados para proteção de dados. O
valor deve ser CBC CNG, GCM CNG ou
gerenciado e é descrito com mais
detalhes abaixo.
DefaultKeyLifetime DWORD Especifica o tempo de vida para chaves

geradas recentemente. O valor é
especificado em dias e deve ser > = 7.
KeyEscrowSinks cadeia de caracteres Especifica os tipos que são usados para

caução de chaves. O valor é uma lista
separada por ponto-e-vírgula de
Coletores de caução de chaves, onde
cada elemento na lista é o nome
qualificado do assembly de um tipo
que implementa IKeyEscrowSink.
Tipos de criptografia
Se EncryptionType é CBC CNG, o sistema está configurado para usar uma codificação de bloco simétrica de
modo CBC para confidencialidade e HMAC autenticidade com serviços fornecidos pelo Windows CNG (consulte
especificando algoritmos personalizados de Windows CNG para mais detalhes). Os seguintes valores adicionais
são suportados, cada uma correspondendo a uma propriedade do tipo CngCbcAuthenticatedEncryptionSettings.
EncryptionAlgorithm cadeia de caracteres O nome de um algoritmo de

criptografia simétrica bloco entendido
pelo CNG. Esse algoritmo é aberto no
modo CBC.
EncryptionAlgorithmProvider cadeia de caracteres O nome da implementação do

provedor CNG que pode produzir o
algoritmo EncryptionAlgorithm.
EncryptionAlgorithmKeySize DWORD O comprimento (em bits) da chave

derivada para o algoritmo de
criptografia simétrica de bloco.
HashAlgorithm cadeia de caracteres O nome de um algoritmo de hash

entendido pelo CNG. Esse algoritmo é
aberto no modo HMAC.
HashAlgorithmProvider cadeia de caracteres O nome da implementação do

algoritmo HashAlgorithm.
Se EncryptionType é GCM CNG, o sistema está configurado para usar uma codificação de bloco simétrica de
modo Galois/contador para autenticidade e confidencialidade com serviços fornecidos pelo Windows CNG
(consulte especificando algoritmos personalizados de Windows CNG Para obter mais detalhes). Os seguintes
valores adicionais são suportados, cada uma correspondendo a uma propriedade do tipo
CngGcmAuthenticatedEncryptionSettings.
EncryptionAlgorithm cadeia de caracteres O nome de um algoritmo de

criptografia simétrica bloco entendido
pelo CNG. Esse algoritmo é aberto no
modo de Galois/contador.
EncryptionAlgorithmProvider cadeia de caracteres O nome da implementação do

algoritmo EncryptionAlgorithm.

derivada para o algoritmo de
criptografia simétrica de bloco.
Se EncryptionType for gerenciado, o sistema está configurado para usar um SymmetricAlgorithm gerenciado
para confidencialidade e KeyedHashAlgorithm autenticidade (consulte especificando personalizado gerenciado
algoritmos para obter mais detalhes). Os seguintes valores adicionais são suportados, cada uma correspondendo
a uma propriedade do tipo ManagedAuthenticatedEncryptionSettings.
EncryptionAlgorithmType cadeia de caracteres O nome qualificado do assembly de

um tipo que implementa
SymmetricAlgorithm.

para derivar o algoritmo de criptografia
simétrica.
ValidationAlgorithmType cadeia de caracteres O nome qualificado do assembly de

um tipo que implementa
KeyedHashAlgorithm.
Se EncryptionType tiver qualquer valor diferente de nulo ou vazio, o sistema de proteção de dados gera uma
exceção durante a inicialização.
WARNING
Ao configurar uma configuração de política padrão que envolve os nomes de tipo (EncryptionAlgorithmType,
ValidationAlgorithmType, KeyEscrowSinks), os tipos devem estar disponíveis para o aplicativo. Isso significa que para
aplicativos em execução no CLR de área de trabalho, os assemblies que contêm esses tipos devem estar presentes no
Cache de Assembly Global (GAC). Para aplicativos do ASP.NET Core em execução no .NET Core, os pacotes que contêm
esses tipos devem ser instalados.
Cenários de reconhecimento não DI para proteção
de dados no ASP.NET Core
Por Rick Anderson

O sistema de proteção de dados do ASP.NET Core é normalmente adicionada a um contêiner de serviço e
consumido por componentes dependentes por meio de injeção de dependência (DI). No entanto, há casos em
que isso não é possível ou desejado, especialmente ao importar o sistema para um aplicativo existente.
Para dar suporte a esses cenários, o Microsoft.AspNetCore.DataProtection.Extensions pacote fornece um tipo
concreto, DataProtectionProvider, que oferece uma maneira simples de usar a proteção de dados sem depender
de injeção de dependência. O DataProtectionProvider tipo implementa IDataProtectionProvider. Construindo
DataProtectionProvider requer apenas fornecer um DirectoryInfo instância para indicar onde as chaves de
criptografia do provedor devem ser armazenadas, como mostrado no exemplo de código a seguir:
using System;
using System.IO;

{
{
// Get the path to %LOCALAPPDATA%\myapp-keys
var destFolder = Path.Combine(
System.Environment.GetEnvironmentVariable("LOCALAPPDATA"),
"myapp-keys");
// Instantiate the data protection system at this folder

var dataProtectionProvider = DataProtectionProvider.Create(
new DirectoryInfo(destFolder));
var protector = dataProtectionProvider.CreateProtector("Program.No-DI");

var input = Console.ReadLine();
// Protect the payload

var protectedPayload = protector.Protect(input);
// Unprotect the payload

var unprotectedPayload = protector.Unprotect(protectedPayload);
Console.WriteLine();
Console.WriteLine("Press any key...");
Console.ReadKey();
}
}
/*
* SAMPLE OUTPUT
*
* Protect returned: CfDJ8FWbAn6...ch3hAPm1NJA
*
* Press any key...
*/
Por padrão, o DataProtectionProvider tipo concreto não criptografa a chave primas persisti-los antes do sistema
de arquivos. Isso é para dar suporte a cenários onde os pontos de desenvolvedor para um compartilhamento de
rede e o sistema de proteção de dados não é possível deduzir automaticamente um mecanismo de criptografia
de chave apropriado em repouso.
Além disso, o DataProtectionProvider tipo concreto não isolar os aplicativos por padrão. Todos os aplicativos
usando o mesmo diretório principal podem compartilhar cargas, contanto que seus finalidade parâmetros
corresponder.
O DataProtectionProvider construtor aceita um retorno de chamada de configuração opcional que pode ser
usado para ajustar os comportamentos do sistema. O exemplo a seguir demonstra o isolamento de restauração
com uma chamada explícita para SetApplicationName. O exemplo também demonstra como configurar o
sistema para criptografar automaticamente chaves persistentes usando Windows DPAPI. Se o diretório aponta
para um compartilhamento UNC, você poderá distribuir um certificado compartilhado por todos os
computadores relevantes e para configurar o sistema para usar a criptografia baseada em certificado com uma
chamada para ProtectKeysWithCertificate.
using System;
using System.IO;

{
{
// Get the path to %LOCALAPPDATA%\myapp-keys
var destFolder = Path.Combine(
System.Environment.GetEnvironmentVariable("LOCALAPPDATA"),
"myapp-keys");
// Instantiate the data protection system at this folder

var dataProtectionProvider = DataProtectionProvider.Create(
new DirectoryInfo(destFolder),
configuration =>
{
configuration.SetApplicationName("my app name");
configuration.ProtectKeysWithDpapi();
});
var protector = dataProtectionProvider.CreateProtector("Program.No-DI");

var input = Console.ReadLine();
// Protect the payload

var protectedPayload = protector.Protect(input);
// Unprotect the payload

var unprotectedPayload = protector.Unprotect(protectedPayload);
Console.WriteLine();
Console.WriteLine("Press any key...");
Console.ReadKey();
}
}
TIP
Instâncias de DataProtectionProvider tipo concreto são caros de criar. Se um aplicativo mantém várias instâncias desse
tipo e se eles estão usando o mesmo diretório de armazenamento de chaves, pode afetar o desempenho do aplicativo. Se
você usar o DataProtectionProvider tipo, recomendamos que você cria esse tipo de uma vez e reutilizá-la tanto quanto
possível. O DataProtectionProvider tipo e todos os IDataProtector instâncias criadas a partir dela são thread-safe para
chamadores vários.
APIs de extensibilidade de proteção de dados do
ASP.NET Core

APIs diversas
Extensibilidade da criptografia de núcleo no núcleo
do ASP.NET
WARNING
Tipos que implementam qualquer uma das seguintes interfaces devem ser thread-safe para chamadores vários.
IAuthenticatedEncryptor
O IAuthenticatedEncryptor interface é o bloco de construção básico do subsistema de criptografia. Em geral,
há um IAuthenticatedEncryptor por chave e a instância IAuthenticatedEncryptor encapsula todas as material de
chave de criptografia e algoritmos informações necessárias para executar operações criptográficas.
Como o nome sugere, o tipo é responsável por fornecer serviços de criptografia e descriptografia autenticados.
Expõe as APIs a seguir.
Descriptografar (ArraySegment texto cifrado, ArraySegment additionalAuthenticatedData): byte]
Criptografar (ArraySegment texto sem formatação, ArraySegment additionalAuthenticatedData): byte]
O método Encrypt retorna um blob que inclui o texto não criptografado enciphered e uma marca de autenticação.
A marca de autenticação deve abranger os dados adicionais autenticados (AAD ), embora o AAD em si não precisa
ser recuperável da carga final. O método Decrypt valida a marca de autenticação e retorna a carga deciphered.
Todas as falhas (exceto ArgumentNullException e semelhante) devem ser homogenized para
CryptographicException.
NOTE
A própria instância IAuthenticatedEncryptor, na verdade, não precisa conter o material da chave. Por exemplo, a
implementação pudesse ser delegado a um HSM para todas as operações.
Como criar um IAuthenticatedEncryptor

ASP.NET Core 2.x
ASP.NET Core 1.x
O IAuthenticatedEncryptorFactory interface representa um tipo que sabe como criar um
IAuthenticatedEncryptor instância. Sua API é o seguinte.
CreateEncryptorInstance (chave IKey): IAuthenticatedEncryptor
Para qualquer instância específica de IKey os qualquer intermediária autenticada criada por seu método
CreateEncryptorInstance deve ser consideradas equivalentes, como o exemplo de código abaixo.
// we have an IAuthenticatedEncryptorFactory instance and an IKey instance
IAuthenticatedEncryptorFactory factory = ...;
IKey key = ...;
// get an encryptor instance and perform an authenticated encryption operation

ArraySegment<byte> plaintext = new ArraySegment<byte>(Encoding.UTF8.GetBytes("plaintext"));
ArraySegment<byte> aad = new ArraySegment<byte>(Encoding.UTF8.GetBytes("AAD"));
var encryptor1 = factory.CreateEncryptorInstance(key);
byte[] ciphertext = encryptor1.Encrypt(plaintext, aad);
// get another encryptor instance and perform an authenticated decryption operation

var encryptor2 = factory.CreateEncryptorInstance(key);
byte[] roundTripped = encryptor2.Decrypt(new ArraySegment<byte>(ciphertext), aad);
// the 'roundTripped' and 'plaintext' buffers should be equivalent
IAuthenticatedEncryptorDescriptor (ASP.NET Core 2. x somente)

ASP.NET Core 2.x
ASP.NET Core 1.x
O IAuthenticatedEncryptorDescriptor interface representa um tipo que sabe como exportar em si para XML.
Sua API é o seguinte.
ExportToXml(): XmlSerializedDescriptorInfo
Serialização XML
A principal diferença entre IAuthenticatedEncryptor e IAuthenticatedEncryptorDescriptor é que o descritor sabe
como criar o Criptografador e fornecê-lo com os argumentos válidos. Considere um IAuthenticatedEncryptor cuja
implementação depende do SymmetricAlgorithm e KeyedHashAlgorithm. Trabalho do Criptografador é consumir
esses tipos, mas não necessariamente souber onde esses tipos de origem, para que ele realmente não é possível
gravar uma descrição adequada do como recriar a mesmo se o aplicativo for reiniciado. O descritor de atua como
um nível superior sobre isso. Desde que o descritor sabe como criar a instância do Criptografador (por exemplo,
sabe como criar os algoritmos necessários), ele pode serializar esse conhecimento em formato XML para que a
instância do Criptografador pode ser recriada após a redefinição de um aplicativo.
O descritor de pode ser serializado por meio de sua rotina de ExportToXml. Esta rotina retorna um
XmlSerializedDescriptorInfo que contém duas propriedades: a representação de XElement do descritor e o tipo
que representa um IAuthenticatedEncryptorDescriptorDeserializer que pode ser usado para lembrar Esse
descritor fornecido o XElement correspondente.
O descritor de serializado pode conter informações confidenciais, como o material de chave de criptografia. O
sistema de proteção de dados tem suporte interno para criptografar informações antes de ele tem persistidos
para armazenamento. Para tirar proveito disso, o descritor deve marcar o elemento que contém informações
confidenciais com o nome do atributo "requiresEncryption" (xmlns
"http://schemas.asp.net/2015/03/dataProtection"), valor "true".
TIP
Há um auxiliar de API para a configuração deste atributo. Chame o método de extensão que
XElement.markasrequiresencryption() localizado no namespace
Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel.
Também pode haver casos onde o descritor serializado não contêm informações confidenciais. Considere
novamente o caso de uma chave de criptografia armazenada em um HSM. Não é possível gravar o descritor de
material de chave ao serializar em si, pois o HSM não expõe o material em forma de texto sem formatação. Em
vez disso, o descritor pode gravar a versão de chave de linha de chave (se o HSM permite exportar dessa forma)
ou o identificador exclusivo do HSM para a chave.
IAuthenticatedEncryptorDescriptorDeserializer
O IAuthenticatedEncryptorDescriptorDeserializer interface representa um tipo que sabe como desserializar
uma instância IAuthenticatedEncryptorDescriptor de um XElement. Ela expõe um único método:
ImportFromXml (elemento de XElement): IAuthenticatedEncryptorDescriptor
O método ImportFromXml usa o XElement foi retornado por IAuthenticatedEncryptorDescriptor.ExportToXml e
cria um equivalente a IAuthenticatedEncryptorDescriptor original.
Tipos que implementam IAuthenticatedEncryptorDescriptorDeserializer devem ter um dos dois construtores
públicos a seguir:
.ctor(IServiceProvider)
.ctor()
NOTE
O IServiceProvider transmitido ao construtor pode ser nulo.
A fábrica de nível superior

ASP.NET Core 2.x
ASP.NET Core 1.x
O AlgorithmConfiguration classe representa um tipo que sabe como criar IAuthenticatedEncryptorDescriptor
instâncias. Ela expõe uma única API.
CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor
Pense AlgorithmConfiguration como a fábrica de nível superior. A configuração funciona como um modelo. Ela
inclui informações de algoritmos (por exemplo, essa configuração produz descritores com uma chave mestra de
AES -128-GCM ), mas ela ainda não está associada com uma chave específica.
Quando CreateNewDescriptor é chamado, novo material de chave é criada somente para essa chamada e um
novo IAuthenticatedEncryptorDescriptor é produzido que encapsula o material de chave e as informações de
algoritmos necessária para consumir o material. O material da chave pode ser criado no software (e mantido na
memória), ele pode ser criado e mantido em um HSM e assim por diante. O ponto fundamental é que as duas
chamadas para CreateNewDescriptor nunca devem criar instâncias de IAuthenticatedEncryptorDescriptor
equivalentes.
O tipo de AlgorithmConfiguration serve como ponto de entrada para rotinas de criação da chave como chave
automática. Para alterar a implementação para todas as chaves futuras, defina a propriedade de
AuthenticatedEncryptorConfiguration em KeyManagementOptions.
Extensibilidade de gerenciamento de chaves no
ASP.NET Core
TIP
Leia as gerenciamento de chaves seção antes de ler esta seção, pois ele explica alguns dos conceitos fundamentais dessas
APIs.
WARNING
Chave
O IKey interface é a representação básica de uma chave no sistema de criptografia. A chave do termo é usada
aqui no sentido abstrato, não no sentido literal "criptográfico do material da chave". Uma chave tem as seguintes
propriedades:
Datas de expiração, criação e ativação
Status de revogação
Identificador de chave (um GUID )
Além disso, IKey expõe uma CreateEncryptor método que pode ser usado para criar um
IAuthenticatedEncryptor instância vinculado a essa chave.
Além disso, IKey expõe uma CreateEncryptorInstance método que pode ser usado para criar um
IAuthenticatedEncryptor instância vinculado a essa chave.
NOTE
Há uma API para recuperar o material criptográfico bruto de um IKey instância.
IKeyManager
O IKeyManager interface representa um objeto responsável pelo armazenamento de chaves geral, a recuperação e
a manipulação. Ele expõe três operações de alto nível:
Criar uma nova chave e mantê-lo no armazenamento.
Obter todas as chaves de armazenamento.
Revogar uma ou mais chaves e persistir as informações de revogação para o armazenamento.
WARNING
Escrevendo um IKeyManager é uma tarefa muito avançada e a maioria dos desenvolvedores não deve tentá-lo. Em vez
disso, a maioria dos desenvolvedores deve tirar vantagem dos recursos oferecidos pelo XmlKeyManager classe.
XmlKeyManager
O XmlKeyManager tipo é a implementação concreta da caixa de entrada da IKeyManager . Ele fornece vários
recursos úteis, incluindo caução de chaves e criptografia de chaves em repouso. Chaves nesse sistema são
representadas como elementos XML (especificamente, XElement).
XmlKeyManager depende de vários outros componentes no decorrer de cumprir suas tarefas:
AlgorithmConfiguration , que determina os algoritmos usados por novas chaves.
IXmlRepository , que controla onde as chaves são mantidas no armazenamento.
IXmlEncryptor [opcional], que permite criptografar as chaves em repouso.
IKeyEscrowSink [opcional], que fornece serviços de caução de chaves.
IXmlRepository , que controla onde as chaves são mantidas no armazenamento.

IXmlEncryptor [opcional], que permite criptografar as chaves em repouso.
IKeyEscrowSink [opcional], que fornece serviços de caução de chaves.
Abaixo estão os diagramas de alto nível que indicam como esses componentes são vinculados dentro
XmlKeyManager .
Criação de chave / CreateNewKey

Na implementação de CreateNewKey , o AlgorithmConfiguration componente é usado para criar um único
IAuthenticatedEncryptorDescriptor , que é então serializado como XML. Se um coletor de caução de chave estiver
presente, o XML bruto de (não criptografado) é fornecido para o coletor para armazenamento de longo prazo. O
XML não criptografado é executado por meio de um IXmlEncryptor (se necessário) para gerar o documento XML
criptografado. Este documento criptografado é persistido no armazenamento de longo prazo via o
IXmlRepository . ( Se nenhum IXmlEncryptor é configurado, o documento não criptografado é persistido no
IXmlRepository .)
Criação de chave / CreateNewKey
Na implementação de CreateNewKey , o IAuthenticatedEncryptorConfiguration componente é usado para criar um
único IAuthenticatedEncryptorDescriptor , que é então serializado como XML. Se um coletor de caução de chave
estiver presente, o XML bruto de (não criptografado) é fornecido para o coletor para armazenamento de longo
prazo. O XML não criptografado é executado por meio de um IXmlEncryptor (se necessário) para gerar o
documento XML criptografado. Este documento criptografado é persistido no armazenamento de longo prazo via
o IXmlRepository . (Se nenhum IXmlEncryptor é configurado, o documento não criptografado é persistido no
IXmlRepository .)
Recuperação de chave / GetAllKeys

Na implementação de GetAllKeys , o XML documenta as chaves que representa e revogações são lidas do
subjacente IXmlRepository . Se esses documentos são criptografados, o sistema automaticamente descriptografá-
los. XmlKeyManager cria o apropriada IAuthenticatedEncryptorDescriptorDeserializer instâncias para desserializar
os documentos de volta para o IAuthenticatedEncryptorDescriptor instâncias, que, em seguida, são encapsuladas
em indivíduo IKey instâncias. Esta coleção de IKey instâncias é retornado ao chamador.
Obter mais informações sobre os elementos XML específicos podem ser encontradas na documentos de formato
de armazenamento de chaves.
IXmlRepository
O IXmlRepository interface representa um tipo que pode persistir o XML para e recuperar o XML de um
armazenamento de backup. Ele expõe duas APIs:
GetAllElements : IReadOnlyCollection<XElement>
StoreElement(XElement element, string friendlyName)
Implementações de IXmlRepository não precisam analisar o XML passar através deles. Eles devem tratar os
documentos XML como opaco e permitir que camadas superiores se preocupar sobre como gerar e analisar os
documentos.
Há quatro tipos concretos internos que implementam IXmlRepository :
FileSystemXmlRepository
RegistryXmlRepository
AzureStorage.AzureBlobXmlRepository
RedisXmlRepository
FileSystemXmlRepository
RegistryXmlRepository
AzureStorage.AzureBlobXmlRepository
RedisXmlRepository
Consulte a documentos de provedores de armazenamento de chaves para obter mais informações.
Registrando um personalizado IXmlRepository é apropriado ao usar um armazenamento de backup diferente
(por exemplo, armazenamento de tabela do Azure).
Para alterar o repositório padrão todo o aplicativo, registre um personalizado IXmlRepository instância:
services.Configure<KeyManagementOptions>(options => options.XmlRepository = new MyCustomXmlRepository());
services.AddSingleton<IXmlRepository>(new MyCustomXmlRepository());
IXmlEncryptor
O IXmlEncryptor interface representa um tipo que pode criptografar um elemento XML de texto sem formatação.
Ela apresenta uma única API:
Criptografar (plaintextElement XElement): EncryptedXmlInfo
Se um serializado IAuthenticatedEncryptorDescriptor contém quaisquer elementos marcados como "requer
criptografia", em seguida, XmlKeyManager executará esses elementos por meio do configurado IXmlEncryptor do
Encrypt método e ele serão mantido o elemento adulterem em vez de elemento de texto sem formatação para o
IXmlRepository . A saída a Encrypt método é um EncryptedXmlInfo objeto. Esse objeto é um wrapper que contém
os dois o resultante adulterem XElement e o tipo que representa um IXmlDecryptor que pode ser usado para
decifrar o elemento correspondente.
Há quatro tipos concretos internos que implementam IXmlEncryptor :
CertificateXmlEncryptor
DpapiNGXmlEncryptor
DpapiXmlEncryptor
NullXmlEncryptor
Consulte a criptografia de chave em documentos do rest para obter mais informações.
Para alterar o mecanismo padrão de chave criptografia em repouso todo o aplicativo, registre um personalizado
IXmlEncryptor instância:
services.Configure<KeyManagementOptions>(options => options.XmlEncryptor = new MyCustomXmlEncryptor());
services.AddSingleton<IXmlEncryptor>(new MyCustomXmlEncryptor());
IXmlDecryptor
O IXmlDecryptor interface representa um tipo que sabe como descriptografar um XElement que foi adulterem
por meio de um IXmlEncryptor . Ela apresenta uma única API:
Descriptografar (encryptedElement XElement): XElement
O método desfaz a criptografia executada pelo IXmlEncryptor.Encrypt . Em geral, cada concreto
Decrypt
IXmlEncryptor implementação terá um concreto correspondente IXmlDecryptor implementação.
Tipos que implementam IXmlDecryptor deve ter um dos dois construtores públicos a seguir:
.ctor(IServiceProvider)
.ctor()
NOTE
O IServiceProvider passado para o construtor pode ser nulo.
IKeyEscrowSink
O IKeyEscrowSink interface representa um tipo que pode executar a caução de informações confidenciais.
Lembre-se de que descritores serializados podem conter informações confidenciais (por exemplo, o material
criptográfico), e esse é o que levou à introdução do IXmlEncryptor digite em primeiro lugar. No entanto, acidentes
acontecem e anéis de chave podem ser excluídos ou corrompidos.
A interface de caução fornece uma hachura de escape de emergência, permitindo o acesso ao XML bruto
serializado antes que ele é transformado por qualquer configurados IXmlEncryptor. A interface expõe uma única
API:
Store (keyId Guid, o elemento de XElement)
Cabe ao IKeyEscrowSink implementação para lidar com o elemento fornecido de maneira segura consistente com
a política de negócios. Uma possível implementação pode ser para o coletor de caução criptografar o elemento
XML usando um certificado x. 509 corporativo reconhecido onde chave privada do certificado tenha sido mantida
em garantia; o CertificateXmlEncryptor tipo pode ajudar com isso. O IKeyEscrowSink implementação também é
responsável por manter o elemento fornecido adequadamente.
Por padrão nenhum mecanismo de caução está habilitado, embora os administradores de servidor podem
configurar isso globalmente. Ele também pode ser configurado por meio de programação por meio de
IDataProtectionBuilder.AddKeyEscrowSink método conforme mostrado no exemplo a seguir. O AddKeyEscrowSink
espelho de sobrecargas do método de IServiceCollection.AddSingleton e IServiceCollection.AddInstance
sobrecargas, como IKeyEscrowSink instâncias devem ser singletons. Se vários IKeyEscrowSink instâncias
registradas, cada um deles será chamado durante a geração de chave, para que as chaves podem ser mantida em
garantia para diversos mecanismos simultaneamente.
Há uma API para ler o material de um IKeyEscrowSink instância. Isso é consistente com a teoria de design do
mecanismo de caução: ele deve disponibilizar o material da chave para uma autoridade confiável, e uma vez que o
aplicativo em si não é uma autoridade confiável, ele não deve ter acesso ao seu próprio caucionada material.
O código de exemplo a seguir demonstra como criar e registrar um IKeyEscrowSink onde as chaves são mantida
em garantia, de modo que somente os membros do grupo "administradores de CONTOSODomain" poderá
recuperá-los.
NOTE
Para executar este exemplo, você deve estar em um domínio do Windows 8 / máquina Windows Server 2012 e o
controlador de domínio devem ser Windows Server 2012 ou posterior.
using System;
using System.IO;
using System.Xml.Linq;
using Microsoft.AspNetCore.DataProtection.XmlEncryption;

{
{
.ProtectKeysWithDpapi()
.AddKeyEscrowSink(sp => new MyKeyEscrowSink(sp));
// get a reference to the key manager and force a new key to be generated
Console.WriteLine("Generating new key...");
keyManager.CreateNewKey(
activationDate: DateTimeOffset.Now,
expirationDate: DateTimeOffset.Now.AddDays(7));
}
// A key escrow sink where keys are escrowed such that they
// can be read by members of the CONTOSO\Domain Admins group.
private class MyKeyEscrowSink : IKeyEscrowSink
{
private readonly IXmlEncryptor _escrowEncryptor;
public MyKeyEscrowSink(IServiceProvider services)

{
// Assuming I'm on a machine that's a member of the CONTOSO
// domain, I can use the Domain Admins SID to generate an
// encrypted payload that only they can read. Sample SID from
// https://technet.microsoft.com/library/cc778824(v=ws.10).aspx.
_escrowEncryptor = new DpapiNGXmlEncryptor(
"SID=S-1-5-21-1004336348-1177238915-682003330-512",
DpapiNGProtectionDescriptorFlags.None,
services);
}
public void Store(Guid keyId, XElement element)

{
// Encrypt the key element to the escrow encryptor.
var encryptedXmlInfo = _escrowEncryptor.Encrypt(element);
// A real implementation would save the escrowed key to a

// write-only file share or some other stable storage, but
// in this sample we'll just write it out to the console.
Console.WriteLine($"Escrowing key {keyId}");
Console.WriteLine(encryptedXmlInfo.EncryptedElement);
// Note: We cannot read the escrowed key material ourselves.

// We need to get a member of CONTOSO\Domain Admins to read
// it for us in the event we need to recover it.
}
}
}
/*
* SAMPLE OUTPUT
*
* Generating new key...
* Escrowing key 38e74534-c1b8-4b43-aea1-79e856a822e5
* <encryptedKey>
* 
* 
* <value>MIIIfAYJKoZIhvcNAQcDoIIIbTCCCGkCAQ...T5rA4g==</value>
* </encryptedKey>
*/
APIs de proteção de dados de diversos principais do
ASP.NET
WARNING
ISecret
O ISecret interface representa um valor de segredo, como o material de chave de criptografia. Ele contém a
superfície de API a seguir:
Length : int
Dispose() : void
WriteSecretIntoBuffer(ArraySegment<byte> buffer) : void
O WriteSecretIntoBuffer método preenche o buffer fornecido com o valor bruto de segredo. O motivo pelo qual
essa API usa o buffer como um parâmetro em vez de retornar um byte[] diretamente é que isso permite que o
chamador fixar o objeto de buffer, limitar a exposição de segredo para o coletor de lixo gerenciada.
O Secret tipo é uma implementação concreta de ISecret onde o valor de segredo é armazenado na memória no
processo. Em plataformas Windows, o valor do segredo é criptografado por meio de CryptProtectMemory.
Implementação da proteção de dados do ASP.NET
Core

Detalhes de criptografia autenticada no núcleo do
ASP.NET
Chamadas para IDataProtector.Protect são as operações de criptografia autenticada. O método Protect oferece
confidencialidade e a autenticidade e ela é vinculada à cadeia finalidade que foi usada para essa instância
específica do IDataProtector derivam da sua raiz IDataProtectionProvider.
IDataProtector.Protect usa um parâmetro de texto sem formatação do byte [] e produz uma byte [] protegido
carga, cujo formato é descrito abaixo. (Também há uma sobrecarga de método de extensão que usa um parâmetro
de texto sem formatação da cadeia de caracteres e retorna uma carga protegido de cadeia de caracteres. Se essa
API é usada ainda terá o formato de carga protegido o abaixo de estrutura, mas será codificado base64url.)
Formato de conteúdo protegido

O formato de carga protegido consiste em três componentes principais:
Um cabeçalho mágico de 32 bits que identifica a versão do sistema de proteção de dados.
Uma id de 128 bits chave que identifica a chave usada para proteger essa carga específica.
O restante da carga protegido é específico para o Criptografador encapsulado por esta chave. No exemplo
a seguir a chave representa um AES -256-CBC + Criptografador HMACSHA256 e a carga é mais
subdividida da seguinte maneira: * modificador chave A 128 bits. * Um vetor de inicialização de 128 bits. *
48 bytes de saída de AES -256-CBC. * Uma marca de autenticação HMACSHA256.
Uma carga protegido exemplo ilustrada abaixo.
09 F0 C9 F0 80 9C 81 0C 19 66 19 40 95 36 53 F8
AA FF EE 57 57 2F 40 4C 3F 7F CC 9D CC D9 32 3E
84 17 99 16 EC BA 1F 4A A1 18 45 1F 2D 13 7A 28
79 6B 86 9C F8 B7 84 F9 26 31 FC B1 86 0A F1 56
61 CF 14 58 D3 51 6F CF 36 50 85 82 08 2D 3F 73
5F B0 AD 9E 1A B2 AE 13 57 90 C8 F5 7C 95 4E 6A
8A AA 06 EF 43 CA 19 62 84 7C 11 B2 C8 71 9D AA
52 19 2E 5B 4C 1E 54 F0 55 BE 88 92 12 C1 4B 5E
52 C9 74 A0
O formato de carga acima os primeiros 32 bits ou 4 bytes são o cabeçalho magic identifica a versão (09 F0 C9 F0)
O próximos 128 bits ou 16 bytes é o identificador de chave (80 9 81 de C 0C 19 66 19 40 95 36 53 F8 AA FF EE
57)
O restante contém a carga e é específico para o formato usado.
WARNING
Todas as cargas protegidas para uma determinada chave começa com o mesmo cabeçalho de 20 bytes (valor mágico, id de
chave). Os administradores podem usar esse fato para fins de diagnóstico para aproximar quando uma carga foi gerada. Por
exemplo, a carga acima corresponde à chave {0c819c80-6619-4019-9536-53f8aaffee57}. Se depois de verificar se o
repositório de chave achar que a data de ativação dessa chave específica era 2015-01-01 e data de expiração foi 2015-03-
01, é razoável pressupor que a carga (se não violada) foi gerada dentro dessa janela, dê ou levar um pequeno fator em
ambos os lados.
Derivação subchave e criptografia autenticada no
núcleo do ASP.NET
A maioria das chaves do anel de chave contém alguma forma de entropia e terá informações algorítmicos
informando "criptografia de modo CBC + validação HMAC" ou "criptografia GCM + validação". Nesses casos, nos
referimos a entropia inserida como o material de chave mestre (ou KM ) para essa chave e podemos executar uma
função de derivação de chave para derivar as chaves que serão usadas para operações de criptografia reais.
NOTE
As chaves são abstratas e uma implementação personalizada pode não se comportar como abaixo. Se a chave fornece sua
própria implementação do IAuthenticatedEncryptor em vez de usar uma das nossas fábricas internas, o mecanismo
descrito nesta seção não se aplica.
Dados autenticados adicionais e subchave derivação

O IAuthenticatedEncryptor interface serve como a interface principal para todas as operações de criptografia
autenticada. Seu Encrypt método usa dois buffers: texto sem formatação e additionalAuthenticatedData (AAD ). O
fluxo de conteúdo de texto sem formatação inalterado a chamada para IDataProtector.Protect , mas o AAD é
gerado pelo sistema e consiste em três componentes:
1. 32 bits magic cabeçalho 09 F0 C9 F0 que identifica esta versão do sistema de proteção de dados.
2. A id de chave de 128 bits.
3. Uma cadeia de caracteres de comprimento variável formada da cadeia de finalidade que criou o
IDataProtector que está executando esta operação.
Como o AAD é exclusivo para a tupla de todos os três componentes, podemos usá-lo derivar novas chaves KM
em vez de usar KM em si em todos os nossos operações criptográficas. Para todas as chamadas para
IAuthenticatedEncryptor.Encrypt , ocorre o processo de derivação de chaves a seguir:
(K_E, K_H) = SP800_108_CTR_HMACSHA512 (contextHeader K_M, AAD, | | keyModifier)

Aqui, estamos ligando para o NIST SP800-108 KDF no modo de contador (consulte NIST SP800-108, SEC 5.1)
com os seguintes parâmetros:
Chave de derivação de chave (KDK) = K_M
PRF = HMACSHA512
rótulo = additionalAuthenticatedData
context = contextHeader || keyModifier
O cabeçalho de contexto é de comprimento variável e essencialmente serve como uma impressão digital dos
algoritmos para a qual estamos estiver derivando K_E e K_H. O modificador de chave é uma cadeia de caracteres
de 128 bits gerada aleatoriamente para cada chamada Encrypt e serve para garantir com grandes probabilidade
que KE e KH são exclusivas para essa operação de criptografia de autenticação específico, mesmo se todas as
outras entradas para o KDF é constante.
Para criptografia de modo CBC + operações de validação de HMAC, | K_E | é o comprimento da chave de
criptografia simétrica bloco, e | K_H | é o tamanho do resumo da rotina de HMAC. Para criptografia GCM +
operações de validação, | K_H | = 0.
Criptografia de modo CBC + validação HMAC

Depois de K_E é gerado por meio do mecanismo acima, podemos gerar um vetor de inicialização aleatória e
executar o algoritmo de criptografia simétrica de bloco para codificar o texto não criptografado. O vetor de
inicialização e o texto cifrado são, em seguida, executar a rotina HMAC inicializada com a chave K_H para produzir
Mac. Esse processo e o valor de retorno é representado graficamente abaixo.
saída: = keyModifier | | IV | | E_cbc (dados K_E, iv,) | | HMAC (K_H, iv | | E_cbc (dados K_E, iv,))
NOTE
O IDataProtector.Protect implementação será preceda o cabeçalho magic e a id de chave a saída antes de retorná-lo ao
chamador. Porque o cabeçalho magic e a id de chave são implicitamente parte do AAD, e porque o modificador de chave é
passado como entrada para o KDF, isso significa que cada byte único da carga final retornada é autenticado pelo Mac.
Criptografia de modo Galois/contador + validação

Quando K_E é gerado por meio do mecanismo acima, podemos gerar um nonce de 96 bits aleatório e executar o
algoritmo de criptografia simétrica de bloco para codificar o texto não criptografado e produzir a marca de
autenticação de 128 bits.
saída: = keyModifier | | nonce | | E_gcm (dados de uso único, K_E,) | | authTag

NOTE
Embora GCM nativamente dá suporte ao conceito de AAD, podemos estiver ainda de alimentação AAD somente para o KDF
original, aceitar para passar uma cadeia de caracteres vazia para GCM para seu parâmetro AAD. A razão para isso é dupla.
Primeiro, para dar suporte a agilidade nunca queremos usar K_M diretamente como a chave de criptografia. Além disso,
GCM impõe requisitos de exclusividade muito estrita em suas entradas. Define a probabilidade de que a rotina de
criptografia do GCM é sempre invocado em dois ou mais distintos de dados de entrada com o mesmo (chave, nonce) par
não deve exceder 2 ^ 32. Se corrigir K_E não foi possível realizar mais de 2 ^ 32 operações de criptografia antes de podemos
executar afoul da 2 ^ limitar -32. Isso pode parecer um grande número de operações, mas um servidor web de alto tráfego
pode passar por solicitações de 4 bilhões em alguns dias, dentro do tempo de vida normal para essas chaves. Para manter a
conformidade de 2 ^ limite de probabilidade-32, podemos continuar a usar um modificador de chave de 128 bits e nonce de
96 bits, o que aumenta a contagem de operação utilizável para qualquer K_M determinado. Para manter a simplicidade de
design compartilha o caminho do código KDF entre as operações CBC e GCM e como AAD já é considerado o KDF não é
necessário encaminhá-lo para a rotina do GCM.
Cabeçalhos de contexto no núcleo do ASP.NET
Plano de fundo e a teoria

No sistema de proteção de dados, uma "chave" significa que um objeto que pode fornecer serviços de criptografia
de autenticação. Cada chave é identificado por uma id exclusiva (uma GUID ) e transporta informações
algorítmicos e material entropic. Ele destina-se que cada chave realizar entropia exclusiva, mas o sistema não pode
impor que e precisamos para desenvolvedores que podem alterar manualmente o anel de chave, modificando as
informações de algoritmos de uma chave existente do anel de chave de conta. Para alcançar nossos requisitos de
segurança fornecidos nesses casos, o sistema de proteção de dados tem um conceito de agilidade criptográfica,
que permite a com segurança usando um único valor entropic entre vários algoritmos de criptografia.
A maioria dos sistemas que oferecem suporte a agilidade criptográfica de fazer isso, incluindo algumas
informações de identificação sobre o algoritmo de carga. OID do algoritmo geralmente é uma boa candidata para
isso. No entanto, um problema que tivemos é que há várias maneiras de especificar o mesmo algoritmo: "AES"
(CNG ) e o gerenciado Aes, AesManaged, AesCryptoServiceProvider, AesCng e RijndaelManaged (fornecida
parâmetros específicos) classes são, na verdade, todos os mesmos coisa e é necessário manter um mapeamento
de tudo isso para a identificação de objeto correta. Se um desenvolvedor deseja fornecer um algoritmo
personalizado (ou até mesmo outra implementação do AES!), eles precisam Conte-nos sua OID. Essa etapa de
registro extra facilita a configuração do sistema particularmente penoso.
Recuando, decidimos que podemos foram chegando o problema de direção errada. Um OID informa o que é o
algoritmo, mas, na verdade, não importa sobre isso. Se for necessário usar um único valor entropic com segurança
em dois algoritmos diferentes, não é necessário para que possamos saber o que os algoritmos realmente são. O
que é realmente importante é como eles se comportam. Qualquer algoritmo de codificação de bloco simétrica
razoável também é uma forte permutação pseudoaleatórios (PRP ): corrija as entradas (chave, cadeia de texto sem
formatação de modo, o IV,) e a saída de texto cifrado com grandes probabilidade serão diferente dos outros
qualquer codificação de bloco simétrica algoritmo considerando as entradas do mesmo. Da mesma forma,
qualquer função de hash com chave razoável também é uma função pseudoaleatórios forte (PRF ) e fornecido um
conjunto fixo de entrada sua saída predominantemente serão diferente de qualquer outra função de hash com
chave.
Podemos usar esse conceito de alta segurança PRPs e PRFs para criar um cabeçalho de contexto. Esse cabeçalho
de contexto atua essencialmente como uma impressão digital estável sobre os algoritmos em uso para qualquer
operação especificada e fornece a agilidade criptográfica necessária ao sistema de proteção de dados. Esse
cabeçalho pode ser reproduzido e é usado posteriormente como parte do processo de derivação de subchave. Há
duas maneiras diferentes para criar o cabeçalho de contexto dependendo os modos de operação dos algoritmos
subjacentes.
Criptografia de modo CBC + autenticação HMAC

O cabeçalho de contexto consiste dos seguintes componentes:
[16 bits] O valor 00 00, o que é um marcador que significa "criptografia CBC + autenticação HMAC".
[32 bits] O comprimento da chave (em bytes, big-endian) do algoritmo de criptografia simétrica de bloco.
[32 bits] O tamanho de bloco (em bytes, big-endian) do algoritmo de criptografia simétrica de bloco.
[32 bits] O comprimento da chave (em bytes, big-endian) do algoritmo HMAC. (Atualmente o tamanho da
chave sempre coincide com o tamanho do resumo.)
[32 bits] O tamanho (em bytes, big-endian) resumo do algoritmo HMAC.
EncCBC (K_E, IV, ""), que é a saída do algoritmo de criptografia simétrica bloco recebe uma entrada de
cadeia de caracteres vazia e onde o IV é um vetor de zeros. A construção de K_E é descrita abaixo.
MAC (K_H, ""), que é a saída do algoritmo HMAC recebe uma entrada de cadeia de caracteres vazia. A
construção de K_H é descrita abaixo.
Idealmente, poderíamos passar vetores de zeros para K_E e K_H. No entanto, queremos evitar a situação em que o
algoritmo subjacente verifica a existência de baixa segurança chaves antes de executar quaisquer operações
(especialmente DES e 3DES ), que impede usando um padrão simple ou repeatable como um vetor de zeros.
Em vez disso, usamos o NIST SP800-108 KDF no modo de contador (consulte NIST SP800-108, SEC 5.1) com
uma chave de comprimento zero, o rótulo e o contexto e a HMACSHA512 como o PRF subjacente. Podemos
derivar | K_E | + | K_H | bytes de saída, em seguida, decompor o resultado em K_E e K_H próprios.
Matematicamente, isso é representado como a seguir.
( K_E || K_H ) = SP800_108_CTR (prf = HMACSHA512, key = "", label = "", context = "")
Exemplo: AES de 192 de CBC + HMACSHA256
Por exemplo, considere o caso em que o algoritmo de criptografia simétrica de bloco é AES de 192 de CBC e o
algoritmo de validação é HMACSHA256. O sistema poderia gerar o cabeçalho de contexto usando as etapas a
seguir.
Primeiro, permitem (K_E | | K_H) = SP800_108_CTR (prf = HMACSHA512, chave = "", rótulo = "", contexto = ""),
onde | K_E | = 192 bits e | K_H | = 256 bits por algoritmos especificados. Isso leva a K_E = 5BB6. 21DD e K_H =
A04A. 00A9 no exemplo a seguir:
5B B6 C9 83 13 78 22 1D 8E 10 73 CA CF 65 8E B0
61 62 42 71 CB 83 21 DD A0 4A 05 00 5B AB C0 A2
49 6F A5 61 E3 E2 49 87 AA 63 55 CD 74 0A DA C4
B7 92 3D BF 59 90 00 A9
Em seguida, calcular Enc_CBC (K_E, IV, "") para AES -192-CBC fornecido IV = 0 * e K_E como acima.
result := F474B1872B3B53E4721DE19C0841DB6F
Em seguida, o MAC de computação (K_H, "") para HMACSHA256 determinado K_H como acima.
result := D4791184B996092EE1202F36E8608FA8FBD98ABDFF5402F264B1D7211536220C
Isso gera o cabeçalho de contexto completo abaixo:
00 00 00 00 00 18 00 00 00 10 00 00 00 20 00 00
00 20 F4 74 B1 87 2B 3B 53 E4 72 1D E1 9C 08 41
DB 6F D4 79 11 84 B9 96 09 2E E1 20 2F 36 E8 60
8F A8 FB D9 8A BD FF 54 02 F2 64 B1 D7 21 15 36
22 0C
Esse cabeçalho de contexto é a impressão digital do par de algoritmo de criptografia autenticada (criptografia AES
de 192 de CBC + HMACSHA256 validação). Os componentes, conforme descrito acima são:
o marcador (00 00)
o comprimento da chave de codificação de bloco (00 00 00 18)
o tamanho de bloco de codificação de bloco (00 00 00 10)
o comprimento da chave HMAC (00 00 00 20)
o tamanho do resumo HMAC (00 00 00 20)
a codificação de bloco saída PRP (F4 74 - DB 6F ) e
a saída PRF HMAC (D4 79 - end).
NOTE
A criptografia de modo CBC + HMAC cabeçalho de contexto de autenticação baseia-se da mesma maneira,
independentemente de se as implementações de algoritmos são fornecidas pelo Windows CNG ou por tipos
SymmetricAlgorithm e KeyedHashAlgorithm gerenciados. Isso permite que os aplicativos executados em diferentes sistemas
operacionais confiável produzem o mesmo cabeçalho de contexto, embora as implementações de algoritmos diferem entre
sistemas operacionais. (Na prática, o KeyedHashAlgorithm não precisa ser um HMAC adequado. Ele pode ser qualquer tipo
de algoritmo de hash com chave.)
Exemplo: 3DES -192-CBC + HMACSHA1

Primeiro, permitem (K_E | | K_H) = SP800_108_CTR (prf = HMACSHA512, chave = "", rótulo = "", contexto = ""),
onde | K_E | = 192 bits e | K_H | = 160 bits por algoritmos especificados. Isso leva a K_E = A219. E2BB e K_H =
DC4A. B464 no exemplo a seguir:
A2 19 60 2F 83 A9 13 EA B0 61 3A 39 B8 A6 7E 22
61 D9 F8 6C 10 51 E2 BB DC 4A 00 D7 03 A2 48 3E
D1 F7 5A 34 EB 28 3E D7 D4 67 B4 64
Em seguida, calcular Enc_CBC (K_E, IV, "") para 3DES -192-CBC fornecido IV = 0 * e K_E como acima.
resultado: = ABB100F81E53E10E
Em seguida, o MAC de computação (K_H, "") para HMACSHA1 determinado K_H como acima.
result := 76EB189B35CF03461DDF877CD9F4B1B4D63A7555
Isso gera o cabeçalho de contexto completo que é uma impressão digital do autenticado par de algoritmo do
encryption (criptografia 3DES -192-CBC + HMACSHA1 validação), mostrado abaixo:
00 00 00 00 00 18 00 00 00 08 00 00 00 14 00 00
00 14 AB B1 00 F8 1E 53 E1 0E 76 EB 18 9B 35 CF
03 46 1D DF 87 7C D9 F4 B1 B4 D6 3A 75 55
Os componentes são divididos da seguinte maneira:

o marcador (00 00)
o comprimento da chave HMAC (00 00 00 14)
o tamanho do resumo HMAC (00 00 00 14)
a codificação de bloco saída PRP (B1 AB - E1 0E ) e
a saída PRF HMAC (76 EB - end).
Criptografia de modo Galois/contador + autenticação

O cabeçalho de contexto consiste dos seguintes componentes:
[16 bits] O valor 00 01, que é um marcador que significa "criptografia GCM + autenticação".
[32 bits] O comprimento da chave (em bytes, big-endian) do algoritmo de criptografia simétrica de bloco.
[32 bits] O tamanho nonce (em bytes, big-endian) usado durante as operações de criptografia autenticada.
(Para nosso sistema, isso é fixo em tamanho nonce = 96 bits.)
[32 bits] O tamanho de bloco (em bytes, big-endian) do algoritmo de criptografia simétrica de bloco. (Para
GCM, isso é fixo em tamanho de bloco = 128 bits.)
[32 bits] O autenticação marca tamanho (em bytes, big-endian) produzido pela função criptografia
autenticada. (Para nosso sistema, isso é fixo em tamanho de marca = 128 bits.)
[128 bits] A marca de Enc_GCM (K_E, nonce, ""), que é a saída do algoritmo de criptografia simétrica bloco
recebe uma entrada de cadeia de caracteres vazia e onde nonce é um vetor de zeros de 96 bits.
K_E é obtida usando o mesmo mecanismo como a criptografia CBC + o cenário de autenticação de HMAC. No
entanto, já que não há nenhum K_H em jogo aqui, essencialmente temos | K_H | = 0, e o algoritmo recolhe para o
formulário abaixo.
K_E = SP800_108_CTR (prf = HMACSHA512, chave = "", rótulo = "", contexto = "")
Exemplo: AES -256-GCM
Primeiramente, vamos K_E = SP800_108_CTR (prf = HMACSHA512, chave = "", rótulo = "", contexto = ""), onde |
K_E | = 256 bits.
K_E := 22BC6F1B171C08C4AE2F27444AF8FC8B3087A90006CAEA91FDCFB47C1B8733B8
Em seguida, calcular a marca de autenticação de Enc_GCM (K_E, nonce, "") para AES -256-GCM fornecido nonce =
096 e K_E como acima.
result := E7DCCE66DF855A323A6BB7BD7A59BE45
Isso gera o cabeçalho de contexto completo abaixo:
00 01 00 00 00 20 00 00 00 0C 00 00 00 10 00 00
00 10 E7 DC CE 66 DF 85 5A 32 3A 6B B7 BD 7A 59
BE 45
Os componentes são divididos da seguinte maneira:

o marcador (00 01)
o tamanho de nonce (00 00 00 0 C )
o tamanho de marca de autenticação (00 00 00 10) e
a marca de autenticação da execução de codificação de bloco (controlador de domínio E7 - end).
Gerenciamento de chaves no ASP.NET Core
O sistema de proteção de dados gerencia automaticamente o tempo de vida das chaves mestras usado para
proteger e Desproteger cargas. Cada chave pode existir em um dos quatro estágios:
Criada - a chave existe no anel de chave, mas ainda não foi ativada. A chave não deve ser usada para
novas operações de proteção até que haja tempo suficiente tenha decorrido a chave tem tido a
oportunidade de se propagar para todos os computadores que estão consumindo esse anel de chave.
Ativo - a chave existe no anel de chave e deve ser usado para todas as operações de proteção de novo.
Expirou - a chave executou seu tempo de vida natural e não deve mais ser usada para novas operações de
proteção.
Revogado - a chave for comprometida e não deve ser usada para novas operações de proteção.
Todos criadas, ativas e vencidas chaves podem ser usadas para desproteger cargas de entrada. Chaves
revogadas por padrão não podem ser usadas para desproteger cargas, mas o desenvolvedor de aplicativos pode
substituir esse comportamento se necessário.
WARNING
O desenvolvedor pode ser tentado a excluir uma chave do anel de chave (por exemplo, excluindo o arquivo
correspondente do sistema de arquivos). Nesse ponto, todos os dados protegidos pela chave é indecifráveis
permanentemente e não há nenhuma substituição de emergência como ocorre com chaves revogadas. Excluir uma chave
é verdadeiramente destrutivo comportamento e, consequentemente, o sistema de proteção de dados não expõe nenhuma
API de primeira classe para realizar esta operação.
Seleção de chave padrão

Quando o sistema de proteção de dados lê o anel de chave do repositório de backup, ele tenta localizar uma
chave de "padrão" do anel de chave. A chave padrão é usada para novas operações de proteção.
A heurística geral é que o sistema de proteção de dados escolhe a chave com a data mais recente de ativação
como a chave padrão. (Há um pequeno fator para permitir o relógio do servidor para servidor distorção.) Se a
chave expirou ou foi revogada, e se o aplicativo não tiver desabilitado automática da chave de geração, uma
nova chave será gerada com a ativação imediata pela expiração e sem interrupção de chave política abaixo.
O motivo pelo qual o sistema de proteção de dados gera uma nova chave imediatamente em vez de fazer
fallback para uma chave diferente é que a nova geração de chave deve ser tratada como uma expiração implícita
de todas as chaves que foram ativados antes da nova chave. A ideia geral é que novas chaves podem ter sido
configuradas com algoritmos diferentes ou mecanismos de criptografia em repouso que chaves antigos, e o
sistema deve preferir a configuração atual em vez de fazer fallback.
Há uma exceção. Se o desenvolvedor do aplicativo tiver desabilitada a geração automática de chaves, em
seguida, o sistema de proteção de dados deve escolher algo como a chave padrão. Nesse cenário de fallback, o
sistema escolherá a chave não revogado com a data de ativação mais recente, com preferência para chaves que
tem tido tempo para ser propagada para outros computadores no cluster. O sistema de fallback pode acabar de
escolher uma chave expirada padrão como resultado. O sistema de fallback nunca escolherá uma chave
revogada como a chave padrão e se o anel de chave estiver vazio ou todas as chaves foi revogada, em seguida, o
sistema produzirá um erro na inicialização.
Expiração da chave e sem interrupção
Quando uma chave é criada, ele automaticamente tenha dado uma data de ativação de {agora + 2 dias} e uma
data de expiração de {agora + 90 dias}. O atraso de 2 dias antes da ativação fornece o tempo-chave para se
propagar através do sistema. Ou seja, ele permite que outros aplicativos que aponta para o repositório de
backup observar a chave em seu próximo período de atualização automática, além de aumentar as chances de
que quando a chave de anel ativo faz tornam-se que ele ser propagado para todos os aplicativos que talvez
precise usá-lo.
Se a chave padrão irá expirar dentro de 2 dias e o anel de chave ainda não tiver uma chave que estará ativa após
a expiração da chave padrão, o sistema de proteção de dados persistirá automaticamente uma nova chave para o
anel de chave. Essa nova chave tem uma data de ativação de {data de validade da chave padrão} e uma data de
expiração de {agora + 90 dias}. Isso permite que o sistema automaticamente reverter chaves regularmente sem
interrupção do serviço.
Pode haver circunstâncias em que uma chave será criada com a ativação imediata. Um exemplo seria quando o
aplicativo não foi executada por um tempo e todas as chaves do anel de chave estão expiradas. Quando isso
acontece, a chave é dada uma data de ativação de {agora} sem o atraso de ativação de 2 dias normal.
O tempo de vida de chave padrão é de 90 dias, embora isso seja configurável, como no exemplo a seguir.
// use 14-day lifetime instead of 90-day lifetime
.SetDefaultKeyLifetime(TimeSpan.FromDays(14));
Um administrador também pode alterar o padrão para todo o sistema, embora uma chamada explícita para
SetDefaultKeyLifetime substituirá qualquer política de todo o sistema. O tempo de vida de chave padrão não
pode ser menor do que 7 dias.
Atualização automática de anel de chave

Quando o sistema de proteção de dados é inicializado, ele lê o anel de chave do repositório subjacente e
armazena em cache na memória. Esse cache permite proteger e Desproteger operações continuar sem atingir o
repositório de backup. O sistema verificará o repositório de backup para que as alterações automaticamente
aproximadamente a cada 24 horas ou quando a chave padrão atual expirar, o que vier primeiro.
WARNING
Os desenvolvedores devem muito raramente (se utilizadas) precisará usar as APIs de gerenciamento de chave diretamente.
O sistema de proteção de dados executará gerenciamento automático de chaves, conforme descrito acima.
O sistema de proteção de dados expõe uma interface IKeyManager que pode ser usado para inspecionar e fazer
alterações para o anel de chave. O sistema de injeção de dependência que forneceu a instância do
IDataProtectionProvider também pode fornecer uma instância de IKeyManager para seu consumo. Como
alternativa, você pode extrair os IKeyManager diretamente do IServiceProvider como no exemplo a seguir.
Qualquer operação que modifica o anel de chave (Criando uma nova chave explicitamente ou executar uma
revogação) invalida o cache na memória. A próxima chamada para Protect ou Unprotect fará com que o
sistema de proteção de dados releia o anel de chave e recriar o cache.
O exemplo a seguir demonstra como usar o IKeyManager interface para inspecionar e manipular o anel de
chave, incluindo Revogando existente de chaves e gerar uma nova chave manualmente.
using System;
using System.IO;
using System.IO;
using System.Threading;

{
{
// point at a specific folder and use DPAPI to encrypt keys
// perform a protect operation to force the system to put at least

// one key in the key ring
services.GetDataProtector("Sample.KeyManager.v1").Protect("payload");
Console.WriteLine("Performed a protect operation.");
Thread.Sleep(2000);
// get a reference to the key manager

// list all keys in the key ring

var allKeys = keyManager.GetAllKeys();
Console.WriteLine($"The key ring contains {allKeys.Count} key(s).");
foreach (var key in allKeys)
{
Console.WriteLine($"Key {key.KeyId:B}: Created = {key.CreationDate:u}, IsRevoked =
{key.IsRevoked}");
}
// revoke all keys in the key ring

keyManager.RevokeAllKeys(DateTimeOffset.Now, reason: "Revocation reason here.");
Console.WriteLine("Revoked all existing keys.");
// add a new key to the key ring with immediate activation and a 1-month expiration
keyManager.CreateNewKey(
activationDate: DateTimeOffset.Now,
expirationDate: DateTimeOffset.Now.AddMonths(1));
Console.WriteLine("Added a new key.");
// list all keys in the key ring

allKeys = keyManager.GetAllKeys();
Console.WriteLine($"The key ring contains {allKeys.Count} key(s).");
foreach (var key in allKeys)
{
Console.WriteLine($"Key {key.KeyId:B}: Created = {key.CreationDate:u}, IsRevoked =
{key.IsRevoked}");
}
}
}
/*
* SAMPLE OUTPUT
*
* Performed a protect operation.
* The key ring contains 1 key(s).
* Key {1b948618-be1f-440b-b204-64ff5a152552}: Created = 2015-03-18 22:20:49Z, IsRevoked = False
* Revoked all existing keys.
* Added a new key.
* The key ring contains 2 key(s).
* Key {1b948618-be1f-440b-b204-64ff5a152552}: Created = 2015-03-18 22:20:49Z, IsRevoked = True
* Key {2266fc40-e2fb-48c6-8ce2-5fde6b1493f7}: Created = 2015-03-18 22:20:51Z, IsRevoked = False
*/
Armazenamento de chaves
O sistema de proteção de dados tem uma heurística, no qual ele tenta deduzir um mecanismo de criptografia em
repouso e o local de armazenamento de chave apropriado automaticamente. O mecanismo de persistência de
chave também é configurável pelo desenvolvedor do aplicativo. Os documentos a seguir discutem as
implementações de caixa de entrada desses mecanismos:
Provedores de armazenamento de chaves no
ASP.NET Core
O sistema de proteção de dados emprega um mecanismo de descoberta por padrão para determinar onde as
chaves de criptografia devem ser persistente. O desenvolvedor pode substituir o mecanismo de descoberta
padrão e especificar manualmente o local.
WARNING
Se você especificar um local de persistência de chave explícita, o sistema de proteção de dados cancela o registro a
criptografia de chave padrão no mecanismo de rest, portanto, as chaves não são criptografadas em repouso. É
recomendável que você adicionalmente especificar um mecanismo de criptografia de chave explícita para implantações de
produção.
Sistema de arquivos
Para configurar um repositório chave baseadas no sistema de arquivos, chame o PersistKeysToFileSystem
rotina de configuração, conforme mostrado abaixo. Fornecer um DirectoryInfo apontando para o repositório
em que as chaves devem ser armazenadas:

{
.PersistKeysToFileSystem(new DirectoryInfo(@"c:\temp-keys\"));
}
O DirectoryInfo pode apontar para um diretório no computador local, ou ele pode apontar para uma pasta
em um compartilhamento de rede. Se apontando para um diretório no computador local (e o cenário é que
apenas os aplicativos no computador local exigem acesso para usar esse repositório), considere o uso de
Windows DPAPI (no Windows) para criptografar as chaves em repouso. Caso contrário, considere o uso de um
certificado x. 509 para criptografar as chaves em repouso.
O Azure e Redis
O Microsoft.AspNetCore.DataProtection.AzureStorage e
Microsoft.AspNetCore.DataProtection.StackExchangeRedis pacotes permitem armazenar chaves de proteção
de dados no armazenamento do Azure ou de um Redis cache. As chaves podem ser compartilhadas entre
várias instâncias de um aplicativo web. Aplicativos podem compartilhar cookies de autenticação ou proteção
CSRF em vários servidores.
O Microsoft.AspNetCore.DataProtection.AzureStorage e Microsoft.AspNetCore.DataProtection.Redis pacotes
permitem armazenar chaves de proteção de dados no armazenamento do Azure ou um cache Redis. As chaves
podem ser compartilhadas entre várias instâncias de um aplicativo web. Aplicativos podem compartilhar
cookies de autenticação ou proteção CSRF em vários servidores.
Para configurar o provedor de armazenamento de BLOBs do Azure, chame um dos
PersistKeysToAzureBlobStorage sobrecargas:
{
.PersistKeysToAzureBlobStorage(new Uri("<blob URI including SAS token>"));
}
Para configurar o Redis, chame um dos PersistKeysToStackExchangeRedis sobrecargas:

{
var redis = ConnectionMultiplexer.Connect("<URI>");
.PersistKeysToStackExchangeRedis(redis, "DataProtection-Keys");
}
Para configurar o Redis, chame um dos PersistKeysToRedis sobrecargas:

{
var redis = ConnectionMultiplexer.Connect("<URI>");
.PersistKeysToRedis(redis, "DataProtection-Keys");
}
Para mais informações, consulte os seguintes tópicos:

ConnectionMultiplexer stackexchange. Redis
Cache Redis do Azure
exemplos de ASPNET/DataProtection
Registro
Só se aplica às implantações do Windows.
Às vezes, o aplicativo pode não ter acesso de gravação para o sistema de arquivos. Considere um cenário em
que um aplicativo é executado como uma conta de serviço virtual (como w3wp.exeda identidade do pool de
aplicativo). Nesses casos, o administrador pode provisionar uma chave do registro que seja acessível pela
identidade da conta de serviço. Chame o PersistKeysToRegistry método de extensão, conforme mostrado
abaixo. Fornecer um RegistryKey apontando para o local onde as chaves de criptografia devem ser
armazenadas:

{
.PersistKeysToRegistry(Registry.CurrentUser.OpenSubKey(@"SOFTWARE\Sample\keys"));
}
IMPORTANT
É recomendável usar Windows DPAPI para criptografar as chaves em repouso.

O Microsoft.AspNetCore.DataProtection.EntityFrameworkCore pacote fornece um mecanismo para armazenar
chaves de proteção de dados para um banco de dados usando o Entity Framework Core. O
Microsoft.AspNetCore.DataProtection.EntityFrameworkCore pacote do NuGet deve ser adicionado ao arquivo de
projeto, ele não é parte do metapacote Microsoft.
Com esse pacote, as chaves podem ser compartilhadas entre várias instâncias de um aplicativo web.
Para configurar o provedor do EF Core, chame o PersistKeysToDbContext<TContext> método:

{
{
});
// using Microsoft.AspNetCore.DataProtection;
.PersistKeysToDbContext<MyKeysContext>();
.AddDefaultUI(UIFramework.Bootstrap4)
}
O parâmetro genérico, TContext , deve herdar de DbContext e IDataProtectionKeyContext:
using Microsoft.AspNetCore.DataProtection.EntityFrameworkCore;
using WebApp1.Data;
namespace WebApp1
{
class MyKeysContext : DbContext, IDataProtectionKeyContext
{
// A recommended constructor overload when using EF Core
// with dependency injection.
public MyKeysContext(DbContextOptions<ApplicationDbContext> options)
: base(options) { }
// This maps to the table that stores keys.

public DbSet<DataProtectionKey> DataProtectionKeys { get; set; }
}
}
Repositório de chave personalizado

Se os mecanismos de caixa de entrada não forem apropriados, o desenvolvedor pode especificar seu próprio
mecanismo de persistência de chave, fornecendo um personalizado IXmlRepository.
Chave de criptografia em repouso no ASP.NET
Core
O sistema de proteção de dados emprega um mecanismo de descoberta por padrão para determinar as
chaves de criptografia como devem ser criptografados em repouso. O desenvolvedor pode substituir o
mecanismo de descoberta e especificar manualmente como chaves devem ser criptografadas em repouso.
WARNING
Se você especificar um explícito local de persistência da chave, o sistema de proteção de dados cancela o registro a
criptografia de chave padrão no mecanismo de rest. Consequentemente, as chaves não são criptografadas em repouso.
É recomendável que você especificar um mecanismo de criptografia de chave explícita para implantações de produção.
As opções de mecanismo de criptografia em repouso são descritas neste tópico.
Azure Key Vault

Para armazenar as chaves na Azure Key Vault, configure o sistema com ProtectKeysWithAzureKeyVault no
Startup classe:

{
.PersistKeysToAzureBlobStorage(new Uri("<blobUriWithSasToken>"))
.ProtectKeysWithAzureKeyVault("<keyIdentifier>", "<clientId>", "<clientSecret>");
}
Para obter mais informações, consulte configurar a proteção de dados do ASP.NET Core:
ProtectKeysWithAzureKeyVault.
Windows DPAPI
Só se aplica às implantações do Windows.
Quando o Windows DPAPI é usado, o material da chave é criptografada com CryptProtectData antes que
estão sendo mantidos no armazenamento. A DPAPI é um mecanismo de criptografia apropriado para os
dados que nunca é lida de fora do computador atual (no entanto é possível fazer essas chaves até do Active
Directory; Consulte DPAPI e perfis móveis). Para configurar a criptografia de chave em repouso DPAPI,
chame um dos ProtectKeysWithDpapi métodos de extensão:

{
// Only the local user account can decrypt the keys
}
Se ProtectKeysWithDpapi é chamado sem parâmetros, somente a conta de usuário atual do Windows poderá
decifrar o anel de chave persistente. Opcionalmente, você pode especificar que qualquer conta de usuário no
computador (não apenas a conta de usuário atual) poderá decifrar o anel de chave:
{
// All user accounts on the machine can decrypt the keys
.ProtectKeysWithDpapi(protectToLocalMachine: true);
}
Certificado X.509
Se o aplicativo é distribuído entre vários computadores, pode ser conveniente distribuir um certificado x. 509
compartilhado entre as máquinas e configure os aplicativos hospedados para usar o certificado de
criptografia de chaves em repouso:

{
.ProtectKeysWithCertificate("3BCE558E2AD3E0E34A7743EAB5AEA2A9BD2575A0");
}
Devido às limitações do .NET Framework, somente os certificados com chaves privadas de CAPI têm
suporte. Consulte o conteúdo abaixo para obter possíveis soluções para essas limitações.
Windows DPAPI-NG
Esse mecanismo está disponível apenas no Windows 8/Windows Server 2012 ou posterior.
Começando com o Windows 8, o sistema operacional do Windows oferece suporte a DPAPI-NG (também
chamado de CNG DPAPI). Para obter mais informações, consulte sobre o DPAPI CNG.
A entidade de segurança é codificada como uma regra de proteção do descritor. No exemplo a seguir que
chama ProtectKeysWithDpapiNG, somente o usuário de domínio com o SID especificado pode
descriptografar o anel de chave:

{
// Uses the descriptor rule "SID=S-1-5-21-..."
.ProtectKeysWithDpapiNG("SID=S-1-5-21-...",
flags: DpapiNGProtectionDescriptorFlags.None);
}
Também há uma sobrecarga sem parâmetros de ProtectKeysWithDpapiNG . Use esse método de conveniência
para especificar a regra "SID = {CURRENT_ACCOUNT_SID }", onde CURRENT_ACCOUNT_SID é o SID da
conta de usuário atual do Windows:

{
// Use the descriptor rule "SID={current account SID}"
.ProtectKeysWithDpapiNG();
}
Nesse cenário, o controlador de domínio do AD é responsável por distribuir as chaves de criptografia usadas
pelas operações NG DPAPI. O usuário de destino poderá decifrar a carga criptografada de qualquer
computador ingressado no domínio (desde que o processo é executado sob sua identidade).
Criptografia baseada em certificado com o Windows DPAPI-NG
Se o aplicativo está em execução no Windows 8.1 / Windows Server 2012 R2 ou posterior, você pode usar o
Windows DPAPI-NG para executar a criptografia baseada em certificado. Use a cadeia de caracteres do
descritor de regra "certificado = HashId:THUMBPRINT", onde impressão digital é a impressão digital
codificação hexadecimal SHA1 do certificado:

{
.ProtectKeysWithDpapiNG("CERTIFICATE=HashId:3BCE558E2...B5AEA2A9BD2575A0",
flags: DpapiNGProtectionDescriptorFlags.None);
}
Qualquer aplicativo apontado para esse repositório deve estar executando no Windows 8.1 / Windows
Server 2012 R2 ou posterior para decifrar as chaves.
Criptografia de chave personalizada

Se os mecanismos de caixa de entrada não forem apropriados, o desenvolvedor pode especificar seu próprio
mecanismo de criptografia de chave, fornecendo um personalizado IXmlEncryptor.
Imutabilidade de chave e as configurações de chave
no ASP.NET Core
Depois que um objeto é persistido para o repositório de backup, sua representação para sempre é fixo. Novos
dados podem ser adicionados ao repositório de backup, mas os dados existentes nunca podem ser modificados. A
principal finalidade desse comportamento é evitar dados corrompidos.
Uma consequência deste comportamento é que, quando uma chave é gravada para o repositório de backup, é
imutável. As datas de criação, ativação e expiração nunca podem ser alteradas, embora ele pode ser revogada
usando IKeyManager . Além disso, suas informações de algorítmicos subjacentes, material de chave mestre e a
criptografia em Propriedades do rest também são imutáveis.
Se o desenvolvedor altera qualquer configuração que afeta a persistência de chave, essas alterações não entrarão
em vigor até a próxima vez que uma chave é gerada, por meio de uma chamada explícita para
IKeyManager.CreateNewKey ou por meio do sistema proteção de dados próprio chave automática geração
comportamento. As configurações que afetam a persistência de chave são da seguinte maneira:
O tempo de vida de chave padrão
A criptografia de chave no mecanismo de rest
As informações de algorítmicos contidas na chave do
Se você precisar dessas configurações arranque anteriores à próxima chave automática sem interrupção de tempo,
considere fazer uma chamada explícita para IKeyManager.CreateNewKey para forçar a criação de uma nova chave.
Lembre-se de fornecer uma data de ativação explícita ({agora + 2 dias} é uma boa regra prática para dar tempo
para a alteração seja propagada) e a data de expiração na chamada.
TIP
Tocar o repositório de todos os aplicativos devem especificar as mesmas configurações com o IDataProtectionBuilder
métodos de extensão. Caso contrário, as propriedades da chave persistente será dependentes do aplicativo específico que
invocou as rotinas de geração de chave.
Formato de armazenamento de chaves no ASP.NET
Core
Objetos são armazenados em repouso na representação XML. O diretório padrão para o armazenamento de
chaves é % LOCALAPPDATA%\ASP.NET\DataProtection-Keys.
O <key > elemento

Chaves existem como objetos de nível superior no repositório de chave. Por convenção, as chaves têm o nome do
arquivo chave-{guid}. XML, onde {guid} é a id da chave. Cada arquivo contém uma única chave. O formato do
arquivo é da seguinte maneira.

<key id="80732141-ec8f-4b80-af9c-c4d2d1ff8901" version="1">
<creationDate>2015-03-19T23:32:02.3949887Z</creationDate>
<activationDate>2015-03-19T23:32:02.3839429Z</activationDate>
<expirationDate>2015-06-17T23:32:02.3839429Z</expirationDate>
<descriptor deserializerType="{deserializerType}">
<descriptor>
<encryption algorithm="AES_256_CBC" />
<validation algorithm="HMACSHA256" />
<enc:encryptedSecret decryptorType="{decryptorType}" xmlns:enc="...">
<encryptedKey>

<value>AQAAANCM...8/zeP8lcwAg==</value>
</encryptedKey>
</enc:encryptedSecret>
</descriptor>
</descriptor>
</key>
O <key > elemento contém os seguintes atributos e elementos filho:

A id da chave. Esse valor é tratado como autoritativo; o nome do arquivo é simplesmente uma sutileza por
humanos.
A versão do <key > elemento, no momento é fixado em 1.
Datas de criação, ativação e expiração da chave.
Um <descritor > elemento, que contém informações sobre a implementação de criptografia autenticada
contida dentro dessa chave.
No exemplo acima, id da chave é {80732141-ec8f-4b80-af9c-c4d2d1ff8901}, ele foi criado e ativado no dia 19 de
março de 2015, e ele tem um tempo de vida de 90 dias. (Ocasionalmente, a data de ativação pode ser um pouco
antes da data de criação, como neste exemplo. Isso ocorre devido a um nit em como as APIs funcionam e é
inofensivas na prática.)
O <descritor > elemento

Externo <descritor > elemento contém um deserializerType de atributo, que é o nome qualificado pelo assembly
de um tipo que implementa IAuthenticatedEncryptorDescriptorDeserializer. Esse tipo é responsável por ler interno
<descritor > elemento e para analisar as informações contidas neles.
O formato específico do <descritor > elemento depende da implementação do Criptografador autenticado
encapsulada pela chave e cada tipo de desserializador espera um formato ligeiramente diferente para isso. Em
geral, no entanto, esse elemento conterá informações algorítmicos (nomes, tipos, OIDs, ou semelhante) e o
material de chave secreta. No exemplo acima, o descritor especifica que essa chave encapsula a criptografia AES -
256-CBC + HMACSHA256 validação.
O <encryptedSecret > elemento

Uma <encryptedSecret> elemento que contém o formulário criptografado do material de chave secreto pode
estar presente se criptografia de segredos em repouso está ativada. O atributo decryptorType é o nome
qualificado pelo assembly de um tipo que implementa IXmlDecryptor. Esse tipo é responsável por ler interna
<encryptedKey> elemento e descriptografá-los para recuperar o texto sem formatação original.
Assim como acontece com <descritor >, o formato específico do elemento depende do mecanismo de criptografia
em repouso em uso. No exemplo acima, a chave mestra é criptografada usando a DPAPI do Windows por
comentário.
O <revogação > elemento

Revogações existem como objetos de nível superior no repositório de chave. Por convenção revogações têm o
nome do arquivo revogação-{timestamp}. XML (para revogar todas as chaves antes de uma data específica) ou
revogação-{guid}. XML (para a revogação de uma chave específica). Cada arquivo contém um único <revogação
> elemento.
Para revogações de chaves individuais, o conteúdo do arquivo será conforme mostrado abaixo.

<revocation version="1">
<revocationDate>2015-03-20T22:45:30.2616742Z</revocationDate>
<key id="eb4fc299-8808-409d-8a34-23fc83d026c9" />
<reason>human-readable reason</reason>
</revocation>
Nesse caso, apenas a chave especificada é revogada. Se a id da chave é "*", no entanto, como mostra o exemplo
abaixo, cuja data de criação está antes da data de revogação especificado de todas as chaves são revogadas.

<revocation version="1">
<revocationDate>2015-03-20T15:45:45.7366491-07:00</revocationDate>

<key id="*" />
<reason>human-readable reason</reason>
</revocation>
O <motivo > elemento nunca é lido pelo sistema. Ele é simplesmente um local conveniente para armazenar um
motivo legível por humanos para revogação.
Provedores de proteção de dados efêmero no núcleo
do ASP.NET
Há cenários em que um aplicativo precisa de um folheto de propaganda IDataProtectionProvider . Por exemplo, o

desenvolvedor pode apenas suas experiências em um aplicativo de console único, ou o aplicativo em si é
transitório (é inserido no script ou uma unidade de projeto de teste). Para dar suporte a esses cenários de
Microsoft.AspNetCore.DataProtection pacote inclui um tipo EphemeralDataProtectionProvider . Esse tipo fornece
uma implementação básica de IDataProtectionProvider cujo repositório de chave é mantido somente na memória
e não é gravado em qualquer armazenamento de backup.
Cada instância de EphemeralDataProtectionProvider usa sua própria chave mestra exclusiva. Portanto, se um
IDataProtector com raiz em um EphemeralDataProtectionProvider gera uma carga protegida, essa carga só pode
ser desprotegida por um equivalente IDataProtector (forem os mesmos finalidade cadeia) vinculados ao mesmo
EphemeralDataProtectionProvider instância.
O exemplo a seguir demonstra a instanciação de um EphemeralDataProtectionProvider e usá-lo para proteger e

Desproteger dados.
using System;

{
{
const string purpose = "Ephemeral.App.v1";
// create an ephemeral provider and demonstrate that it can round-trip a payload

var provider = new EphemeralDataProtectionProvider();
var protector = provider.CreateProtector(purpose);

string protectedPayload = protector.Protect(input);

string unprotectedPayload = protector.Unprotect(protectedPayload);
// if I create a new ephemeral provider, it won't be able to unprotect existing

// payloads, even if I specify the same purpose
provider = new EphemeralDataProtectionProvider();
protector = provider.CreateProtector(purpose);
unprotectedPayload = protector.Unprotect(protectedPayload); // THROWS
}
}
/*
* SAMPLE OUTPUT
*
* Enter input: Hello!
* Protect returned: CfDJ8AAAAAAAAAAAAAAAAAAAAA...uGoxWLjGKtm1SkNACQ
* Unprotect returned: Hello!
* << throws CryptographicException >>
*/
Compatibilidade no ASP.NET Core
Substituição do ASP.NET <machineKey> no ASP.NET Core

Substitua o machineKey ASP.NET no núcleo do
ASP.NET
A implementação de <machineKey> elemento no ASP.NET é substituível. Isso permite que a maioria das
chamadas para rotinas criptográficas ASP.NET para ser roteada por meio de um mecanismo de proteção de
dados de substituição, incluindo o novo sistema de proteção de dados.
NOTE
O novo sistema de proteção de dados só pode ser instalado em um aplicativo ASP.NET existente direcionado ao .NET 4.5.1
ou posterior. Instalação irá falhar se o aplicativo tem como destino .NET 4.5 ou inferior.
Para instalar o novo sistema de proteção de dados em um projeto de 4.5.1+ ASP.NET existente, instale o pacote
Microsoft.AspNetCore.DataProtection.SystemWeb. Isso criará uma instância de sistema de proteção de dados
usando o configuração padrão configurações.
Quando você instala o pacote, ele insere uma linha em Web. config que diz ao ASP.NET para usá-la para mais
operações criptográficas, incluindo autenticação de formulários, o estado de exibição e chamadas para Protect. A
linha é inserida lê da seguinte maneira.
<machineKey compatibilityMode="Framework45" dataProtectorType="..." />
TIP
Você pode determinar se o novo sistema de proteção de dados está ativo inspecionando campos como __VIEWSTATE , que
deve começar com "CfDJ8" como no exemplo a seguir. "CfDJ8" é a representação de base64 do cabeçalho magic "09 F0 C9
F0" que identifica um conteúdo protegido pelo sistema de proteção de dados.
<input type="hidden" name="__VIEWSTATE" id="__VIEWSTATE" value="CfDJ8AWPr2EQPTBGs3L2GCZOpk..." />
Configuração de pacote
O sistema de proteção de dados é instanciado com uma configuração de zero a instalação padrão. No entanto,
uma vez que por padrão as chaves são mantidas para o sistema de arquivos local, isso não funcionará para
aplicativos que são implantados em um farm. Para resolver esse problema, você pode fornecer uma configuração
por meio da criação de um tipo que herda DataProtectionStartup e substitui o método ConfigureServices.
Abaixo está um exemplo de um tipo de inicialização de proteção de dados personalizados que configurado onde
as chaves são persistentes e como eles são criptografados em repouso. Ela também substitui a política de
isolamento de aplicativo padrão, fornecendo seu próprio nome de aplicativo.
using System;
using System.IO;
using Microsoft.AspNetCore.DataProtection.SystemWeb;
namespace DataProtectionDemo
{
public class MyDataProtectionStartup : DataProtectionStartup
{
public override void ConfigureServices(IServiceCollection services)
{
.SetApplicationName("my-app")
.PersistKeysToFileSystem(new DirectoryInfo(@"\\server\share\myapp-keys\"))
}
}
}
TIP
Você também pode usar <machineKey applicationName="my-app" ... /> no lugar de uma chamada explícita para
SetApplicationName. Esse é um mecanismo de conveniência para evitar forçar o desenvolvedor para criar um tipo derivado
de DataProtectionStartup se todos os quisessem configurar foi definindo o nome do aplicativo.
Para habilitar essa configuração personalizada, volte para a Web. config e procure o <appSettings> elemento que
instala o pacote adicionado ao arquivo de configuração. Ele se parecerá com a seguinte marcação:
<appSettings>

<add key="aspnet:dataProtectionStartupType" value="" />
</appSettings>
Preencha o valor em branco com o nome qualificado do assembly do tipo derivado DataProtectionStartup que
você acabou de criar. Se o nome do aplicativo é DataProtectionDemo, isso seria semelhante a abaixo.
<add key="aspnet:dataProtectionStartupType"
value="DataProtectionDemo.MyDataProtectionStartup, DataProtectionDemo" />
O sistema de proteção de dados recém-configurada agora está pronto para uso dentro do aplicativo.
Armazenamento seguro dos segredos do
aplicativo em desenvolvimento no ASP.NET
Core
Por Rick Anderson, Daniel Roth, e Scott Addie

Este documento explica as técnicas para armazenar e recuperar dados confidenciais durante o
desenvolvimento de um aplicativo ASP.NET Core. Nunca armazene senhas ou outros dados
confidenciais no código-fonte. Segredos de produção não devem ser usados para desenvolvimento ou
teste. Você pode armazenar e proteger os segredos de teste e produção do Azure com o provedor de
configuração do Azure Key Vault.
Variáveis de ambiente são usadas para evitar o armazenamento de segredos do aplicativo no código ou
em arquivos de configuração local. Variáveis de ambiente substituem os valores de configuração para
todas as fontes de configuração especificado anteriormente.
Configure a leitura dos valores de variáveis de ambiente chamando AddEnvironmentVariables no
Startup construtor:

{
.AddJsonFile("appsettings.json",
optional: false,
.AddEnvironmentVariables();
{
builder.AddUserSecrets<Startup>();
}
}
Considere um aplicativo da web ASP.NET Core no qual contas de usuário individuais segurança
está habilitada. Uma cadeia de caracteres de conexão de banco de dados padrão está incluída no
projeto do appSettings. JSON arquivo com a chave DefaultConnection . É a cadeia de caracteres de
conexão padrão para o LocalDB, que é executado no modo de usuário e não requer uma senha.
Durante a implantação de aplicativo, o DefaultConnection valor de chave pode ser substituído com o
valor da variável de ambiente. A variável de ambiente pode armazenar a cadeia de caracteres de
conexão completa com credenciais confidenciais.
WARNING
Variáveis de ambiente geralmente são armazenadas em texto não criptografado e sem formatação. Se o
computador ou processo for comprometido, as variáveis de ambiente podem ser acessadas por pessoas não
confiáveis. Medidas adicionais para evitar a divulgação de segredos do usuário podem ser necessárias.
Secret Manager
A ferramenta Secret Manager armazena dados confidenciais durante o desenvolvimento de um projeto
ASP.NET Core. Nesse contexto, uma parte dos dados confidenciais é um segredo do aplicativo.
Segredos do aplicativo são armazenados em um local separado da árvore do projeto. Os segredos do
aplicativo são compartilhados em vários projetos ou associados a um projeto específico. Os segredos
do aplicativo não são verificados no controle de origem.
WARNING
A ferramenta Secret Manager não criptografa os segredos armazenados e não deve ser tratada como um
repositório confiável. Ele é apenas a fins de desenvolvimento. As chaves e valores são armazenados em um
arquivo de configuração JSON no diretório de perfil do usuário.
Como funciona a ferramenta Secret Manager

A ferramenta Secret Manager abstrai os detalhes de implementação, como onde e como os valores são
armazenados. Você pode usar a ferramenta sem conhecer esses detalhes de implementação. Os valores
são armazenados em um arquivo de configuração do JSON em uma pasta de perfil do usuário do
sistema protegido no computador local:
Windows
macOS
Linux
Caminho do sistema de arquivos:
%APPDATA%\Microsoft\UserSecrets\<user_secrets_id>\secrets.json
Na anterior caminhos de arquivo, substitua <user_secrets_id> com o UserSecretsId valor especificado

na . csproj arquivo.
Não escreva código que depende do local ou o formato dos dados salvos com a ferramenta Secret
Manager. Esses detalhes de implementação pode ser alterado. Por exemplo, os valores secretos não
são criptografados, mas pode ser no futuro.
Instalar a ferramenta Secret Manager

A ferramenta Secret Manager é fornecido com a CLI do .NET Core no SDK do .NET Core 2.1.300 ou
posterior. Para versões do SDK do .NET Core anteriores 2.1.300, a instalação da ferramenta é
necessária.
TIP
Executar dotnet --version em um shell de comando para ver o número de versão do SDK do .NET Core
instalado.
Um aviso será exibido se a ferramenta inclui o SDK do .NET Core que está sendo usada:
The tool 'Microsoft.Extensions.SecretManager.Tools' is now included in the .NET Core SDK.

Information on resolving this warning is available at (https://aka.ms/dotnetclitools-in-box).
Instalar o secretmanager pacote do NuGet em seu projeto ASP.NET Core. Por exemplo:
<PropertyGroup>
<UserSecretsId>1242d6d6-9df3-4031-b031-d9b27d13c25a</UserSecretsId>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore"
Version="1.1.6" />
<PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets"
Version="1.1.2" />
<PackageReference Include="System.Data.SqlClient"
Version="4.5.0" />
</ItemGroup>
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools"
Version="1.0.1" />
</ItemGroup>
</Project>
Execute o seguinte comando em um shell de comando para validar a instalação da ferramenta:
dotnet user-secrets -h
A ferramenta Secret Manager exibe um exemplo de uso e opções de ajuda de comando:
Usage: dotnet user-secrets [options] [command]
Options:
-?|-h|--help Show help information
--version Show version information
-v|--verbose Show verbose output
-p|--project <PROJECT> Path to project. Defaults to searching the current directory.
-c|--configuration <CONFIGURATION> The project configuration to use. Defaults to 'Debug'.
--id The user secret ID to use.
Commands:
clear Deletes all the application secrets
list Lists all the application secrets
remove Removes the specified user secret
set Sets the user secret to the specified value
Use "dotnet user-secrets [command] --help" for more information about a command.
NOTE
Você deve estar no mesmo diretório que o . csproj arquivo para executar as ferramentas definidas na . csproj do
arquivo DotNetCliToolReference elementos.
Defina um segredo
A ferramenta Secret Manager opera em definições de configuração de específicos do projeto
armazenadas no perfil do usuário. Para usar os segredos do usuário, defina uma UserSecretsId
elemento dentro de uma PropertyGroup da . csproj arquivo. O valor de UserSecretsId é arbitrária, mas
é exclusiva para o projeto. Os desenvolvedores geralmente geram um GUID para o UserSecretsId .
<PropertyGroup>
<UserSecretsId>79a3edd0-2092-40a2-a04d-dcb46d5ca9ed</UserSecretsId>
</PropertyGroup>
<PropertyGroup>
<UserSecretsId>1242d6d6-9df3-4031-b031-d9b27d13c25a</UserSecretsId>
</PropertyGroup>
TIP
No Visual Studio, clique com botão direito no projeto no Gerenciador de soluções e selecione gerenciar
segredos do usuário no menu de contexto. Esse gesto adiciona uma UserSecretsId elemento, preenchido
com um GUID para o . csproj arquivo. O Visual Studio abre uma Secrets arquivo no editor de texto. Substitua o
conteúdo do Secrets com os pares chave-valor a ser armazenado. Por exemplo:
{
"Movies": {
"ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-
1;Trusted_Connection=True;MultipleActiveResultSets=true",
"ServiceApiKey": "12345"
}
}
A estrutura JSON é mesclada após modificações via dotnet user-secrets remove ou

dotnet user-secrets set . Por exemplo, executando
dotnet user-secrets remove "Movies:ConnectionString" recolhe o Movies literal de objeto. O arquivo
modificado é semelhante a:
{
"Movies:ServiceApiKey": "12345"
}
Defina um segredo do aplicativo consiste em uma chave e seu valor. O segredo está associado com o
projeto UserSecretsId valor. Por exemplo, execute o seguinte comando do diretório no qual o . csproj
arquivo existe:
dotnet user-secrets set "Movies:ServiceApiKey" "12345"
No exemplo anterior, os dois-pontos indica que Movies é um objeto literal com um ServiceApiKey
propriedade.
A ferramenta Secret Manager pode ser usada de outros diretórios muito. Use o --project opção de
fornecer o caminho do sistema de arquivos no qual o . csproj arquivo existe. Por exemplo:
dotnet user-secrets set "Movies:ServiceApiKey" "12345" --project "C:\apps\WebApp1\src\WebApp1"

Defina vários segredos
Um lote de segredos pode ser definido ao canalizar o JSON para o set comando. No exemplo a
seguir, o Input conteúdo do arquivo será canalizado para o set comando.
Windows
macOS
Linux
Abra um shell de comando e execute o seguinte comando:
type .\input.json | dotnet user-secrets set
Acesse um segredo
O API de configuração do ASP.NET Core fornece acesso aos segredos Secret Manager. Se seu projeto
direcionado ao .NET Framework, instale o Microsoft.Extensions.Configuration.UserSecrets pacote do
NuGet.
No ASP.NET Core 2.0 ou posterior, a fonte de configuração de segredos do usuário é adicionada
automaticamente no modo de desenvolvimento quando o projeto chama CreateDefaultBuilder para
inicializar uma nova instância do host com os padrões pré-configurados. CreateDefaultBuilder
chamadas AddUserSecrets quando o EnvironmentName está desenvolvimento:

Quando CreateDefaultBuilder não é chamado durante a construção de host, adicione a fonte de

configuração de segredos do usuário com uma chamada para AddUserSecrets no Startup construtor:

{
optional: false,
{
}
}
O API de configuração do ASP.NET Core fornece acesso aos segredos Secret Manager. Instalar o
Microsoft.Extensions.Configuration.UserSecrets pacote do NuGet.
Adicionar a fonte de configuração de segredos do usuário com uma chamada para AddUserSecrets no
Startup construtor:
{
optional: false,
{
}
}
Segredos do usuário podem ser recuperados por meio de Configuration API:

{
private string _moviesApiKey = null;

{
}

{
_moviesApiKey = Configuration["Movies:ServiceApiKey"];
}

{
var result = string.IsNullOrEmpty(_moviesApiKey) ? "Null" : "Not Null";
{
await context.Response.WriteAsync($"Secret is {result}");
});
}
}
{
private string _moviesApiKey = null;

{
optional: false,
{
}
}
public IConfigurationRoot Configuration { get; }

{
_moviesApiKey = Configuration["Movies:ServiceApiKey"];
}

{
var result = string.IsNullOrEmpty(_moviesApiKey) ? "Null" : "Not Null";
{
await context.Response.WriteAsync($"Secret is {result}");
});
}
}
Segredos do mapa para um POCO

Mapeando um literal de objeto inteiro para um POCO (uma classe .NET simple com propriedades) é
útil para agregar as propriedades relacionadas.
Suponha que o aplicativo Secrets arquivo contém os dois segredos do seguintes:
{
"Movies": {
"ServiceApiKey": "12345",
}
}
Para mapear os segredos anteriores para um POCO, use o Configuration da API de associação do
grafo de objeto recurso. O código a seguir associa a um personalizado MovieSettings POCO e acessa
o ServiceApiKey valor da propriedade:
var moviesConfig = Configuration.GetSection("Movies")

.Get<MovieSettings>();
_moviesApiKey = moviesConfig.ServiceApiKey;
var moviesConfig = new MovieSettings();
Configuration.GetSection("Movies").Bind(moviesConfig);
_moviesApiKey = moviesConfig.ServiceApiKey;
O Movies:ConnectionString e Movies:ServiceApiKey segredos são mapeados para as respectivas

propriedades no MovieSettings :
public class MovieSettings

{
public string ConnectionString { get; set; }
public string ServiceApiKey { get; set; }

}
Cadeia de caracteres de substituição com segredos

Armazenar senhas em texto sem formatação é inseguro. Por exemplo, uma cadeia de caracteres de
conexão de banco de dados armazenados em appSettings. JSON pode incluir uma senha para o
usuário especificado:
{
"Movies": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;User
Id=johndoe;Password=pass123;MultipleActiveResultSets=true"
}
}
Uma abordagem mais segura é armazenar a senha como um segredo. Por exemplo:
dotnet user-secrets set "DbPassword" "pass123"
Remover o Password par chave-valor da cadeia de conexão na appSettings. JSON. Por exemplo:
{
"Movies": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;User
Id=johndoe;MultipleActiveResultSets=true"
}
}
Valor do segredo pode ser definida em um SqlConnectionStringBuilder do objeto senha propriedade

para concluir a cadeia de caracteres de conexão:
{
private string _connection = null;

{
}

{
var builder = new SqlConnectionStringBuilder(
Configuration.GetConnectionString("Movies"));
builder.Password = Configuration["DbPassword"];
_connection = builder.ConnectionString;
}

{
{
await context.Response.WriteAsync($"DB Connection: {_connection}");
});
}
}
{
private string _connection = null;

{
optional: false,
{
}
}

{
var builder = new SqlConnectionStringBuilder(
Configuration.GetConnectionString("Movies"));
builder.Password = Configuration["DbPassword"];
_connection = builder.ConnectionString;
}

{
{
await context.Response.WriteAsync($"DB Connection: {_connection}");
});
}
}
Lista os segredos
{
"Movies": {
}
}
Execute o seguinte comando no diretório no qual o . csproj arquivo existe:
dotnet user-secrets list
A saída a seguir é exibida:

Movies:ConnectionString = Server=(localdb)\mssqllocaldb;Database=Movie-
1;Trusted_Connection=True;MultipleActiveResultSets=true
Movies:ServiceApiKey = 12345
No exemplo anterior, dois-pontos em nomes de chave denota a hierarquia de objetos dentro Secrets.
Remover um segredo único

{
"Movies": {
}
}
dotnet user-secrets remove "Movies:ConnectionString"
O aplicativo Secrets arquivo foi modificado para remover o par chave-valor associado a
MoviesConnectionString chave:
{
"Movies": {
"ServiceApiKey": "12345"
}
}
Executando dotnet user-secrets list exibe a seguinte mensagem:
Movies:ServiceApiKey = 12345
Remover todos os segredos

{
"Movies": {
}
}
dotnet user-secrets clear
Todos os segredos do usuário para o aplicativo tem sido excluídos do Secrets arquivo:
{}
Executando dotnet user-secrets list exibe a seguinte mensagem:
No secrets configured for this application.
Recursos adicionais
Provedor de configuração de Cofre de chaves do Azure no ASP.NET Core
Impor HTTPS no ASP.NET Core
Por Rick Anderson

Este documento demonstra como:
Exigir HTTPS para todas as solicitações.
Redirecione todas as solicitações HTTP para HTTPS.
Nenhuma API pode impedir que um cliente envie dados confidenciais na primeira solicitação.
WARNING
Fazer não usar RequireHttpsAttribute em APIs da Web que recebe informações confidenciais. RequireHttpsAttribute
usa códigos de status HTTP para redirecionar navegadores de HTTP para HTTPS. Os clientes da API não podem
compreender ou obedecem redirecionamentos de HTTP para HTTPS. Esses clientes podem enviar informações por meio
de HTTP. As APIs da Web deverá:
Não realizar a escuta em HTTP.
Feche a conexão com o código de status 400 (solicitação incorreta) e não atender à solicitação.
Exigir HTTPS
É recomendável que produção do ASP.NET Core chamada de aplicativos web:
Middleware de redirecionamento de HTTPS (UseHttpsRedirection) para redirecionar solicitações HTTP
para HTTPS.
Middleware HSTS (UseHsts) para enviar cabeçalhos de protocolo de segurança de transporte estrito
(HSTS ) HTTP aos clientes.
NOTE
Aplicativos implantados em uma configuração de proxy reverso permitem que o proxy lidar com a segurança de conexão
(HTTPS). Se o proxy também manipula o redirecionamento de HTTPS, não é necessário usar o Middleware de
redirecionamento de HTTPS. Se o servidor proxy também manipula a HSTS cabeçalhos de gravação (por exemplo, dar
suporte a HSTS nativos no IIS 10.0 (1709) ou posterior), Middleware HSTS não é necessário para o aplicativo. Para obter
mais informações, consulte Opt-out de HTTPS/HSTS na criação do projeto.
UseHttpsRedirection
O código a seguir chama UseHttpsRedirection no Startup classe:
{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
O código realçado anterior:

Usa o padrão HttpsRedirectionOptions.RedirectStatusCode (Status307TemporaryRedirect).
Usa o padrão HttpsRedirectionOptions.HttpsPort (null), a menos que substituído pela
ASPNETCORE_HTTPS_PORT variável de ambiente ou IServerAddressesFeature.
É recomendável usar redirecionamentos temporários em vez de redirecionamentos permanentes. Cache de

link pode causar um comportamento instável em ambientes de desenvolvimento. Se você preferir enviar um
código de status de redirecionamento permanente quando o aplicativo estiver em um ambiente de não
desenvolvimento, consulte o configurar redirecionamentos permanentes em produção seção. É recomendável
usar HSTS para sinalizar para os clientes que proteger somente o recurso deve ser redirecionada para o
aplicativo (somente em produção).
Configuração de porta
Uma porta deve estar disponível para o middleware redirecionar uma solicitação não segura para HTTPS. Se
nenhuma porta estiver disponível:
Redirecionamento de HTTPS não ocorre.
O middleware registra o aviso "Falha ao determinar a porta https para redirecionamento."
Especifique a porta HTTPS usando qualquer uma das seguintes abordagens:
Definir HttpsRedirectionOptions.HttpsPort.
Defina as ASPNETCORE_HTTPS_PORT variável de ambiente ou definição de configuração do Host da Web
https_port:
Chave: https_port
Tipo: string
Padrão: um valor padrão não está definido.
Variável de ambiente: <PREFIX_>HTTPS_PORT (é o prefixo ASPNETCORE_ ao usar os Host Web.)
Ao configurar uma IWebHostBuilder em Program :
{
{
}

.UseSetting("https_port", "8080")
}
Indicar uma porta com o esquema segura usando o ASPNETCORE_URLS variável de ambiente. A variável
de ambiente configura o servidor. O middleware indiretamente descobre a porta HTTPS por meio de
IServerAddressesFeature. (Faz não funcionam em implantações de proxy reverso.)
No desenvolvimento, defina uma URL HTTPS launchsettings. JSON. Habilite HTTPS quando o IIS
Express é usado.
Configurar um ponto de extremidade de URL HTTPS para uma implantação de borda para o público do
Kestrel ou HTTP. sys. Somente uma porta HTTPS é usado pelo aplicativo. O middleware descobre a
porta por meio de IServerAddressesFeature.
NOTE
Quando um aplicativo é executado atrás de um proxy reverso (por exemplo, IIS, IIS Express), IServerAddressesFeature
não está disponível. A porta deve ser configurada manualmente. Quando a porta não for definida, as solicitações não
são redirecionadas.
Quando o Kestrel ou HTTP. sys é usado como um servidor de borda para o público, o Kestrel ou HTTP. sys
deve ser configurado para escutar em ambos:
A porta segura em que o cliente é redirecionado (normalmente, 443 em 5001 no desenvolvimento e
produção).
A porta não segura (normalmente, 80 na produção) e 5000 no desenvolvimento.
A porta não segura deve estar acessível pelo cliente para que o aplicativo para receber uma solicitação não
segura e redirecionar o cliente para a porta segura.
Para obter mais informações, consulte configuração de ponto de extremidade do Kestrel ou Implementação do
servidor Web HTTP.sys no ASP.NET Core.
Cenários de implantação
Qualquer firewall entre o cliente e o servidor também deve ter as portas de comunicação aberto para o
tráfego.
Se as solicitações são encaminhadas em uma configuração de proxy reverso, use Middleware de cabeçalhos
encaminhados antes de chamar Middleware de redirecionamento de HTTPS. Encaminhado atualizações de
Middleware de cabeçalhos a Request.Scheme , usando o X-Forwarded-Proto cabeçalho. O middleware permite
redirecionar URIs e outras políticas de segurança para funcionar corretamente. Quando o Middleware de
cabeçalhos encaminhados não for usado, o aplicativo de back-end não pode receber o esquema correto e
acabar em um loop de redirecionamento. Uma mensagem de erro comuns do usuário final é que muitos
redirecionamentos ocorreram.
Ao implantar o serviço de aplicativo do Azure, siga as orientações Tutorial: associar um certificado SSL
personalizado existente a aplicativos Web do Azure.
Opções
O seguinte realçado código chama AddHttpsRedirection para configurar as opções de middleware:

{
services.AddMvc();
services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = StatusCodes.Status307TemporaryRedirect;
options.HttpsPort = 5001;
});
}
Chamando AddHttpsRedirection só é necessário alterar os valores de HttpsPort ou RedirectStatusCode .

O código realçado anterior:
Conjuntos HttpsRedirectionOptions.RedirectStatusCode para Status307TemporaryRedirect, que é o valor
padrão. Use os campos do StatusCodes classe atribuições para RedirectStatusCode .
Define a porta HTTPS para 5001. O valor padrão é 443.
Configurar redirecionamentos permanentes em produção
O middleware usará como padrão para envio de uma Status307TemporaryRedirect com todos os
redirecionamentos. Se você preferir enviar um código de status de redirecionamento permanente quando o
aplicativo estiver em um ambiente de não desenvolvimento, encapsule a configuração de opções de
middleware em uma verificação condicional para um ambiente de desenvolvimento não.
Ao configurar uma IWebHostBuilder na Startup.cs:

{
// IHostingEnvironment (stored in _env) is injected into the Startup class.
if (!_env.IsDevelopment())
{
{
options.RedirectStatusCode = StatusCodes.Status308PermanentRedirect;
});
}
}
Abordagem alternativa de Middleware de redirecionamento de

HTTPS
Uma alternativa ao uso de Middleware de redirecionamento de HTTPS ( UseHttpsRedirection ) é usar o
Middleware de reconfiguração de URL ( AddRedirectToHttps ). AddRedirectToHttps também pode definir o
código de status e a porta quando o redirecionamento é executado. Para obter mais informações, consulte
Middleware de reconfiguração de URL.
Ao redirecionar para HTTPS sem a necessidade de regras de redirecionamento adicional, é recomendável usar
o Middleware de redirecionamento de HTTPS ( UseHttpsRedirection ) descrito neste tópico.
O RequireHttpsAttribute é usada para exigir HTTPS. [RequireHttpsAttribute] pode decorar controladores ou
métodos, ou podem ser aplicadas globalmente. Para aplicar o atributo globalmente, adicione o seguinte código
ao ConfigureServices em Startup :
// Requires using Microsoft.AspNetCore.Mvc;

{
services.Configure<MvcOptions>(options =>
{
options.Filters.Add(new RequireHttpsAttribute());
});
O código realçado anterior requer que todas as solicitações usem HTTPS ; portanto, as solicitações HTTP são
ignoradas. O seguinte código realçado redireciona todas as solicitações HTTP para HTTPS:
// Requires using Microsoft.AspNetCore.Rewrite;

{
var options = new RewriteOptions()

.AddRedirectToHttps();
app.UseRewriter(options);
Para obter mais informações, consulte Middleware de reconfiguração de URL. O middleware também permite
que o aplicativo para definir o código de status ou o código de status e a porta quando o redirecionamento é
executado.
Exigir HTTPS globalmente ( options.Filters.Add(new RequireHttpsAttribute()); ) é uma prática recomendada
de segurança. Aplicando o [RequireHttps] atributo a todas as páginas do Razor/controladores não é
considerado tão seguro quanto exigir HTTPS globalmente. Você não pode garantir o [RequireHttps] atributo
é aplicado quando novos controladores e páginas Razor são adicionadas.
Protocolo de segurança de transporte estrito HTTP (HSTS)

Por OWASP, segurança de transporte estrito HTTP (HSTS ) é um aprimoramento de segurança opcional é
especificado por um aplicativo web com o uso de um cabeçalho de resposta. Quando um navegador que
ofereça suporte a HSTS recebe esse cabeçalho:
O navegador armazena a configuração para o domínio que evita o envio de qualquer comunicação por
HTTP. O navegador força todas as comunicações via HTTPS.
O navegador impede que o usuário usando os certificados não confiáveis ou é inválidos. O navegador
desativa prompts que permitem que um usuário para confiar temporariamente esses certificados.
Como HSTS é imposta pelo cliente, ele tem algumas limitações:
O cliente deve oferecer suporte a HSTS.
HSTS requer pelo menos uma solicitação HTTPS bem-sucedida para estabelecer a política HSTS.
O aplicativo deve verificar todas as solicitações HTTP e redirecionar ou rejeitar a solicitação HTTP.
ASP.NET Core 2.1 ou posterior implementa HSTS com o UseHsts método de extensão. O código a seguir
chama UseHsts quando o aplicativo não está no modo de desenvolvimento:
{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
UseHsts não é recomendado em desenvolvimento porque as configurações de HSTS são altamente

armazenáveis em cache por navegadores. Por padrão, UseHsts exclui o endereço de loopback local.
Para ambientes de produção implementando HTTPS pela primeira vez, definir inicial HstsOptions.MaxAge
com um valor pequeno usando um do TimeSpan métodos. Defina o valor de horas como não mais do que um
único dia caso você precise reverter a infraestrutura HTTPS para HTTP. Depois que você estiver confiante em
sustentabilidade da configuração do HTTPS, aumente o valor de idade máxima HSTS; um valor comumente
usado é um ano.
O código a seguir:

{
services.AddMvc();
services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
{
options.RedirectStatusCode = StatusCodes.Status307TemporaryRedirect;
});
}
Define o parâmetro de pré-carregamento do cabeçalho de segurança de transporte estrito. Pré-

carregamento não faz parte dos especificação RFC HSTS, mas é compatível com navegadores da web para
pré-carregar sites HSTS na nova instalação. Veja https://hstspreload.org/ para obter mais informações.
Habilita includeSubDomain, que se aplica a política HSTS para hospedar subdomínios.
Define explicitamente o parâmetro de idade máxima do cabeçalho de segurança de transporte estrito para
60 dias. Se não for definido, o padrão é 30 dias. Consulte a max-age diretiva para obter mais informações.
Adiciona example.com à lista de hosts a serem excluídos.
UseHsts Exclui os seguintes hosts de loopback:

localhost : O endereço de loopback do IPv4.
127.0.0.1 : O endereço de loopback do IPv4.
[::1] : O endereço de loopback do IPv6.
Recusa de HTTPS/HSTS na criação do projeto

Em alguns cenários de serviço de back-end em que a segurança de conexão é manipulada na borda da rede
para o público, configurando a segurança de conexão em cada nó não é necessária. Aplicativos gerados a partir
de modelos no Visual Studio ou na Web a dotnet new comando enable redirecionamento a HTTPS e HSTS.
Para implantações que não exigem esses cenários, você pode recusar HTTPS/HSTS quando o aplicativo é
criado a partir do modelo.
A recusa de HTTPS/HSTS:
Visual Studio
CLI do .NET Core
Desmarque a configurar para HTTPS caixa de seleção.
Confiar no certificado de desenvolvimento do ASP.NET Core HTTPS

no Windows e macOS
SDK do .NET core inclui um certificado de desenvolvimento de HTTPS. O certificado é instalado como parte
da experiência de primeira execução. Por exemplo, dotnet --info produz uma saída semelhante à seguinte:
ASP.NET Core
------------
Successfully installed the ASP.NET Core HTTPS Development Certificate.
To trust the certificate run 'dotnet dev-certs https --trust' (Windows and macOS only).
For establishing trust on other platforms refer to the platform specific documentation.
For more information on configuring HTTPS see https://go.microsoft.com/fwlink/?linkid=848054.
Instalar o SDK do .NET Core instala o certificado de desenvolvimento do ASP.NET Core HTTPS para o
repositório de certificados de usuário local. O certificado foi instalado, mas não for confiável. Confiar em
certificado execute a etapa única para executar o dotnet dev-certs ferramenta:
dotnet dev-certs https --trust
O comando a seguir fornece ajuda sobre o dev-certs ferramenta:
dotnet dev-certs https --help
Como configurar um certificado de desenvolvedor para o Docker

Ver esse problema de GitHub.
Informações adicionais
Configure o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga
Hospedar o ASP.NET Core no Linux com o Apache: configuração de SSL
Hospedar o ASP.NET Core no Linux com Nginx: configuração de SSL
Como configurar o SSL no IIS
Suporte a navegador HSTS OWASP
Suporte da UE Data Protection GDPR
(regulamento geral) no ASP.NET Core
Por Rick Anderson

O ASP.NET Core fornece modelos e APIs para ajudar a atender a alguns dos regulamentação de proteção de
dados geral (GDPR ) da UE requisitos:
Os modelos de projeto incluem pontos de extensão e a marcação de stub que você pode substituir por sua
privacidade e a política de uso de cookies.
Um recurso de consentimento do cookie permite que você pedir consentimento (e acompanhar uma) de
seus usuários para armazenar informações pessoais. Se um usuário não tiver consentido para coleta de
dados e o aplicativo tem CheckConsentNeeded definido como true , não-essenciais cookies não são
enviados para o navegador.
Os cookies podem ser marcados como essenciais. Cookies essenciais são enviados ao navegador, mesmo
quando o usuário não tiver consentido e acompanhamento está desabilitado.
Cookies de sessão e TempData não são funcionais quando o rastreamento está desabilitado.
O gerenciar identidades página fornece um link para baixar e excluir dados de usuário.
O aplicativo de exemplo permite que você teste a maioria dos pontos de extensão de GDPR e APIs
adicionadas para os modelos do ASP.NET Core 2.1. Consulte a Leiame arquivo para obter instruções de teste.
Suporte GDPR do ASP.NET Core no código de modelo gerado

Páginas do Razor e MVC projetos criados com os modelos de projeto incluem o seguinte suporte GDPR:
CookiePolicyOptions e UseCookiePolicy são definidos no Startup .
O _CookieConsentPartial.cshtml exibição parcial.
O Pages/Privacy.cshtml página ou Views/Home/Privacy.cshtml exibição fornece uma página para a política
de privacidade do seu site de detalhe. O _CookieConsentPartial.cshtml arquivo gera um link para a página
de privacidade.
Para os aplicativos criados com as contas de usuário individual, a página Gerenciar fornece links para
baixar e excluir dados pessoais do usuário.
CookiePolicyOptions e UseCookiePolicy
CookiePolicyOptions são inicializadas em Startup.ConfigureServices :
{
{
}
// This method gets called by the runtime. Use this method to add services
// to the container.
{
{
// This lambda determines whether user consent for non-essential cookies
// is needed for a given request.
});
// If the app uses session state, call AddSession.

// services.AddSession();
}
// This method gets called by the runtime. Use this method to configure the
// HTTP request pipeline.
{
{
}
else
{
app.UseHsts();
}
// app.UseSession();
app.UseMvc();
}
}
UseCookiePolicy é chamado no Startup.Configure :

{
{
}
// This method gets called by the runtime. Use this method to add services
// to the container.
{
{
// This lambda determines whether user consent for non-essential cookies
// is needed for a given request.
});
// If the app uses session state, call AddSession.

// services.AddSession();
}
// This method gets called by the runtime. Use this method to configure the
// HTTP request pipeline.
{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
}
Modo de exibição parcial _CookieConsentPartial.cshtml

O _CookieConsentPartial.cshtml exibição parcial:
@using Microsoft.AspNetCore.Http.Features
@{
var consentFeature = Context.Features.Get<ITrackingConsentFeature>();
var showBanner = !consentFeature?.CanTrack ?? false;
var cookieString = consentFeature?.CreateConsentCookie();
}
@if (showBanner)
{
<nav id="cookieConsent" class="navbar navbar-default navbar-fixed-top" role="alert">
target="#cookieConsent .navbar-collapse">
<span class="sr-only">Toggle cookie consent banner</span>
</button>
<span class="navbar-brand"><span class="glyphicon glyphicon-info-sign" aria-hidden="true">
</span></span>
</div>
<div class="collapse navbar-collapse">
<p class="navbar-text">
Use this space to summarize your privacy and cookie use policy.
</p>
<div class="navbar-right">
<a asp-page="/Privacy" class="btn btn-info navbar-btn">Learn More</a>
<button type="button" class="btn btn-default navbar-btn" data-cookie-
string="@cookieString">Accept</button>
</div>
</div>
</div>
</nav>
<script>
(function () {
document.querySelector("#cookieConsent button[data-cookie-string]").addEventListener("click",
function (el) {
document.cookie = el.target.dataset.cookieString;
document.querySelector("#cookieConsent").classList.add("hidden");
}, false);
})();
</script>
}
Essa parcial:
Obtém o estado do controle para o usuário. Se o aplicativo estiver configurado para exigir o
consentimento, o usuário deve consentir antes de cookies podem ser controlados. Se for necessário o
consentimento, o painel de consentimento do cookie é fixa na parte superior da barra de navegação criada
pelo layout. cshtml arquivo.
Fornece um HTML <p> elemento para resumir a sua privacidade e cookie usar a política.
Fornece um link para a página de privacidade ou exibição onde você pode detalhar a política de
privacidade do seu site.
Cookies essenciais
Se o consentimento não foi fornecido, somente os cookies marcados essenciais são enviados para o
navegador. O código a seguir faz com que um cookie essenciais:
public IActionResult OnPostCreateEssentialAsync()
{
HttpContext.Response.Cookies.Append(Constants.EssentialSec,
DateTime.Now.Second.ToString(),
new CookieOptions() { IsEssential = true });
ResponseCookies = Response.Headers[HeaderNames.SetCookie].ToString();
}
Cookies de estado de sessão e o provedor de TempData não são

essenciais
O provedor de Tempdata cookie não essencial. Se o controle estiver desabilitado, o provedor de Tempdata
não é funcional. Para habilitar o provedor de Tempdata quando o rastreamento está desabilitado, marcar o
cookie de TempData como essencial para Startup.ConfigureServices :
// The Tempdata provider cookie is not essential. Make it essential

// so Tempdata is functional when tracking is disabled.
services.Configure<CookieTempDataProviderOptions>(options => {
options.Cookie.IsEssential = true;
});
Estado de sessão cookies não são essenciais. Estado de sessão não está funcionando quando o rastreamento
está desabilitado.
Dados pessoais
Aplicativos ASP.NET Core criados com contas de usuário individuais incluem código para baixar e excluir
dados pessoais.
Selecione o nome de usuário e, em seguida, selecione dados pessoais:
Notas:
Para gerar a Account/Manage de código, consulte Scaffold identidade.
Excluir e baixar apenas o impacto de dados de identidade padrão. Aplicativos que criam os dados de
usuário personalizada devem ser estendidos para exclusão/baixar os dados de usuário personalizada. Para
obter mais informações, consulte adicionar, baixar e excluir dados de usuário personalizada para
identidade.
Salva os tokens para o usuário que são armazenados na tabela de banco de dados de identidade
AspNetUserTokens são excluídos quando o usuário é excluído por meio do comportamento de exclusão em
cascata devido ao chave estrangeira.
Criptografia em repouso
Alguns bancos de dados e mecanismos de armazenamento permitem a criptografia em repouso. Criptografia
em repouso:
Criptografa dados armazenados automaticamente.
Criptografa sem configuração, programação ou outro trabalho para o software que acessa os dados.
É a opção mais segura e fácil.
Permite que o banco de dados gerenciar chaves e criptografia.
Por exemplo:
Microsoft SQL e SQL Azure fornecem Transparent Data Encryption (TDE ).
SQL Azure criptografa o banco de dados por padrão
Blobs, arquivos, tabela e o armazenamento de filas do Azure são criptografados por padrão.
Para bancos de dados que não fornecem internos de criptografia em repouso, você poderá usar a criptografia
de disco para fornecer a mesma proteção. Por exemplo:
BitLocker para Windows Server
Linux:
eCryptfs
EncFS.
Recursos adicionais
Microsoft.com/GDPR
Provedor de configuração de Cofre de chaves do
Azure no ASP.NET Core
Por Luke Latham e Andrew Stanton-Nurse

Este documento explica como usar o Microsoft Azure Key Vault provedor de configuração para carregar
valores de configuração de aplicativo de segredos do Cofre de chaves do Azure. O Azure Key Vault é um
serviço baseado em nuvem que ajuda você a proteger chaves criptográficas e segredos usados por aplicativos
e serviços. Cenários comuns incluem controlar o acesso aos dados de configuração confidenciais e atender o
requisito para FIPS 140-2 nível 2 validados módulos de segurança de Hardware (HSM ) ao armazenar dados
de configuração. Esse recurso está disponível para aplicativos que usam o ASP.NET Core 1.1 ou superior.
Pacote
Para usar o provedor, adicione uma referência para o Microsoft.Extensions.Configuration.AzureKeyVault
pacote.
Configuração de aplicativo
Você pode explorar o provedor com o aplicativos de exemplo. Depois de estabelecer um cofre de chaves e crie
os segredos no cofre, os aplicativos de exemplo carregar os valores secretos em suas configurações e exibem-
las em páginas da Web com segurança.
O provedor é adicionado à configuração do aplicativo com o AddAzureKeyVault extensão. Em aplicativos de
exemplo, a extensão usa três valores de configuração carregados a partir de appSettings. JSON arquivo.
CONFIGURAÇÃO DE APLICATIVO DESCRIÇÃO EXEMPLO
Vault Nome do Cofre de chaves do Azure contosovault
ClientId Id do aplicativo do Azure Active 627e911e-43cc-61d4-992e-

Directory 12db9c81b413
ClientSecret Chave do aplicativo do Azure Active g58K3dtg59o1Pa+e59v2Tx829w6VxT

Directory B2yv9sv/101di=

{
var builtConfig = config.Build();
config.AddAzureKeyVault(
$"https://{builtConfig["Vault"]}.vault.azure.net/",
builtConfig["ClientId"],
builtConfig["ClientSecret"]);
})
Crie os segredos do Cofre de chaves e carregar valores de
configuração (exemplo basic)
1. Criar um cofre de chaves e configurar o Azure Active Directory (Azure AD ) para o aplicativo seguindo
as orientações em Introdução ao Azure Key Vault.
Adicionar segredos no cofre de chaves usando o módulo do PowerShell do AzureRM chave cofre
disponível na Galeria do PowerShell, o API REST do Azure Key Vault, ou o Portal do azure. Segredos
são criados como um Manual ou certificado segredos. Certificado segredos são certificados para uso
por aplicativos e serviços, mas não são suportados pelo provedor de configuração. Você deve usar o
Manual opção para criar os segredos de par nome-valor para uso com o provedor de configuração.
Segredos simples são criados como pares nome-valor. Nomes de segredos de Cofre de
chaves do Azure são limitados a caracteres alfanuméricos e traços.
Usam valores hierárquicos (seções de configuração) -- (dois traços) como um separador no
exemplo. Dois-pontos, que normalmente são usadas para delimitar uma seção de uma
subchave no configuração do ASP.NET Core, não são permitidos em nomes de segredos.
Portanto, os dois traços são usados e trocados para dois-pontos quando os segredos são
carregados para a configuração do aplicativo.
Criar duas Manual segredos com os seguintes pares de nome-valor. O segredo do primeiro é
um nome simples e um valor, e o segredo do segundo cria um valor do segredo com uma
seção e a subchave no nome do segredo:
SecretName : secret_value_1
Section--SecretName : secret_value_2
Registre o aplicativo de exemplo com o Azure Active Directory.
Autorize o aplicativo para acessar o Cofre de chaves. Quando você usa o
Set-AzureRmKeyVaultAccessPolicy cmdlet do PowerShell para autorizar o aplicativo para acessar o
Cofre de chaves, forneça List e Get acesso aos segredos com -PermissionsToSecrets list,get .
2. Atualizar o aplicativo appSettings. JSON arquivo com os valores de Vault , ClientId , e ClientSecret .
3. Executar o aplicativo de exemplo que obtém seus valores de configuração de IConfigurationRoot com o
mesmo nome que o nome do segredo.
Valores não são hierárquicos: O valor para SecretName é obtido com config["SecretName"] .
Valores hierárquicos (seções): Use : notação (dois-pontos) ou o GetSection método de extensão.
Use qualquer uma dessas abordagens para obter o valor de configuração:
config["Section:SecretName"]
config.GetSection("Section")["SecretName"]
Quando você executa o aplicativo, uma página da Web mostra os valores secretos carregados:
Associar uma matriz a uma classe

O provedor é capaz de ler os valores de configuração em uma matriz para a associação para uma matriz
POCO.
Durante a leitura de uma fonte de configuração que permite que as chaves conter dois-pontos ( : )
separadores, um segmento de chave numérico é usado para distinguir as chaves que compõem uma matriz (
:0: , :1: ,... :{n}: ). Para obter mais informações, consulte configuração: associar uma matriz a uma classe.
Chaves do Azure Key Vault não podem usar dois-pontos como um separador. A abordagem descrita neste
tópico usa double traços ( -- ) como separador de valores hierárquicos (seções). As chaves de matriz são
armazenadas no Azure Key Vault com double traços e segmentos de chave numéricos ( --0-- , --1-- ,...
--{n}-- ).
Examine o seguinte Serilog fornecida por um arquivo JSON de configuração do provedor de log. Há dois
objetos literais definidos na WriteTo matriz que refletem os dois Serilog coletores, que descrevem os destinos
para saída de log:
"Serilog": {
"WriteTo": [
{
"Name": "AzureTableStorage",
"Args": {
"storageTableName": "logs",
"connectionString": "DefaultEnd...ountKey=Eby8...GMGw=="
}
},
{
"Name": "AzureDocumentDB",
"Args": {
"endpointUrl": "https://contoso.documents.azure.com:443",
"authorizationKey": "Eby8...GMGw=="
}
}
]
}
A configuração mostrada no arquivo JSON anterior é armazenada no Azure Key Vault usando o traço duplo (
-- ) segmentos notação e numérico:
CHAVE VALOR
Serilog--WriteTo--0--Name AzureTableStorage
Serilog--WriteTo--0--Args--storageTableName logs
Serilog--WriteTo--0--Args--connectionString DefaultEnd...ountKey=Eby8...GMGw==
Serilog--WriteTo--1--Name AzureDocumentDB
Serilog--WriteTo--1--Args--endpointUrl https://contoso.documents.azure.com:443
Serilog--WriteTo--1--Args--authorizationKey Eby8...GMGw==
Segredos do Cofre de chaves prefixados de criar e carregar valores

de configuração (chave-nome-prefixo-sample)
AddAzureKeyVault também fornece uma sobrecarga que aceita uma implementação de
IKeyVaultSecretManager , que permite que você controle como os principais segredos do cofre são convertidas
em chaves de configuração. Por exemplo, você pode implementar a interface para carregar os valores do
segredo com base em um valor de prefixo que você fornece na inicialização do aplicativo. Isso permite que
você, por exemplo, para carregar segredos de acordo com a versão do aplicativo.
WARNING
Não usar prefixos de segredos do Cofre de chaves para colocar segredos para vários aplicativos no mesmo Cofre de
chaves ou para colocar segredos ambientais (por exemplo, development versus produção segredos) no mesmo cofre. É
recomendável que diferentes aplicativos e ambientes de desenvolvimento/produção usam cofres de chaves separados
para isolar os ambientes de aplicativo para o nível mais alto de segurança.
Usando o segundo aplicativo de exemplo, criar um segredo no cofre de chaves para 5000-AppSecret (períodos
não são permitidos em nomes de segredos do Cofre de chaves) que representa um segredo do aplicativo para
versão Version=5.0.0.0 do seu aplicativo. Para obter outra versão, 5.1.0.0, você cria um segredo para
5100-AppSecret . Cada versão do aplicativo carrega seu próprio valor do segredo em sua configuração como
AppSecret , remoção desativar a versão ele carrega o segredo. A implementação da amostra é mostrada
abaixo:

{
// The appVersion obtains the app version (5.0.0.0), which
// is set in the project file and obtained from the entry
// assembly. The versionPrefix holds the version without
// dot notation for the PrefixKeyVaultSecretManager.
var appVersion = Assembly.GetEntryAssembly().GetName().Version.ToString();
var versionPrefix = appVersion.Replace(".", string.Empty);
$"https://{builtConfig["Vault"]}.vault.azure.net/",
builtConfig["ClientSecret"],
new PrefixKeyVaultSecretManager(versionPrefix));
})
public class PrefixKeyVaultSecretManager : IKeyVaultSecretManager
{
private readonly string _prefix;
public PrefixKeyVaultSecretManager(string prefix)

{
_prefix = $"{prefix}-";
}
public bool Load(SecretItem secret)

{
// Load a vault secret when its secret name starts with the
// prefix. Other secrets won't be loaded.
return secret.Identifier.Name.StartsWith(_prefix);
}
public string GetKey(SecretBundle secret)

{
// Remove the prefix from the secret name and replace two
// dashes in any name with the KeyDelimiter, which is the
// delimiter used in configuration (usually a colon). Azure
// Key Vault doesn't allow a colon in secret names.
return secret.SecretIdentifier.Name
.Substring(_prefix.Length)
.Replace("--", ConfigurationPath.KeyDelimiter);
}
}
O Load método é chamado por um algoritmo de provedor que itera os segredos do cofre para encontrar
aqueles que têm o prefixo de versão. Quando um prefixo de versão é encontrado com Load , o algoritmo usa o
GetKey método para retornar o nome da configuração do nome do segredo. Ele ignora o prefixo de versão do
nome do segredo e retorna o restante do nome do segredo para carregamento na configuração do aplicativo
pares nome-valor.
Ao implementar essa abordagem:
1. Os segredos do Cofre de chaves são carregados.
2. O segredo de cadeia de caracteres para 5000-AppSecret é correspondido.
3. A versão 5000 (com o traço) é removidos de deixar o nome da chave AppSecret carregar com o valor do
segredo para a configuração do aplicativo.
NOTE
Você também pode fornecer seus próprios KeyVaultClient implementação para AddAzureKeyVault . Fornecer um
cliente personalizado permite que você compartilhe uma única instância do cliente entre o provedor de configuração e
outras partes do seu aplicativo.
1. Criar um cofre de chaves e configurar o Azure Active Directory (Azure AD ) para o aplicativo seguindo
as orientações em Introdução ao Azure Key Vault.
Adicionar segredos no cofre de chaves usando o módulo do PowerShell do AzureRM chave cofre
disponível na Galeria do PowerShell, o API REST do Azure Key Vault, ou o Portal do azure. Segredos
são criados como um Manual ou certificado segredos. Certificado segredos são certificados para uso
por aplicativos e serviços, mas não são suportados pelo provedor de configuração. Você deve usar o
Manual opção para criar os segredos de par nome-valor para uso com o provedor de configuração.
Usam valores hierárquicos (seções de configuração) -- (dois traços) como um separador.
Criar duas Manual segredos com os seguintes pares de nome-valor:
5000-AppSecret : 5.0.0.0_secret_value
5100-AppSecret : 5.1.0.0_secret_value
Registre o aplicativo de exemplo com o Azure Active Directory.
Autorize o aplicativo para acessar o Cofre de chaves. Quando você usa o
Set-AzureRmKeyVaultAccessPolicy cmdlet do PowerShell para autorizar o aplicativo para acessar o
Cofre de chaves, forneça List e Get acesso aos segredos com -PermissionsToSecrets list,get .
2. Atualizar o aplicativo appSettings. JSON arquivo com os valores de Vault , ClientId , e ClientSecret .
3. Executar o aplicativo de exemplo que obtém seus valores de configuração de IConfigurationRoot com o
mesmo nome que o nome do segredo prefixado. Neste exemplo, o prefixo é a versão do aplicativo, que
você forneceu para o PrefixKeyVaultSecretManager quando você adicionou o provedor de configuração
do Azure Key Vault. O valor para AppSecret é obtido com config["AppSecret"] . A página da Web
gerada pelo aplicativo mostra o valor carregado:
4. Alterar a versão do assembly no arquivo de projeto de aplicativo 5.0.0.0 para 5.1.0.0 e execute o
aplicativo novamente. Esse tempo, o valor do segredo retornado é 5.1.0.0_secret_value . A página da
Web gerada pelo aplicativo mostra o valor carregado:
Controlar o acesso para o segredo do cliente

Use o ferramenta Secret Manager para manter o ClientSecret fora de sua árvore de origem do projeto. Com
o Secret Manager, você associar a um projeto específico de segredos do aplicativo e compartilhá-los em vários
projetos.
Ao desenvolver um aplicativo do .NET Framework em um ambiente que dá suporte a certificados, você pode
autenticar para o Azure Key Vault com um certificado X.509. Chave privada do certificado X.509 é gerenciado
pelo sistema operacional. Para obter mais informações, consulte autenticar com um certificado em vez de um
segredo do cliente. Use o AddAzureKeyVault sobrecarga que aceita um X509Certificate2 ( _env no exemplo a
seguir:
var store = new X509Store(StoreLocation.CurrentUser);

store.Open(OpenFlags.ReadOnly);
var cert = store.Certificates
.Find(X509FindType.FindByThumbprint,
config["CertificateThumbprint"], false);
builtConfig["Vault"],
cert.OfType<X509Certificate2>().Single(),
new EnvironmentSecretManager(context.HostingEnvironment.ApplicationName));
store.Close();
Recarregue os segredos
Segredos são armazenados em cache até IConfigurationRoot.Reload() é chamado. Expirado, desabilitado, e
atualizados segredos no cofre de chaves não serão respeitados pelo aplicativo até Reload é executado.
Configuration.Reload();
Segredos desabilitados e expirados

Segredos desabilitados e expirados lançar um KeyVaultClientException . Para impedir que seu aplicativo
acione, substitua o seu aplicativo ou atualizar o segredo desabilitado/expirado.
Quando o aplicativo falha ao carregar a configuração usando o provedor, uma mensagem de erro é gravada
para o infra-estrutura de log do ASP.NET Core. As seguintes condições impedirá que a configuração de
carregamento:
O aplicativo não está configurado corretamente no Azure Active Directory.
O Cofre de chaves não existe no Azure Key Vault.
O aplicativo não está autorizado a acessar o Cofre de chaves.
A política de acesso não inclui Get e List permissões.
No cofre de chaves, os dados de configuração (par nome-valor) estão nomeados incorretamente, ausente,
desabilitado ou expirado.
O aplicativo tem o nome do cofre da chave incorreta ( Vault ), Id do aplicativo do Azure AD ( ClientId ), ou
a chave do Azure AD ( ClientSecret ).
A chave do AD do Azure ( ClientSecret ) expirou.
A chave de configuração (nome) está incorreta no aplicativo para o valor que você está tentando carregar.
Recursos adicionais
Microsoft Azure: Cofre de chaves
Microsoft Azure: Documentação de Cofre de chaves
Como gerar e transferir protegida por HSM chaves para o Azure Key Vault
Classe KeyVaultClient
Ataques de evitar entre solicitação intersite
forjada (CSRF/XSRF) no ASP.NET Core
Por Steve Smith, Fiyaz Hasan, e Rick Anderson

Falsificação de solicitação intersite forjada (também conhecida como XSRF ou CSRF, pronunciado
surfe consulte) é um ataque contra aplicativos hospedados na web, no qual um aplicativo web mal-
intencionado pode influenciar a interação entre um navegador cliente e um aplicativo web que
confia que Navegador. Esses ataques são possíveis, pois navegadores da web enviam alguns tipos
de tokens de autenticação automaticamente com cada solicitação de um site. Essa forma de
exploração é também conhecido como um ataque de um clique ou sequestro de sessão porque o
ataque aproveita o usuário do autenticado anteriormente sessão.
Um exemplo de um ataque CSRF:
1. Um usuário entra em www.good-banking-site.com usando a autenticação de formulários. O
servidor autentica o usuário e emite uma resposta que inclui um cookie de autenticação. O
site é vulnerável a ataques porque ele confia qualquer solicitação recebida com um cookie de
autenticação válido.
2. O usuário visitar um site mal-intencionado, www.bad-crook-site.com .
O site mal-intencionado, www.bad-crook-site.com , contém um formulário HTML semelhante
ao seguinte:
<h1>Congratulations! You're a Winner!</h1>

<form action="http://good-banking-site.com/api/account" method="post">
<input type="hidden" name="Transaction" value="withdraw">
<input type="hidden" name="Amount" value="1000000">
<input type="submit" value="Click to collect your prize!">
</form>
Observe que o formulário action postagens para o site vulnerável, não para o site mal-
intencionado. Essa é a parte de "site cruzado" de CSRF.
3. O usuário seleciona o botão Enviar. O navegador faz a solicitação e inclui automaticamente o
cookie de autenticação para o domínio solicitado, www.good-banking-site.com .
4. A solicitação é executada www.good-banking-site.com server com o contexto de autenticação
do usuário e pode executar qualquer ação que um usuário autenticado tem permissão para
executar.
Além do cenário em que o usuário seleciona o botão para enviar o formulário, o site mal-
intencionado pode:
Execute um script que envia automaticamente o formulário.
Envie o envio do formulário como uma solicitação AJAX.
Oculte o formulário usando CSS.
Esses cenários alternativos não exigem qualquer entrada do usuário que não sejam inicialmente
visitar o site mal-intencionado ou ação.
Usar o HTTPS não impede que um ataque CSRF. O site mal-intencionado pode enviar um
https://www.good-banking-site.com/ solicitar tão fácil quanto ele pode enviar uma solicitação não
segura.
Alguns ataques são direcionados a pontos de extremidade que respondem às solicitações GET,
neste caso, uma marca de imagem pode ser usada para executar a ação. Essa forma de ataque é
comum nos sites de Fórum que permitem imagens, mas bloqueiam o JavaScript. Aplicativos que
alteram o estado em solicitações GET, em que as variáveis ou os recursos são alterados, são
vulneráveis a ataques mal-intencionados. Solicitações GET que alteram o estado são
inseguras. Uma prática recomendada é nunca alterar o estado em uma solicitação GET.
Ataques de CSRF são possíveis em relação a aplicativos web que usam cookies para autenticação
porque:
Os navegadores armazenam os cookies emitidos por um aplicativo web.
Armazenado cookies incluem cookies de sessão para usuários autenticados.
Os navegadores enviam a que todos os cookies associados com um domínio para o aplicativo
web cada solicitação, independentemente de como a solicitação para o aplicativo foi gerada
dentro do navegador.
No entanto, os ataques de CSRF não estão limitadas a exploração de cookies. Por exemplo, a
autenticação básica e Digest também são vulneráveis. Depois que um usuário entra com a
autenticação básica ou Digest, o navegador automaticamente envia as credenciais até que a sessão†
termina.
†Nesse contexto, sessão refere-se à sessão do lado do cliente durante o qual o usuário é
autenticado. Ele é não relacionada a sessões do lado do servidor ou Middleware de sessão do
ASP.NET Core.
Os usuários podem se proteger contra vulnerabilidades CSRF tomando precauções:
Entrar em aplicativos web quando terminar de usá-los.
Limpar os cookies do navegador periodicamente.
No entanto, as vulnerabilidades CSRF são basicamente um problema com o aplicativo web, não
pelo usuário final.
Conceitos básicos de autenticação

Autenticação baseada em cookie é uma forma popular de autenticação. Sistemas de autenticação
baseada em token estão crescendo em termos de popularidade, especialmente para aplicativos de
página única (SPAs).
Autenticação baseada em cookie
Quando um usuário é autenticado usando o nome de usuário e senha, elas emitidas um token, que
contém um tíquete de autenticação que pode ser usado para autenticação e autorização. O token é
armazenado como um cookie que acompanha cada solicitação, o cliente faz. Gerar e validar esse
cookie é realizada pelo Middleware de autenticação de Cookie. O middleware serializa uma
entidade de usuário em um cookie criptografado. Nas próximas solicitações, o middleware valida o
cookie, recria a entidade de segurança e a atribui a entidade de segurança de usuário propriedade
de HttpContext.
Autenticação baseada em token
Quando um usuário é autenticado, elas emitidas um token (não um token antifalsificação). O token
contém informações de usuário na forma de declarações ou um token de referência que aponta o
aplicativo para o estado do usuário mantido no aplicativo. Quando um usuário tenta acessar um
recurso que requer autenticação, o token é enviado para o aplicativo com um cabeçalho de
autorização adicionais na forma de token de portador. Isso torna o aplicativo sem monitoração de
estado. Em cada solicitação subsequente, o token é passado na solicitação para a validação do lado
do servidor. Não é esse token criptografado; ele tem codificado. No servidor, o token é decodificado
para acessar suas informações. Para enviar o token em solicitações subsequentes, armazene o
token no armazenamento local do navegador. Não fique preocupado sobre vulnerabilidade CSRF,
se o token é armazenado no armazenamento local do navegador. CSRF é uma preocupação
quando o token é armazenado em um cookie.
Vários aplicativos hospedados em um domínio
Ambientes de hospedagem compartilhados são vulneráveis a sequestro de sessão, login CSRF e
outros ataques.
Embora example1.contoso.net e example2.contoso.net são hosts diferentes, há uma relação de
confiança implícita entre os hosts sob o *.contoso.net domínio. Essa relação de confiança implícita
permite que os hosts potencialmente não confiáveis afetam uns dos outros cookies (as políticas de
mesma origem que regem as solicitações AJAX não necessariamente se aplicam aos cookies
HTTP ).
Ataques que exploram confiáveis cookies entre aplicativos hospedados no mesmo domínio podem
ser evitadas por meio do compartilhamento não domínios. Quando cada aplicativo é hospedado
em seu próprio domínio, não há nenhuma relação de confiança implícita de cookie para explorar.
Configuração antifalsificação do ASP.NET Core

WARNING
ASP.NET Core implementa usando antifalsificação proteção de dados do ASP.NET Core. A pilha da proteção
de dados deve ser configurada para funcionar em um farm de servidores. Ver Configurando a proteção de
dados para obter mais informações.
No ASP.NET Core 2.0 ou posterior, o FormTagHelper injeta tokens antifalsificação em elementos

de formulário HTML. A marcação a seguir em um arquivo Razor gera automaticamente os tokens
antifalsificação:
...
</form>
Similarily, IHtmlHelper.BeginForm gera tokens antifalsificação por padrão, se o método do

formulário não é GET.
A geração automática de tokens antifalsificação para elementos de formulário HTML acontece
quando o <form> marca contém o method="post" atributo e uma das opções a seguir forem
verdadeira:
O atributo action está vazio ( action="" ).
O atributo de ação não for fornecido ( <form method="post"> ).
Geração automática de tokens antifalsificação para elementos de formulário HTML pode ser
desabilitada:
Desabilitar explicitamente tokens antifalsificação com o asp-antiforgery atributo:
<form method="post" asp-antiforgery="false">
...
</form>
O elemento de formulário é aceito-out dos auxiliares de marca usando o auxiliar de marca !

recusar símbolo:
<!form method="post">
...
</!form>
Remover o FormTagHelper da exibição. O FormTagHelper pode ser removido de uma

exibição, adicionando a seguinte diretiva para o modo de exibição do Razor:
@removeTagHelper Microsoft.AspNetCore.Mvc.TagHelpers.FormTagHelper,
Microsoft.AspNetCore.Mvc.TagHelpers
NOTE
Páginas do Razor são protegidos automaticamente contra XSRF/CSRF. Para obter mais informações,
consulte XSRF/CSRF e páginas Razor.
A abordagem mais comum para proteger contra ataques CSRF é usar o padrão de Token do
sincronizador (STP ). STP é usado quando o usuário solicita uma página com os dados de
formulário:
1. O servidor envia um token associado com a atual identidade do usuário para o cliente.
2. O cliente envia o token para o servidor para verificação.
3. Se o servidor recebe um token que não corresponde à identidade do usuário autenticado, a
solicitação será rejeitada.
O token é exclusivo e imprevisíveis. O token também pode ser usado para garantir que o
sequenciamento adequado de uma série de solicitações (por exemplo, garantindo a sequência de
solicitação de: a página 1 – página 2 – página 3). Todos os formulários em modelos do ASP.NET
Core MVC e páginas do Razor geram tokens contra falsificação. O seguinte par de exemplos do
modo de exibição gera tokens contra falsificação:
<form asp-controller="Manage" asp-action="ChangePassword" method="post">

...
</form>
@using (Html.BeginForm("ChangePassword", "Manage"))

{
...
}
Adicionar explicitamente um token antifalsificação para um <form> elemento sem o uso de

auxiliares de marca com o auxiliar HTML @Html.AntiForgeryToken :
<form action="/" method="post">

@Html.AntiForgeryToken()
</form>
Em cada um dos casos anteriores, o ASP.NET Core adiciona um campo de formulário oculto
semelhante ao seguinte:
<input name="__RequestVerificationToken" type="hidden" value="CfDJ8NrAkS ... s2-m9Yw">
ASP.NET Core inclui três filtros para trabalhar com tokens antifalsificação:
ValidateAntiForgeryToken
AutoValidateAntiforgeryToken
IgnoreAntiforgeryToken
Opções de antifalsificação
Personalize opções antifalsificação em Startup.ConfigureServices :
services.AddAntiforgery(options =>
{
// Set Cookie properties using CookieBuilder properties†.
options.FormFieldName = "AntiforgeryFieldname";
options.HeaderName = "X-CSRF-TOKEN-HEADERNAME";
options.SuppressXFrameOptionsHeader = false;
});
†Definir a antifalsificação Cookie usando as propriedades do objeto de propriedades de

CookieBuilder classe.
OPÇÃO DESCRIÇÃO
Cookie Determina as configurações usadas para criar o

cookie antifalsificação.
FormFieldName O nome do campo de formulário oculto usado pelo

sistema antifalsificação para processar tokens
antifalsificação nos modos de exibição.
HeaderName O nome do cabeçalho usado pelo sistema

antifalsificação. Se null , o sistema considera apenas
os dados de formulário.
SuppressXFrameOptionsHeader Especifica se deve suprimir a geração do

X-Frame-Options cabeçalho. Por padrão, o
cabeçalho é gerado com um valor de "SAMEORIGIN".
services.AddAntiforgery(options =>
{
options.CookieDomain = "contoso.com";
options.CookieName = "X-CSRF-TOKEN-COOKIENAME";
options.CookiePath = "Path";
options.FormFieldName = "AntiforgeryFieldname";
options.HeaderName = "X-CSRF-TOKEN-HEADERNAME";
options.RequireSsl = false;
options.SuppressXFrameOptionsHeader = false;
});
OPÇÃO DESCRIÇÃO
Cookie Determina as configurações usadas para criar o

cookie antifalsificação.
CookieDomain O domínio do cookie. Assume o padrão de null .

Essa propriedade está obsoleta e será removida em
uma versão futura. A alternativa recomendada é
Cookie.Domain.
CookieName O nome do cookie. Se não definido, o sistema gera

um nome exclusivo que começa com o
DefaultCookiePrefix (". AspNetCore.Antiforgery."). Essa
propriedade está obsoleta e será removida em uma
versão futura. A alternativa recomendada é
Cookie.Name.
CookiePath O caminho definido no cookie. Essa propriedade está

obsoleta e será removida em uma versão futura. A
alternativa recomendada é Cookie.Path.
FormFieldName O nome do campo de formulário oculto usado pelo

sistema antifalsificação para processar tokens
antifalsificação nos modos de exibição.
HeaderName O nome do cabeçalho usado pelo sistema

antifalsificação. Se null , o sistema considera apenas
os dados de formulário.
RequireSsl Especifica se o SSL é necessária pelo sistema

antifalsificação. Se true , solicitações não SSL falhar.
Assume o padrão de false . Essa propriedade está
obsoleta e será removida em uma versão futura. A
alternativa recomendada é definir
Cookie.SecurePolicy.
SuppressXFrameOptionsHeader Especifica se deve suprimir a geração do

X-Frame-Options cabeçalho. Por padrão, o
cabeçalho é gerado com um valor de "SAMEORIGIN".
Para obter mais informações, consulte CookieAuthenticationOptions.
Configurar recursos antiforgery com IAntiforgery

IAntiforgery fornece a API para configurar recursos antifalsificação. IAntiforgery podem ser
solicitadas a Configure método da Startup classe. O exemplo a seguir usa o middleware da home
page do aplicativo para gerar um token antifalsificação e enviá-lo na resposta como um cookie
(usando a convenção de nomenclatura Angular da padrão descrita mais adiante neste tópico):
public void Configure(IApplicationBuilder app, IAntiforgery antiforgery)
{
app.Use(next => context =>
{
string path = context.Request.Path.Value;
if (
string.Equals(path, "/", StringComparison.OrdinalIgnoreCase) ||
string.Equals(path, "/index.html", StringComparison.OrdinalIgnoreCase))
{
// The request token can be sent as a JavaScript-readable cookie,
// and Angular uses it by default.
var tokens = antiforgery.GetAndStoreTokens(context);
context.Response.Cookies.Append("XSRF-TOKEN", tokens.RequestToken,
new CookieOptions() { HttpOnly = false });
}
return next(context);
});
}
Exigir validação antifalsificação

ValidateAntiForgeryToken é um filtro de ação que pode ser aplicado a uma ação individual, um
controlador ou globalmente. As solicitações feitas a ações que têm esse filtro aplicado são
bloqueadas, a menos que a solicitação inclui um token antifalsificação válido.
[HttpPost]
public async Task<IActionResult> RemoveLogin(RemoveLoginViewModel account)
{
ManageMessageId? message = ManageMessageId.Error;
var user = await GetCurrentUserAsync();
if (user != null)
{
var result =
await _userManager.RemoveLoginAsync(
user, account.LoginProvider, account.ProviderKey);
{
message = ManageMessageId.RemoveLoginSuccess;
}
}
return RedirectToAction(nameof(ManageLogins), new { Message = message });

}
O ValidateAntiForgeryToken atributo requer um token para solicitações para os métodos de ação

decora, incluindo as solicitações HTTP GET. Se o ValidateAntiForgeryToken atributo é aplicado em
controladores do aplicativo, ele pode ser substituído com o IgnoreAntiforgeryToken atributo.
NOTE
ASP.NET Core não dá suporte a adição de tokens antifalsificação para solicitações GET automaticamente.
Automaticamente validar tokens antifalsificação para métodos HTTP não seguros apenas
Aplicativos ASP.NET Core não geram tokens contra falsificação para métodos HTTP seguros (GET,
HEAD, opções e rastreamento). Em vez de aplicar amplamente a ValidateAntiForgeryToken atributo
e, em seguida, substituindo-o com IgnoreAntiforgeryToken atributos, o
AutoValidateAntiforgeryToken atributo pode ser usado. Esse atributo funciona de maneira idêntica
ao ValidateAntiForgeryToken de atributo, exceto que ele não exige tokens para solicitações feitas
usando os seguintes métodos HTTP:
OBTER
HOME
OPÇÕES
TRACE
É recomendável o uso de AutoValidateAntiforgeryToken em larga escala para cenários de não-API.
Isso garante que as ações de POSTAGEM são protegidas por padrão. A alternativa é ignorar tokens
antifalsificação por padrão, a menos que ValidateAntiForgeryToken é aplicado a métodos de ação
individual. Ele tem mais provavelmente neste cenário para um método de ação a ser deixado POST
desprotegidos por engano, deixando o aplicativo vulnerável a ataques CSRF. Todas as postagens
devem enviar o token antifalsificação.
APIs não têm um mecanismo automático para enviar a parte não-cookie do token. A
implementação provavelmente depende a implementação de código do cliente. Alguns exemplos
são mostrados abaixo:
Exemplo de nível de classe:
[Authorize]
[AutoValidateAntiforgeryToken]
public class ManageController : Controller
{
Exemplo global:
options.Filters.Add(new AutoValidateAntiforgeryTokenAttribute()));
Substituição global ou atributos antifalsificação do controlador

O IgnoreAntiforgeryToken filtro é usado para eliminar a necessidade de um token antifalsificação
para uma determinada ação (ou controlador). Quando aplicado, esse filtro substitui
ValidateAntiForgeryToken e AutoValidateAntiforgeryToken filtros especificados em um nível mais
alto (globalmente ou em um controlador).
[Authorize]
[AutoValidateAntiforgeryToken]
public class ManageController : Controller
{
[HttpPost]
[IgnoreAntiforgeryToken]
public async Task<IActionResult> DoSomethingSafe(SomeViewModel model)
{
// no antiforgery token required
}
}
Tokens de atualização após a autenticação

Tokens devem ser atualizados depois que o usuário é autenticado ao redirecionar o usuário para
uma exibição ou página do Razor.
JavaScript, AJAX e SPAs

Em aplicativos tradicionais baseados em HTML, tokens antifalsificação são passados para o
servidor usando os campos de formulário oculto. Em aplicativos modernos baseados em JavaScript
e SPAs, muitas solicitações são feitas por meio de programação. Essas solicitações AJAX podem
usar outras técnicas (como cabeçalhos de solicitação ou cookies) para enviar o token.
Se os cookies são usados para armazenar tokens de autenticação e para autenticar solicitações de
API no servidor, CSRF é um problema potencial. Se o armazenamento local é usado para
armazenar o token, vulnerabilidade CSRF pode ser reduzida porque os valores do armazenamento
local não são enviadas automaticamente para o servidor com cada solicitação. Dessa forma, usando
o armazenamento local para armazenar o token antifalsificação no cliente e enviar o token como
um cabeçalho de solicitação é uma abordagem recomendada.
JavaScript
Usando o JavaScript com modos de exibição, o token pode ser criado usando um serviço de dentro
da exibição. Injetar o Microsoft.AspNetCore.Antiforgery.IAntiforgery serviço para o modo de
exibição e chame GetAndStoreTokens:
@{
ViewData["Title"] = "AJAX Demo";
}
@inject Microsoft.AspNetCore.Antiforgery.IAntiforgery Xsrf
@functions{
public string GetAntiXsrfRequestToken()
{
return Xsrf.GetAndStoreTokens(Context).RequestToken;
}
}
<input type="hidden" id="RequestVerificationToken"

name="RequestVerificationToken" value="@GetAntiXsrfRequestToken()">
<div class="row">
<p><input type="button" id="antiforgery" value="Antiforgery"></p>
<script>
var xhttp = new XMLHttpRequest();
xhttp.onreadystatechange = function() {
if (xhttp.readyState == XMLHttpRequest.DONE) {
if (xhttp.status == 200) {
alert(xhttp.responseText);
} else {
alert('There was an error processing the AJAX request.');
}
}
};
document.addEventListener('DOMContentLoaded', function() {
document.getElementById("antiforgery").onclick = function () {
xhttp.open('POST', '@Url.Action("Antiforgery", "Home")', true);
xhttp.setRequestHeader("RequestVerificationToken",
document.getElementById('RequestVerificationToken').value);
xhttp.send();
}
});
</script>
</div>
Essa abordagem elimina a necessidade de lidar diretamente com definir cookies a partir do
servidor ou lê-los a partir do cliente.
O exemplo anterior usa JavaScript para ler o valor do campo oculto para o cabeçalho de
POSTAGEM de AJAX.
JavaScript pode também tokens de acesso em cookies e usar o conteúdo do cookie para criar um
cabeçalho com o valor do token.
context.Response.Cookies.Append("CSRF-TOKEN", tokens.RequestToken,
new Microsoft.AspNetCore.Http.CookieOptions { HttpOnly = false });
Supondo que o script solicita para enviar o token em um cabeçalho chamado X-CSRF-TOKEN ,
configure o serviço antifalsificação para procurar o X-CSRF-TOKEN cabeçalho:
services.AddAntiforgery(options => options.HeaderName = "X-CSRF-TOKEN");
O exemplo a seguir usa JavaScript para fazer uma solicitação AJAX com o cabeçalho apropriado:
function getCookie(cname) {
var name = cname + "=";
var decodedCookie = decodeURIComponent(document.cookie);
var ca = decodedCookie.split(';');
for(var i = 0; i <ca.length; i++) {
var c = ca[i];
while (c.charAt(0) == ' ') {
c = c.substring(1);
}
if (c.indexOf(name) == 0) {
return c.substring(name.length, c.length);
}
}
return "";
}
var csrfToken = getCookie("CSRF-TOKEN");
var xhttp = new XMLHttpRequest();

xhttp.onreadystatechange = function() {
if (xhttp.readyState == XMLHttpRequest.DONE) {
if (xhttp.status == 200) {
alert(xhttp.responseText);
} else {
alert('There was an error processing the AJAX request.');
}
}
};
xhttp.open('POST', '/api/password/changepassword', true);
xhttp.setRequestHeader("Content-type", "application/json");
xhttp.setRequestHeader("X-CSRF-TOKEN", csrfToken);
xhttp.send(JSON.stringify({ "newPassword": "ReallySecurePassword999$$$" }));
AngularJS
AngularJS usa uma convenção para endereço CSRF. Se o servidor envia um cookie com o nome
XSRF-TOKEN , o AngularJS $http serviço adiciona o valor do cookie a um cabeçalho quando ele
envia uma solicitação ao servidor. Esse processo é automático. O cabeçalho não precisa ser definido
explicitamente. O nome do cabeçalho é X-XSRF-TOKEN . O servidor deve detectar esse cabeçalho e
validar seu conteúdo.
Para a API do ASP.NET Core trabalhe com essa convenção:
Configurar seu aplicativo para fornecer um token em um cookie chamado XSRF-TOKEN .
Configurar o serviço antifalsificação para procurar por um cabeçalho chamado X-XSRF-TOKEN .
services.AddAntiforgery(options => options.HeaderName = "X-XSRF-TOKEN");
Estender antifalsificação
O IAntiForgeryAdditionalDataProvider tipo permite aos desenvolvedores estender o
comportamento do sistema anti-CSRF por dados adicionais de ciclo completo em cada token. O
GetAdditionalData método é chamado sempre que um token de campo é gerado e o valor de
retorno é incorporado dentro do token gerado. Um implementador poderia retornar um carimbo
de hora, um nonce ou qualquer outro valor e, em seguida, chame ValidateAdditionalData para
validar dados quando o token é validado. Nome de usuário do cliente já está incorporado em
tokens gerados, portanto, não há nenhuma necessidade de incluir essas informações. Se um token
inclui dados complementares, mas não IAntiForgeryAdditionalDataProvider é configurado, os
dados complementares não são validados.
Recursos adicionais
CSRF na Abrir Web Application Security Project (OWASP ).
Impedir ataques de redirecionamento aberto no
ASP.NET Core
Um aplicativo web que redireciona para uma URL que é especificada por meio de solicitação, como os dados de
formulário ou cadeia de consulta potencialmente pode ser violado para redirecionar usuários para uma URL
externa e mal-intencionado. Essa violação é chamado de um ataque de redirecionamento aberto.
Sempre que a lógica do aplicativo redireciona para uma URL especificada, verifique se a URL de redirecionamento
não foi adulterada. O ASP.NET Core tem funcionalidade interna para ajudar a proteger aplicativos contra ataques
de redirecionamento aberto (também conhecido como open redirecionamento).
O que é um ataque de redirecionamento aberto?

Aplicativos Web com frequência redirecionar os usuários para uma página de logon quando acessarem os
recursos que exigem a autenticação. O redirecionamento normalmente inclui uma returnUrl parâmetro
querystring para que o usuário pode ser retornado para a URL solicitada originalmente depois que eles fizeram
logon com êxito. Depois que o usuário é autenticado, ele serão redirecionados para a URL que eles solicitaram
originalmente.
Como a URL de destino é especificada na sequência de consulta da solicitação, um usuário mal-intencionado pode
violar a querystring. Uma cadeia de consulta violada pode permitir que o site redirecionar o usuário para um site
externo, mal-intencionado. Essa técnica é chamada de um ataque de redirecionamento (ou redirecionamento)
aberto.
Um ataque de exemplo
Um usuário mal-intencionado pode desenvolver um ataque de objetivo de permitir que o usuário mal-
intencionado acesso a informações confidenciais ou as credenciais de um usuário. Para iniciar o ataque, o usuário
mal-intencionado convence o usuário clicar em um link para a página de logon do seu site com um returnUrl
valor de cadeia de consulta adicionada à URL. Por exemplo, considere um aplicativo na contoso.com que inclui
uma página de logon no http://contoso.com/Account/LogOn?returnUrl=/Home/About . O ataque segue estas etapas:
1. O usuário clica no link para mal-intencionado
http://contoso.com/Account/LogOn?returnUrl=http://contoso1.com/Account/LogOn (a segunda URL é
"contoso1.com", não "contoso.com").
2. O usuário fizer logon com êxito.
3. O usuário é redirecionado (pelo site) para http://contoso1.com/Account/LogOn (um site mal-intencionado que se
parece exatamente com o site real).
4. O usuário fizer logon novamente (dando mal-intencionado suas credenciais do site) e é redirecionado para o
site real.
O usuário provavelmente acredita que sua primeira tentativa de fazer logon falhou e que sua segunda tentativa
seja bem-sucedida. O usuário provavelmente permanecerá ciente de que suas credenciais estão comprometidas.
Além das páginas de logon, alguns sites fornecem páginas de redirecionamento ou pontos de extremidade.
Imagine que seu aplicativo tem uma página com um redirecionamento aberto, /Home/Redirect . Um invasor pode
criar, por exemplo, um link em um email que vai para
[yoursite]/Home/Redirect?url=http://phishingsite.com/Home/Login . Um usuário típico examinará a URL e ver que
ele começa com o nome do site. Confiar em que, eles clicarem no link. O redirecionamento aberto, em seguida,
enviaria o usuário para o site de phishing, que parece ser idêntico ao seu, e provavelmente o usuário faça logon no
que acreditam for seu site.
Proteção contra ataques de redirecionamento abertos

Ao desenvolver aplicativos da web, trate todos os dados fornecidos pelo usuário como não confiáveis. Se seu
aplicativo tem funcionalidade que redireciona o usuário com base no conteúdo da URL, certifique-se de que tais
redirecionamentos são feitos somente localmente dentro de seu aplicativo (ou uma URL conhecida, não qualquer
URL que pode ser fornecido na cadeia de consulta).
LocalRedirect
Use o LocalRedirect o método auxiliar da base Controller classe:
public IActionResult SomeAction(string redirectUrl)

{
return LocalRedirect(redirectUrl);
}
LocalRedirect lançará uma exceção se uma URL de local não for especificada. Caso contrário, ele se comporta
exatamente como o Redirect método.
IsLocalUrl
Use o IsLocalUrl método para testar a antes de redirecionar URLs:
O exemplo a seguir mostra como verificar se uma URL é local antes de redirecionar.
private IActionResult RedirectToLocal(string returnUrl)

{
if (Url.IsLocalUrl(returnUrl))
{
return Redirect(returnUrl);
}
else
{
}
}
O IsLocalUrl método protege os usuários contra inadvertidamente sendo redirecionado para um site mal-
intencionado. Você pode registrar os detalhes da URL que foi fornecido quando uma URL de local não é fornecida
em uma situação em que você esperava uma URL local. URLs de redirecionamento de registro em log podem
ajudar no diagnóstico de ataques de redirecionamento.
Evitar Cross-Site Scripting (XSS) no ASP.NET Core
Por Rick Anderson

Criação de scripts entre sites (XSS ) é uma vulnerabilidade de segurança que permite que um invasor inserir os
scripts do lado do cliente (geralmente o JavaScript) em páginas da web. Quando outros usuários carregar
páginas afetadas, scripts do invasor serão executado, permitindo que o invasor roubar cookies e tokens de sessão,
altere o conteúdo da página da web por meio de manipulação de DOM ou redirecionar o navegador para outra
página. As vulnerabilidades de XSS geralmente ocorrem quando um aplicativo recebe entrada do usuário e os
coloca em uma página sem validação, codificação ou escape-lo.
Proteger seu aplicativo contra o XSS

AT um XSS de nível básico funciona por enganar o seu aplicativo para inserir uma <script> marca em sua
página processada, ou inserindo um On* eventos em um elemento. Os desenvolvedores devem usar as
seguintes etapas de prevenção para evitar a introdução de XSS em seu aplicativo.
1. Nunca coloque dados não confiáveis em sua entrada HTML, a menos que você siga o restante das etapas
a seguir. Dados não confiáveis são todos os dados que podem ser controlados por um invasor, entradas de
formulário HTML, cadeias de caracteres de consulta, os cabeçalhos HTTP, até mesmo dados originados de
um banco de dados como um invasor pode ser capaz de violar o seu banco de dados, mesmo se eles não
podem violar o seu aplicativo.
2. Antes de colocar os dados não confiáveis dentro de um elemento HTML, verifique se que ele é codificado
em HTML. A codificação HTML usa caracteres, como < e alterá-los em um formulário seguro como <
3. Antes de colocar os dados não confiáveis em um atributo HTML, verifique se que ele é codificado em
HTML. Codificação do atributo HTML é um superconjunto de codificação HTML e codifica os caracteres
adicionais, como "e '.
4. Antes de colocar os dados não confiáveis em JavaScript, colocar os dados em um elemento HTML cujo
conteúdo você recuperar em tempo de execução. Se isso não for possível, verifique se que os dados são
codificado de JavaScript. Codificação de JavaScript usa caracteres perigosos para JavaScript e os substitui
por sua hex, por exemplo < seria codificado como \u003C .
5. Antes de colocar os dados não confiáveis em uma cadeia de caracteres de consulta de URL, verifique se
que ele é codificado por URL.
Codificação HTML usando o Razor

O mecanismo Razor usado no MVC automaticamente codifica todos originado de saída de variáveis, a menos
que você trabalha muito para impedi-lo ao fazer isso. Ele usa as regras de codificação HTML atributo sempre que
você usar o @ diretiva. Como HTML a codificação do atributo é um superconjunto de codificação de HTML, que
isso significa que você não precisa se preocupar com se você deve usar a codificação HTML ou codificação do
atributo HTML. Você deve garantir que você só usar em um contexto HTML, não quando a tentativa de inserir
entradas não confiáveis diretamente em JavaScript. Os auxiliares de marca codificará também usar parâmetros
de marca de entrada.
Execute o seguinte modo de exibição do Razor:
@{
var untrustedInput = "<\"123\">";
}
@untrustedInput
Essa exibição mostra o conteúdo do untrustedInput variável. Essa variável inclui alguns caracteres que são usadas
em ataques de XSS, ou seja, <, "e >. Examinar o código-fonte mostra a saída renderizada codificada como:
<"123">
WARNING
ASP.NET Core MVC fornece uma HtmlString classe que não é codificado automaticamente após a saída. Isso nunca deve
ser usado em combinação com entradas não confiáveis, pois isso irá expor uma vulnerabilidade de XSS.
Usando o Razor de codificação do JavaScript

Pode haver ocasiões que você deseja inserir um valor em JavaScript para processar no modo de exibição. Há
duas formas de fazer isso. A maneira mais segura para inserir valores é colocar o valor em um atributo de dados
de uma marca e recuperá-lo em seu JavaScript. Por exemplo:
@{
}
<div
id="injectedData"
data-untrustedinput="@untrustedInput" />
<script>
var injectedData = document.getElementById("injectedData");
// All clients
var clientSideUntrustedInputOldStyle =
injectedData.getAttribute("data-untrustedinput");
// HTML 5 clients only

var clientSideUntrustedInputHtml5 =
injectedData.dataset.untrustedinput;
document.write(clientSideUntrustedInputOldStyle);
document.write("<br />")
document.write(clientSideUntrustedInputHtml5);
</script>
Isso produzirá o HTML a seguir

<div
id="injectedData"
data-untrustedinput="<"123">" />
<script>
var injectedData = document.getElementById("injectedData");
var clientSideUntrustedInputOldStyle =
injectedData.getAttribute("data-untrustedinput");
var clientSideUntrustedInputHtml5 =
injectedData.dataset.untrustedinput;
document.write(clientSideUntrustedInputOldStyle);
document.write("<br />")
document.write(clientSideUntrustedInputHtml5);
</script>
Que, quando ele é executado, será renderizado o seguinte:
<"123">
<"123">
Você também pode chamar diretamente o codificador de JavaScript:
@using System.Text.Encodings.Web;
@inject JavaScriptEncoder encoder;
@{
}
<script>
document.write("@encoder.Encode(untrustedInput)");
</script>
Isso será renderizado no navegador da seguinte maneira:
<script>
document.write("\u003C\u0022123\u0022\u003E");
</script>
WARNING
Não concatene entradas não confiáveis em JavaScript para criar elementos DOM. Você deve usar createElement() e
atribuir valores de propriedade adequadamente, como node.TextContent= , ou use element.SetAttribute() /
element[attribute]= caso contrário, você se exporá a XSS baseado em DOM.
Acessando codificadores no código

Os codificadores HTML, JavaScript e a URL estão disponíveis para seu código de duas maneiras, você pode
colocá-los por meio injeção de dependência ou você pode usar os codificadores padrão contidos no
System.Text.Encodings.Web namespace. Se você usar os codificadores padrão, qualquer aplicadas ao intervalos de
caracteres a serem tratados como seguro não terão efeito - os codificadores padrão usam as regras de
codificação mais seguras possíveis.
Para usar os codificadores configuráveis por meio da DI seus construtores devem levar uma HtmlEncoder,
JavaScriptEncoder e UrlEncoder parâmetro conforme apropriado. Por exemplo:

{
HtmlEncoder _htmlEncoder;
JavaScriptEncoder _javaScriptEncoder;
UrlEncoder _urlEncoder;
public HomeController(HtmlEncoder htmlEncoder,

JavaScriptEncoder javascriptEncoder,
UrlEncoder urlEncoder)
{
_htmlEncoder = htmlEncoder;
_javaScriptEncoder = javascriptEncoder;
_urlEncoder = urlEncoder;
}
}
Parâmetros de codificação de URL

Se você quiser criar uma cadeia de caracteres de consulta de URL com a entrada não confiável como um valor,
use o UrlEncoder para codificar o valor. Por exemplo,
var example = "\"Quoted Value with spaces and &\"";

var encodedValue = _urlEncoder.Encode(example);
Após a codificação de encodedValue variável conterá %22Quoted%20Value%20with%20spaces%20and%20%26%22 . Espaços,

aspas, pontuação e outros caracteres não seguros será porcentagem codificado para seu valor hexadecimal, por
exemplo, um caractere de espaço tornará % 20.
WARNING
Não use entradas não confiáveis como parte de um caminho de URL. Sempre passe a entrada não confiável como um valor
de cadeia de caracteres de consulta.
Personalizando os codificadores
Por padrão, codificadores de usam uma lista segura limitada ao intervalo Unicode de Latim básico e codificar
todos os caracteres fora do intervalo como seus equivalentes de código de caractere. Esse comportamento
também afeta a renderização TagHelper Razor e HtmlHelper como ele utilizará os codificadores para suas cadeias
de caracteres de saída.
O raciocínio por trás disso é proteger contra bugs no navegador desconhecido ou futuras (bugs no navegador
anterior tiveram atropelados análise com base no processamento de caracteres do inglês). Se seu site da web faz
uso intenso de caracteres não latinos, como o chinês, cirílico ou outras pessoas isso provavelmente não é o
comportamento desejado.
Você pode personalizar as listas de seguro de codificador para incluir Unicode intervalos apropriadas para seu
aplicativo durante a inicialização, no ConfigureServices() .
Por exemplo, usando a configuração padrão que você pode usar um HtmlHelper Razor assim;
<p>This link text is in Chinese: @Html.ActionLink("汉语/漢語", "Index")</p>

Quando você exibir a origem da página da web, você verá que ele foi renderizado da seguinte maneira, com o
texto codificado; em chinês
<p>This link text is in Chinese: <a href="/">汉语/漢語</a></p>
Ampliar os caracteres tratados como seguro pelo codificador você inseriria a linha a seguir para o
ConfigureServices() método no startup.cs ;
services.AddSingleton<HtmlEncoder>(
HtmlEncoder.Create(allowedRanges: new[] { UnicodeRanges.BasicLatin,
UnicodeRanges.CjkUnifiedIdeographs }));
Este exemplo amplia a lista segura para incluir o CjkUnifiedIdeographs de intervalo Unicode. A saída renderizada
tornaria
<p>This link text is in Chinese: <a href="/">汉语/漢語</a></p>
Intervalos de lista segura são especificados como gráficos de código Unicode, não os idiomas. O padrão Unicode
tem uma lista de gráficos de código você pode usar para localizar o gráfico que contém os caracteres. Cada
codificador, Html, JavaScript e a Url, deve ser configurado separadamente.
NOTE
Personalização da lista de confiáveis afeta apenas os codificadores originados por meio da DI. Se você acessar diretamente
um codificador via System.Text.Encodings.Web.*Encoder.Default , em seguida, o padrão, Latim básico somente lista
segura será usada.
Onde a codificação take deve colocar?

Em geral aceito prática é que a codificação ocorre no ponto de saída e valores codificados nunca devem ser
armazenados em um banco de dados. Codificação no ponto de saída permite que você altere o uso de dados, por
exemplo, de HTML para um valor de cadeia de caracteres de consulta. Ele também permite que você pesquise
facilmente seus dados sem a necessidade de codificar valores antes de pesquisar e permite que você se beneficie
de quaisquer alterações ou correções de bug feitas aos codificadores.
Validação como uma técnica de prevenção de XSS

Validação pode ser uma ferramenta útil na limitação de ataques de XSS. Por exemplo, uma cadeia de caracteres
numérica que contém somente os caracteres de 0 a 9 não disparar um ataque XSS. Validação se torna mais
complicada ao aceitar HTML na entrada do usuário. Analisar a entrada em HTML é difícil, se não impossível.
Markdown, juntamente com um analisador que retira HTML incorporado, é uma opção mais segura para aceitar
a entrada avançada. Nunca confie em validação sozinha. Sempre codificar entradas não confiáveis antes da saída,
não importa quais validação ou limpeza foi executada.
Habilitar solicitações entre origens (CORS) no
ASP.NET Core
Por Mike Wasson, Shayne Boyer, e Tom Dykstra

Segurança do navegador impede que uma página da web fazendo solicitações para um domínio diferente
daquele que atendia a página da web. Essa restrição é chamada de política de mesma origem. A política de
mesma origem impede que um site mal-intencionado leia dados confidenciais de outro site. Às vezes, você
talvez queira permitir que outros sites fazem solicitações entre origens em seu aplicativo.
Entre o compartilhamento de recursos de origem (CORS ) é um padrão W3C que permite que um servidor
relaxar a política de mesma origem. Usando o CORS, um servidor pode explicitamente permitir algumas
solicitações entre origens enquanto rejeita outras. O CORS é mais seguro e flexível que técnicas anteriores, tais
como JSONP. Este tópico mostra como habilitar o CORS em um aplicativo ASP.NET Core.
Mesma origem
Duas URLs têm a mesma origem se eles têm esquemas idênticas, hosts e portas ( 6454 RFC ).
Essas duas URLs têm a mesma origem:
https://example.com/foo.html
https://example.com/bar.html
Essas URLs têm diferentes origens que as duas URLs anteriores:

https://example.net – Domínio diferente
https://www.example.com/foo.html – Subdomínio diferente
http://example.com/foo.html – Esquema diferente
https://example.com:9000/foo.html – Porta diferente
NOTE
Internet Explorer não considera a porta ao comparar as origens.
Registrar os serviços do CORS

Referência a metapacote do Microsoft ou adicionar uma referência de pacote para o Microsoft.AspNetCore.Cors
pacote.
Referência a metapacote Microsoft.AspNetCore.All ou adicionar uma referência de pacote para o
Microsoft.AspNetCore.Cors pacote.
Adicionar uma referência de pacote para o Microsoft.AspNetCore.Cors pacote.
Chame AddCors em Startup.ConfigureServices para adicionar serviços do CORS ao contêiner de serviço do
aplicativo:
{
services.AddCors();
}
Habilitar o CORS
Depois de registrar os serviços do CORS, use qualquer uma das abordagens a seguir para habilitar o CORS em
um aplicativo ASP.NET Core:
Middleware do CORS – políticas CORS se aplicam globalmente para o aplicativo por meio do middleware.
O CORS no MVC – políticas aplicar CORS por controlador ou por ação. Middleware CORS não é usada.
Habilitar o CORS com Middleware CORS
Middleware CORS manipula solicitações entre origens para o aplicativo. Para habilitar o CORS Middleware no
pipeline de processamento de solicitação, chame o UseCors método de extensão no Startup.Configure .
Middleware CORS devem preceder quaisquer pontos de extremidade definidos em seu aplicativo onde você
deseja dar suporte a solicitações entre origens (por exemplo, antes de chamar UseMvc de Middleware de
páginas do Razor/MVC ).
Um política entre origens pode ser especificado ao adicionar o Middleware CORS usando o CorsPolicyBuilder
classe. Há duas abordagens para definir uma política CORS:
Chamar UseCors com um lambda:

{
{
}
// Shows UseCors with CorsPolicyBuilder.

builder.WithOrigins("http://example.com"));

{
});
O lambda utiliza um CorsPolicyBuilder objeto. Opções de configuração, tais como WithOrigins , são
descritas posteriormente neste tópico. No exemplo anterior, a política permite que solicitações entre
origens de https://example.com e sem outras origens.
A URL deve ser especificada sem uma barra à direita ( / ). Se a URL termina com / , a comparação
retorna false e nenhum cabeçalho é retornado.
CorsPolicyBuilder tem uma API fluente, portanto, é possível encadear chamadas de método:
.AllowAnyHeader()
);
Definir uma ou mais políticas CORS e selecione a política por nome em tempo de execução. O exemplo a
seguir adiciona uma política CORS definida pelo usuário chamada AllowSpecificOrigin. Para selecionar a
política, passe o nome para UseCors :

{
services.AddCors(options =>
{
options.AddPolicy("AllowSpecificOrigin",
builder => builder.WithOrigins("http://example.com"));
});
}

{
{
}
// Shows UseCors with named policy.

app.UseCors("AllowSpecificOrigin");

{
});
}
Habilitar o CORS no MVC

Como alternativa, você pode usar o MVC para aplicar políticas CORS específicas por ação ou por controlador.
Ao usar o MVC para habilitar o CORS, os serviços registrados de CORS são usados. O Middleware do CORS
não é usado.
Por ação
Para especificar uma política CORS para uma ação específica, adicione a [EnableCors] atributo à ação.
Especifique o nome da política.
[HttpGet]
[EnableCors("AllowSpecificOrigin")]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
Por controlador
Para especificar a política CORS para um controlador específico, adicione a [EnableCors] atributo à classe do
controlador. Especifique o nome da política.
[EnableCors("AllowSpecificOrigin")]
public class ValuesController : ControllerBase
A ordem de precedência é:
1. ação
2. controlador
Desabilitar o CORS
Para desabilitar CORS para um controlador ou ação, use o [DisableCors] atributo:
[HttpGet("{id}")]
[DisableCors]
public string Get(int id)
{
return "value";
}
Opções de política de CORS

Esta seção descreve as várias opções que podem ser definidas em uma política CORS.
Defina as origens permitidas
Defina os métodos HTTP permitidos
Definir os cabeçalhos de solicitação permitido
Definir os cabeçalhos de resposta exposto
Credenciais nas solicitações entre origens
Definir o tempo de expiração de simulação
Para algumas opções, pode ser útil ler o funciona como o CORS seção pela primeira vez.
Defina as origens permitidas
Para permitir que um ou mais origens específicas, chame WithOrigins:
options.AddPolicy("AllowSpecificOrigins",
builder =>
{
builder.WithOrigins("http://example.com", "http://www.contoso.com");
});
Para permitir todas as origens, chamar AllowAnyOrigin:
options.AddPolicy("AllowAllOrigins",
builder =>
{
builder.AllowAnyOrigin();
});
Considere cuidadosamente antes de permitir que solicitações de qualquer origem. Permitir solicitações de
qualquer origem significa que de qualquer site pode fazer solicitações entre origens ao seu aplicativo.
Essa configuração afeta comprovação solicitações e o cabeçalho Access-Control-Allow -Origin (descrito
posteriormente neste tópico).
Defina os métodos HTTP permitidos
Para permitir que todos os métodos HTTP, chamar AllowAnyMethod:
options.AddPolicy("AllowAllMethods",
builder =>
{
.AllowAnyMethod();
});
Essa configuração afeta comprovação solicitações e o cabeçalho Access-Control-Allow -Methods (descrito

Definir os cabeçalhos de solicitação permitido
Para permitir que os cabeçalhos específicos a serem enviados em uma solicitação CORS, chamado criar
cabeçalhos de solicitação, chame WithHeaders e especificar os cabeçalhos permitidos:
options.AddPolicy("AllowHeaders",
builder =>
{
.WithHeaders(HeaderNames.ContentType, "x-custom-header");
});
Para permitir que todos os cabeçalhos de solicitação do autor chamar AllowAnyHeader:
options.AddPolicy("AllowAllHeaders",
builder =>
{
.AllowAnyHeader();
});
Essa configuração afeta comprovação solicitações e o cabeçalho Access-Control-Request-Headers (descrito

Uma correspondência de política de Middleware do CORS para cabeçalhos específicos especificado por
WithHeaders só é possível quando os cabeçalhos enviados Access-Control-Request-Headers coincidir exatamente
com os cabeçalhos indicados na WithHeaders .
Por exemplo, considere um aplicativo configurado da seguinte maneira:
app.UseCors(policy => policy.WithHeaders(HeaderNames.CacheControl));
Middleware CORS recusar uma solicitação de simulação com o seguinte cabeçalho de solicitação, pois
Content-Language ( HeaderNames.ContentLanguage) não está listado no WithHeaders :
Access-Control-Request-Headers: Cache-Control, Content-Language
O aplicativo retorna um 200 Okey resposta, mas não envia de volta os cabeçalhos de CORS. Portanto, o
navegador não tente a solicitação entre origens.
Middleware CORS sempre permite que os cabeçalhos de quatro no Access-Control-Request-Headers a ser
enviado, independentemente dos valores configurados no CorsPolicy.Headers. Esta lista de cabeçalhos inclui:
Accept
Accept-Language
Content-Language
Origin
Por exemplo, considere um aplicativo configurado da seguinte maneira:
app.UseCors(policy => policy.WithHeaders(HeaderNames.CacheControl));
Middleware CORS responde com êxito a uma solicitação de simulação com o seguinte cabeçalho de solicitação
porque Content-Language é sempre na lista de permissões:
Access-Control-Request-Headers: Cache-Control, Content-Language
Definir os cabeçalhos de resposta exposto

Por padrão, o navegador não expõe todos os cabeçalhos de resposta para o aplicativo. Para obter mais
informações, consulte W3C Cross-Origin Resource Sharing (terminologia): o cabeçalho de resposta simples.
Os cabeçalhos de resposta que estão disponíveis por padrão são:
Cache-Control
Content-Language
Content-Type
Expires
Last-Modified
Pragma
A especificação CORS chama esses cabeçalhos cabeçalhos de resposta simples. Para disponibilizar outros
cabeçalhos para o aplicativo, chame WithExposedHeaders:
options.AddPolicy("ExposeResponseHeaders",
builder =>
{
.WithExposedHeaders("x-custom-header");
});
Credenciais nas solicitações entre origens

Credenciais exigem tratamento especial em uma solicitação CORS. Por padrão, o navegador não envia as
credenciais com uma solicitação entre origens. As credenciais incluem cookies e esquemas de autenticação
HTTP. Para enviar as credenciais com uma solicitação entre origens, o cliente deve definir
XMLHttpRequest.withCredentials para true .
Usando XMLHttpRequest diretamente:
var xhr = new XMLHttpRequest();

xhr.open('get', 'https://www.example.com/api/test');
xhr.withCredentials = true;
No jQuery:
$.ajax({
type: 'get',
url: 'https://www.example.com/home',
xhrFields: {
withCredentials: true
}
Além disso, o servidor deve permitir que as credenciais. Para permitir credenciais entre origens, chamar
AllowCredentials:
options.AddPolicy("AllowCredentials",
builder =>
{
});
A resposta HTTP inclui um Access-Control-Allow-Credentials cabeçalho, que informa ao navegador que o

servidor permite que as credenciais para uma solicitação entre origens.
Se o navegador envia as credenciais, mas a resposta não inclui um válido Access-Control-Allow-Credentials
cabeçalho, o navegador não expõe a resposta para o aplicativo e a solicitação entre origens falhar.
Tenha cuidado ao permitindo credenciais entre origens. Um site em outro domínio pode enviar credenciais do
usuário conectado para o aplicativo em nome do usuário sem o conhecimento do usuário.
A especificação CORS também declara que a configuração origens "*" (todas as origens) é inválida se o
Access-Control-Allow-Credentials cabeçalho está presente.
Solicitações de simulação
Para algumas solicitações CORS, o navegador envia uma solicitação adicional antes de fazer a solicitação real.
Essa solicitação é chamada de um solicitação de simulação. O navegador pode ignorar a solicitação de
simulação se as seguintes condições forem verdadeiras:
O método de solicitação é GET, HEAD ou POST.
O aplicativo não define cabeçalhos de solicitação diferente de Accept , Accept-Language , Content-Language ,
Content-Type , ou Last-Event-ID .
O Content-Type cabeçalho, se definido, tem um dos seguintes valores:
application/x-www-form-urlencoded
multipart/form-data
text/plain
A regra em cabeçalhos de solicitação definido para a solicitação do cliente se aplica aos cabeçalhos que o
aplicativo define chamando setRequestHeader sobre o XMLHttpRequest objeto. A especificação CORS chama
esses cabeçalhos criar cabeçalhos de solicitação. A regra não se aplica aos cabeçalhos, o navegador pode definir,
tais como User-Agent , Host , ou Content-Length .
Este é um exemplo de uma solicitação de simulação:
OPTIONS https://myservice.azurewebsites.net/api/test HTTP/1.1
Accept: */*
Origin: https://myclient.azurewebsites.net
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: accept, x-my-custom-header
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0)
Host: myservice.azurewebsites.net
Content-Length: 0
A solicitação de simulação usa o método HTTP OPTIONS. Ele inclui dois cabeçalhos especiais:
Access-Control-Request-Method : O método HTTP que será usado para a solicitação real.
Access-Control-Request-Headers : Uma lista de cabeçalhos de solicitação que o aplicativo define a solicitação
real. Conforme mencionado anteriormente, isso não inclui os cabeçalhos que define o navegador, tais como
User-Agent .
Uma solicitação de simulação de CORS pode incluir um Access-Control-Request-Headers cabeçalho, que indica
ao servidor, os cabeçalhos que são enviados com a solicitação real.
Para permitir que os cabeçalhos específicos, chame WithHeaders:
options.AddPolicy("AllowHeaders",
builder =>
{
.WithHeaders(HeaderNames.ContentType, "x-custom-header");
});
Para permitir que todos os cabeçalhos de solicitação do autor chamar AllowAnyHeader:
options.AddPolicy("AllowAllHeaders",
builder =>
{
.AllowAnyHeader();
});
Navegadores não estão totalmente consistentes em como eles definir Access-Control-Request-Headers . Se você
definir os cabeçalhos para algo diferente de "*" (ou use AllowAnyHeader), você deve incluir pelo menos
Accept , Content-Type , e Origin , além de quaisquer cabeçalhos personalizados que você deseja dar suporte.
Este é um exemplo de resposta à solicitação de simulação (supondo que o servidor permite que a solicitação):
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 0
Access-Control-Allow-Origin: https://myclient.azurewebsites.net
Access-Control-Allow-Headers: x-my-custom-header
Access-Control-Allow-Methods: PUT
Date: Wed, 20 May 2015 06:33:22 GMT
A resposta inclui um Access-Control-Allow-Methods cabeçalho que lista os métodos permitidos e,

opcionalmente, um Access-Control-Allow-Headers cabeçalho, que lista os cabeçalhos permitidos. Se a solicitação
de simulação for bem-sucedida, o navegador envia a solicitação real.
Se a solicitação de simulação for negada, o aplicativo retornar um 200 Okey resposta, mas não envia de volta os
cabeçalhos de CORS. Portanto, o navegador não tente a solicitação entre origens.
Definir o tempo de expiração de simulação
O Access-Control-Max-Age cabeçalho Especifica quanto tempo a resposta à solicitação de simulação pode ser
armazenados em cache. Para definir esse cabeçalho, chame SetPreflightMaxAge:
options.AddPolicy("SetPreflightExpiration",
builder =>
{
.SetPreflightMaxAge(TimeSpan.FromSeconds(2520));
});
Como funciona o CORS

Esta seção descreve o que acontece em uma solicitação CORS no nível das mensagens HTTP. É importante
entender o funcionamento de CORS para que a política CORS pode ser configurada corretamente e depurada
quando comportamentos inesperados ocorrerem.
A especificação CORS apresenta vários novos cabeçalhos HTTP que permitem que solicitações entre origens.
Se um navegador oferece suporte a CORS, ele define esses cabeçalhos automaticamente para solicitações entre
origens. Código JavaScript personalizado não é necessário para habilitar o CORS.
O exemplo a seguir é um exemplo de uma solicitação entre origens. O Origin cabeçalho fornece o domínio do
site que está fazendo a solicitação:
GET https://myservice.azurewebsites.net/api/test HTTP/1.1

Referer: https://myclient.azurewebsites.net/
Accept: */*
Accept-Language: en-US
Origin: https://myclient.azurewebsites.net
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0)
Host: myservice.azurewebsites.net
Se o servidor permite que a solicitação, ele define o Access-Control-Allow-Origin cabeçalho na resposta. O valor
desse cabeçalho também corresponde a Origin cabeçalho da solicitação ou é o valor de curinga "*" , o que
significa que qualquer origem é permitida:
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: text/plain; charset=utf-8
Access-Control-Allow-Origin: https://myclient.azurewebsites.net
Date: Wed, 20 May 2015 06:27:30 GMT
Content-Length: 12
Test message
Se a resposta não inclui o Access-Control-Allow-Origin falha do cabeçalho, a solicitação entre origens.

Especificamente, o navegador não permite a solicitação. Mesmo se o servidor retorna uma resposta bem-
sucedida, o navegador não disponibiliza a resposta para o aplicativo cliente.
Recursos adicionais
Cross-Origin Resource Sharing (CORS )
Compartilhar cookies entre aplicativos com o
ASP.NET e ASP.NET Core
Por Rick Anderson e Luke Latham

Sites geralmente consistem em aplicativos web individuais trabalhando juntos. Para fornecer uma experiência de
logon único (SSO ), aplicativos web dentro de um site devem compartilhar cookies de autenticação. Para dar
suporte a esse cenário, a pilha de proteção de dados permite o compartilhamento de autenticação de cookie do
Katana e tíquetes de autenticação de cookie do ASP.NET Core.
O exemplo ilustra o cookie compartilhando entre três aplicativos que usam a autenticação de cookie:
Aplicativo do ASP.NET Core 2.0 as páginas do Razor sem usar ASP.NET Core Identity
Aplicativo MVC do ASP.NET Core 2.0 com o ASP.NET Core Identity
Aplicativo MVC do ASP.NET Framework 4.6.1 com o ASP.NET Identity
Nos exemplos a seguir:
O nome do cookie de autenticação é definido como um valor comum de .AspNet.SharedCookie .
O AuthenticationType é definido como Identity.Application explicitamente ou por padrão.
Um nome de aplicativo comum é usado para permitir que o sistema de proteção de dados compartilhar as
chaves de proteção de dados ( SharedCookieApp ).
Identity.Application é usado como o esquema de autenticação. Qualquer esquema é usada, ele deve ser
usado de forma consistente dentro e entre os aplicativos de cookie compartilhado como o esquema padrão ou
ao defini-lo. O esquema é usado ao criptografar e descriptografar cookies, portanto, um esquema consistente
deve ser usado entre aplicativos.
Um comum chave da proteção de dados armazenamento local é usado. O aplicativo de exemplo usa uma pasta
chamada token de autenticação na raiz da solução para manter as chaves de proteção de dados.
Em aplicativos ASP.NET Core, PersistKeysToFileSystem é usado para definir o local de armazenamento de
chaves. SetApplicationName é usado para configurar um nome de aplicativo compartilhado comum.
No aplicativo do .NET Framework, o middleware de autenticação de cookie usa uma implementação
DataProtectionProvider. DataProtectionProvider fornece serviços de proteção de dados para a criptografia e
descriptografia de dados de conteúdo do cookie de autenticação. O DataProtectionProvider instância é isolada
do sistema de proteção de dados usado por outras partes do aplicativo.
DataProtectionProvider.Create (DirectoryInfo, uma ação<IDataProtectionBuilder >) aceita uma
DirectoryInfo para especificar o local para armazenamento de chaves de proteção de dados. O aplicativo
de exemplo fornece o caminho da token de autenticação pasta a ser DirectoryInfo .
DataProtectionBuilderExtensions.SetApplicationName define o nome comum do aplicativo.
DataProtectionProvider exige as Microsoft.AspNetCore.DataProtection.Extensions pacote do NuGet.
Para obter esse pacote para o ASP.NET Core 2.1 e posteriores aplicativos, fazer referência a metapacote
Microsoft. Ao direcionar o .NET Framework, adicione uma referência de pacote ao
Microsoft.AspNetCore.DataProtection.Extensions .
Compartilhar cookies de autenticação entre aplicativos do ASP.NET

Core
Ao usar a identidade do ASP.NET Core:
No ConfigureServices método, use o ConfigureApplicationCookie método de extensão para configurar o serviço
de proteção de dados para cookies.
.PersistKeysToFileSystem(GetKeyRingDirInfo())
.SetApplicationName("SharedCookieApp");
services.ConfigureApplicationCookie(options => {
options.Cookie.Name = ".AspNet.SharedCookie";
});
Chaves de proteção de dados e o nome do aplicativo devem ser compartilhados entre aplicativos. Em aplicativos
de exemplo, GetKeyRingDirInfo retorna o local de armazenamento de chaves comuns para o
PersistKeysToFileSystem método. Use SetApplicationName para configurar um nome de aplicativo compartilhado
comum ( SharedCookieApp no exemplo). Para obter mais informações, consulte Configurando a proteção de dados.
Ao hospedar aplicativos que compartilham cookies entre subdomínios, especifique um domínio comum na
Cookie.Domain propriedade. Compartilhar cookies entre aplicativos no contoso.com , como
first_subdomain.contoso.com e second_subdomain.contoso.com , especifique o Cookie.Domain como .contoso.com :
options.Cookie.Domain = ".contoso.com";
Consulte a CookieAuthWithIdentity.Core do projeto na código de exemplo (como baixar).

No Configure método, use o CookieAuthenticationOptions configurar:
O serviço de proteção de dados para cookies.
O AuthenticationScheme para coincidir com o ASP.NET 4. x.
app.AddIdentity<ApplicationUser, IdentityRole>(options =>

{
options.Cookies.ApplicationCookie.AuthenticationScheme =
"ApplicationCookie";
var protectionProvider =
DataProtectionProvider.Create(
new DirectoryInfo(@"PATH_TO_KEY_RING_FOLDER"));
options.Cookies.ApplicationCookie.DataProtectionProvider =
protectionProvider;
options.Cookies.ApplicationCookie.TicketDataFormat =
new TicketDataFormat(protectionProvider.CreateProtector(
"Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationMiddleware",
"Cookies",
"v2"));
});
Ao usar cookies diretamente:

.PersistKeysToFileSystem(GetKeyRingDirInfo())
.SetApplicationName("SharedCookieApp");
services.AddAuthentication("Identity.Application")
.AddCookie("Identity.Application", options =>
{
options.Cookie.Name = ".AspNet.SharedCookie";
});
Chaves de proteção de dados e o nome do aplicativo devem ser compartilhados entre aplicativos. Em aplicativos
de exemplo, GetKeyRingDirInfo retorna o local de armazenamento de chaves comuns para o
PersistKeysToFileSystem método. Use SetApplicationName para configurar um nome de aplicativo compartilhado
comum ( SharedCookieApp no exemplo). Para obter mais informações, consulte Configurando a proteção de dados.
Ao hospedar aplicativos que compartilham cookies entre subdomínios, especifique um domínio comum na
Cookie.Domain propriedade. Compartilhar cookies entre aplicativos no contoso.com , como
first_subdomain.contoso.com e second_subdomain.contoso.com , especifique o Cookie.Domain como .contoso.com :
options.Cookie.Domain = ".contoso.com";
Consulte a CookieAuth.Core do projeto na código de exemplo (como baixar).
app.UseCookieAuthentication(new CookieAuthenticationOptions
{
DataProtectionProvider =
DataProtectionProvider.Create(
new DirectoryInfo(@"PATH_TO_KEY_RING_FOLDER"))
});
Criptografar as chaves de proteção de dados em repouso

Para implantações de produção, configure o DataProtectionProvider para criptografar as chaves em repouso com
DPAPI ou um X509Certificate. Ver chave de criptografia em repouso para obter mais informações.
{
DataProtectionProvider = DataProtectionProvider.Create(
new DirectoryInfo(@"PATH_TO_KEY_RING"),
configure =>
{
configure.ProtectKeysWithCertificate("thumbprint");
})
});
Compartilhamento de cookies de autenticação entre o ASP.NET 4. x e

aplicativos ASP.NET Core
Os aplicativos do ASP.NET 4.x que usam o middleware de autenticação de cookie do Katana podem ser
configurados para gerar os cookies de autenticação que são compatíveis com o middleware de autenticação de
cookie do ASP.NET Core. Isso permite atualizar aplicativos individuais de um grande site gradativamente,
fornecendo uma experiência de SSO suave em todo o site.
Quando um aplicativo usa o middleware de autenticação de cookie do Katana, ele chama UseCookieAuthentication
do projeto Startup.Auth.cs arquivo. Projetos de aplicativo web do ASP.NET 4.x criado com o Visual Studio 2013 e
posterior, use o middleware de autenticação de cookie do Katana por padrão. Embora UseCookieAuthentication
está obsoleto e sem suporte para aplicativos ASP.NET Core, chamando UseCookieAuthentication em um
aplicativo do ASP.NET 4.x que usa o Katana middleware de autenticação de cookie é válido.
Um aplicativo do ASP.NET 4. x deve ter como destino do .NET Framework 4.5.1 ou superior. Caso contrário, não
conseguir instalar os pacotes NuGet necessários.
Para compartilhar cookies de autenticação entre um aplicativo do ASP.NET 4.x e um aplicativo ASP.NET Core,
configurar o aplicativo ASP.NET Core, conforme mencionado acima e, em seguida, configurar o aplicativo do
ASP.NET 4.x, seguindo estas etapas:
1. Instale o pacote Microsoft.Owin.Security.Interop em cada aplicativo do ASP.NET 4. x.
2. Na Startup.Auth.cs, localize a chamada para UseCookieAuthentication e modificá-lo da seguinte maneira.
Altere o nome do cookie para corresponder ao nome usado pelo middleware de autenticação de cookie do
ASP.NET Core. Fornecer uma instância de um DataProtectionProvider inicializado para o local de
armazenamento de chaves de proteção de dados comuns. Certifique-se de que o nome do aplicativo é
definido como o nome de aplicativo comum usado por todos os aplicativos que compartilham os cookies,
SharedCookieApp no aplicativo de exemplo.
{
AuthenticationType = "Identity.Application",
CookieName = ".AspNet.SharedCookie",
LoginPath = new PathString("/Account/Login"),
Provider = new CookieAuthenticationProvider
{
OnValidateIdentity =
SecurityStampValidator
.OnValidateIdentity<ApplicationUserManager, ApplicationUser>(
validateInterval: TimeSpan.FromMinutes(30),
regenerateIdentity: (manager, user) =>
user.GenerateUserIdentityAsync(manager))
},
TicketDataFormat = new AspNetTicketDataFormat(
new DataProtectorShim(
DataProtectionProvider.Create(GetKeyRingDirInfo(),
(builder) => { builder.SetApplicationName("SharedCookieApp"); })
.CreateProtector(
"Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationMiddleware",
"Identity.Application",
"v2"))),
CookieManager = new ChunkingCookieManager()
});
// If not setting http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier and

// http://schemas.microsoft.com/accesscontrolservice/2010/07/claims/identityprovider,
// then set UniqueClaimTypeIdentifier to a claim that distinguishes unique users.
System.Web.Helpers.AntiForgeryConfig.UniqueClaimTypeIdentifier =
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name";
Consulte a CookieAuthWithIdentity.NETFramework do projeto na código de exemplo (como baixar).

Ao gerar uma identidade de usuário, o tipo de autenticação deve corresponder ao tipo definido em
AuthenticationType definido com UseCookieAuthentication .
Models/IdentityModels.cs:
public async Task<ClaimsIdentity> GenerateUserIdentityAsync(UserManager<ApplicationUser> manager)
{
// Note the authenticationType must match the one defined in
CookieAuthenticationOptions.AuthenticationType
var userIdentity = await manager.CreateIdentityAsync(this, "Identity.Application");
// Add custom user claims here
return userIdentity;
}
Usar um banco de dados de usuário comum

Confirme que o sistema de identidade para cada aplicativo está apontado para o mesmo banco de dados do
usuário. Caso contrário, o sistema de identidade gera falhas em tempo de execução quando ele tenta
corresponder as informações no cookie de autenticação em relação as informações em seu banco de dados.
Recursos adicionais
Lista segura IP do cliente para o ASP.NET Core
Por Damien Bowden e Tom Dykstra

Este artigo mostra três maneiras de implementar uma lista segura IP (também conhecido como uma lista de
permissões) em um aplicativo ASP.NET Core. Você pode usar:
Middleware para verificar o endereço IP remoto de cada solicitação.
Filtros de ação para verificar o endereço IP remoto de solicitações para controladores específicos ou métodos
de ação.
Filtros de páginas do Razor para verificar o endereço IP remoto de solicitações de páginas do Razor.
O aplicativo de exemplo ilustra as duas abordagens. Em cada caso, uma cadeia de caracteres que contém os
endereços IP de cliente aprovados é armazenada em uma configuração de aplicativo. O middleware ou filtro
analisa a cadeia de caracteres em uma lista e verifica se o IP remoto estiver na lista. Caso contrário, será retornado
um código de status HTTP 403 Proibido.
A lista segura
A lista é configurada na appSettings. JSON arquivo. Ele é uma lista delimitada por ponto e vírgula e pode conter
endereços IPv4 e IPv6.
{
"AdminSafeList": "127.0.0.1;192.168.1.5;::1",
"Logging": {
"LogLevel": {
"Default": "Debug",
}
}
}
Middleware
O Configure método adiciona o middleware e passa a cadeia de caracteres de lista segura para ele em um
parâmetro de construtor.
public void Configure(
IApplicationBuilder app,
{
loggerFactory.AddNLog();
app.UseMiddleware<AdminSafeListMiddleware>(
Configuration["AdminSafeList"]);
app.UseMvc();
}
O middleware analisa a cadeia de caracteres em uma matriz e procura o endereço IP remoto na matriz. Se o
endereço IP remoto não for encontrado, o middleware retornará HTTP 401 proibido. Esse processo de validação é
ignorado para solicitações HTTP Get.
public class AdminSafeListMiddleware
{
private readonly ILogger<AdminSafeListMiddleware> _logger;
private readonly string _adminSafeList;
public AdminSafeListMiddleware(
RequestDelegate next,
ILogger<AdminSafeListMiddleware> logger,
string adminSafeList)
{
_adminSafeList = adminSafeList;
_next = next;
_logger = logger;
}
public async Task Invoke(HttpContext context)

{
if (context.Request.Method != "GET")
{
var remoteIp = context.Connection.RemoteIpAddress;
_logger.LogDebug($"Request from Remote IP address: {remoteIp}");
string[] ip = _adminSafeList.Split(';');
var bytes = remoteIp.GetAddressBytes();

var badIp = true;
foreach (var address in ip)
{
var testIp = IPAddress.Parse(address);
if(testIp.GetAddressBytes().SequenceEqual(bytes))
{
badIp = false;
break;
}
}
if(badIp)
{
$"Forbidden Request from Remote IP address: {remoteIp}");
context.Response.StatusCode = (int)HttpStatusCode.Forbidden;
return;
}
}
await _next.Invoke(context);
}
}
Filtro de ação
Se você quiser uma lista segura somente para controladores específicos ou métodos de ação, use um filtro de
ação. Veja um exemplo:
using System.Linq;
using System.Net;
using Microsoft.AspNetCore.Mvc.Authorization;
namespace ClientIpAspNetCore.Filters
{
public class ClientIdCheckFilter : ActionFilterAttribute
{
private readonly string _safelist;
public ClientIdCheckFilter
(ILoggerFactory loggerFactory, IConfiguration configuration)
{
_logger = loggerFactory.CreateLogger("ClientIdCheckFilter");
_safelist = configuration["AdminSafeList"];
}
public override void OnActionExecuting(ActionExecutingContext context)

{
$"Remote IpAddress: {context.HttpContext.Connection.RemoteIpAddress}");
var remoteIp = context.HttpContext.Connection.RemoteIpAddress;

string[] ip = _safelist.Split(';');

var badIp = true;
{
if (testIp.GetAddressBytes().SequenceEqual(bytes))
{
badIp = false;
break;
}
}
if (badIp)
{
context.Result = new StatusCodeResult(401);
return;
}
base.OnActionExecuting(context);
}
}
}
O filtro de ação é adicionado ao contêiner de serviços.

{
services.AddScoped<ClientIdCheckFilter>();
{
options.Filters.Add
(new ClientIdCheckPageFilter
(_loggerFactory, Configuration));
}).SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}
O filtro, em seguida, pode ser usado em um método de ação ou controlador.
[ServiceFilter(typeof(ClientIdCheckFilter))]
[HttpGet]
public IEnumerable<string> Get()
No aplicativo de exemplo, o filtro é aplicado para o Get método. Portanto, quando você testar o aplicativo,
enviando um Get solicitação de API, o atributo é validar o endereço IP do cliente. Quando você testa chamando a
API com qualquer outro método HTTP, o middleware é validar o IP do cliente.
Filtro de páginas do Razor

Se você quiser uma lista segura para um aplicativo páginas Razor, use um filtro de páginas do Razor. Veja um
exemplo:
using System;
using System.Linq;
using System.Net;
namespace ClientIpAspNetCore
{
public class ClientIdCheckPageFilter : IPageFilter
{
private readonly string _safelist;
public ClientIdCheckPageFilter
(ILoggerFactory loggerFactory, IConfiguration configuration)
{
_logger = loggerFactory.CreateLogger("ClientIdCheckPageFilter");
_safelist = configuration["AdminSafeList"];
}
public void OnPageHandlerExecuting(PageHandlerExecutingContext context)

{
$"Remote IpAddress: {context.HttpContext.Connection.RemoteIpAddress}");
var remoteIp = context.HttpContext.Connection.RemoteIpAddress;

string[] ip = _safelist.Split(';');

var badIp = true;
{
if (testIp.GetAddressBytes().SequenceEqual(bytes))
{
badIp = false;
break;
}
}
if (badIp)
{
context.Result = new StatusCodeResult(401);
return;
}
}
public void OnPageHandlerExecuted(PageHandlerExecutedContext context)

{
}
public void OnPageHandlerSelected(PageHandlerSelectedContext context)

{
}
}
}
Esse filtro é habilitado adicionando-o à coleção de filtros MVC.

{
services.AddScoped<ClientIdCheckFilter>();
{
options.Filters.Add
(new ClientIdCheckPageFilter
(_loggerFactory, Configuration));
}
Quando você executa o aplicativo e solicita uma página Razor, o filtro de páginas do Razor é validar o IP do cliente.
Próximas etapas
Saiba mais sobre o Middleware do ASP.NET Core.
Globalização e localização no ASP.NET Core
Por Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana e Hisham Bin Ateya
A criação de um site multilíngue com o ASP.NET Core permitirá que seu site alcance um público maior. O
ASP.NET Core fornece serviços e middleware para localização em diferentes idiomas e culturas.
A internacionalização envolve Globalização e Localização. Globalização é o processo de criação de aplicativos
que dão suporte a diferentes culturas. A globalização adiciona suporte para entrada, exibição e saída de um
conjunto definido de scripts de idiomas relacionados a áreas geográficas específicas.
Localização é o processo de adaptar um aplicativo globalizado, que você já processou para possibilidade de
localização, a determinada cultura/localidade. Para obter mais informações, consulte Termos de globalização
e localização próximo ao final deste documento.
A localização de aplicativos envolve o seguinte:
1. Tornar o conteúdo do aplicativo localizável
2. Fornecer recursos localizados para as culturas e os idiomas aos quais você dá suporte
3. Implementar uma estratégia para selecionar o idioma e a cultura para cada solicitação
Tornar o conteúdo do aplicativo localizável

Introduzidos no ASP.NET Core IStringLocalizer e IStringLocalizer<T> foram projetados para melhorar a
produtividade ao desenvolver aplicativos localizados. IStringLocalizer usa o ResourceManager e o
ResourceReader para fornecer recursos específicos a uma cultura em tempo de execução. A interface simples
tem um indexador e um IEnumerable para retornar cadeias de caracteres localizadas. IStringLocalizer não
exige o armazenamento das cadeias de caracteres de idioma padrão em um arquivo de recurso. Você pode
desenvolver um aplicativo direcionado à localização e não precisa criar arquivos de recurso no início do
desenvolvimento. O código abaixo mostra como encapsular a cadeia de caracteres "About Title" para
localização.
using Microsoft.Extensions.Localization;
namespace Localization.Controllers
{
public class AboutController : Controller
{
private readonly IStringLocalizer<AboutController> _localizer;
public AboutController(IStringLocalizer<AboutController> localizer)

{
_localizer = localizer;
}
[HttpGet]
public string Get()
{
return _localizer["About Title"];
}
}
}
No código acima, a implementação IStringLocalizer<T> é obtida da Injeção de Dependência. Se o valor

localizado de "About Title" não é encontrado, a chave do indexador é retornada, ou seja, a cadeia de caracteres
"About Title". Deixe as cadeias de caracteres literais de idioma padrão no aplicativo e encapsule-as no
localizador, de modo que você possa se concentrar no desenvolvimento do aplicativo. Você pode desenvolve
seu aplicativo com o idioma padrão e prepará-lo para a etapa de localização sem primeiro criar um arquivo de
recurso padrão. Como alternativa, você pode usar a abordagem tradicional e fornecer uma chave para
recuperar a cadeia de caracteres de idioma padrão. Para muitos desenvolvedores, o novo fluxo de trabalho de
não ter um arquivo .resx de idioma padrão e simplesmente encapsular os literais de cadeia de caracteres pode
reduzir a sobrecarga de localizar um aplicativo. Outros desenvolvedores preferirão o fluxo de trabalho
tradicional, pois ele pode facilitar o trabalho com literais de cadeia de caracteres mais longas e a atualização de
cadeias de caracteres localizadas.
Use a implementação IHtmlLocalizer<T> para recursos que contêm HTML. O IHtmlLocalizer codifica em
HTML os argumentos que são formatados na cadeia de caracteres de recurso, mas não codifica em HTML a
cadeia de caracteres de recurso em si. Na amostra realçada abaixo, apenas o valor do parâmetro name é
codificado em HTML.
using System;
using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc.Localization;
namespace Localization.Controllers
{
public class BookController : Controller
{
private readonly IHtmlLocalizer<BookController> _localizer;
public BookController(IHtmlLocalizer<BookController> localizer)

{
}
public IActionResult Hello(string name)

{
ViewData["Message"] = _localizer["<b>Hello</b><i> {0}</i>", name];
return View();
}
Observação: em geral, recomendamos localizar somente o texto e não o HTML.

No nível mais baixo, você pode obter IStringLocalizerFactory com a Injeção de Dependência:
{
public class TestController : Controller
{
private readonly IStringLocalizer _localizer;
private readonly IStringLocalizer _localizer2;
public TestController(IStringLocalizerFactory factory)

{
var type = typeof(SharedResource);
var assemblyName = new AssemblyName(type.GetTypeInfo().Assembly.FullName);
_localizer = factory.Create(type);
_localizer2 = factory.Create("SharedResource", assemblyName.Name);
}

{
ViewData["Message"] = _localizer["Your application description page."]
+ " loc 2: " + _localizer2["Your application description page."];
O código acima demonstra cada um dos dois métodos Create de alocador.

Você pode particionar as cadeias de caracteres localizadas por controlador, área ou ter apenas um contêiner. No
aplicativo de exemplo, uma classe fictícia chamada SharedResource é usada para recursos compartilhados.
// Dummy class to group shared resources
namespace Localization
{
public class SharedResource
{
}
}
Alguns desenvolvedores usam a classe Startup para conter cadeias de caracteres globais ou compartilhadas.
Na amostra abaixo, os localizadores InfoController e SharedResource são usados:
public class InfoController : Controller

{
private readonly IStringLocalizer<InfoController> _localizer;
private readonly IStringLocalizer<SharedResource> _sharedLocalizer;
public InfoController(IStringLocalizer<InfoController> localizer,

IStringLocalizer<SharedResource> sharedLocalizer)
{
_sharedLocalizer = sharedLocalizer;
}
public string TestLoc()

{
string msg = "Shared resx: " + _sharedLocalizer["Hello!"] +
" Info resx " + _localizer["Hello!"];
return msg;
}
Localização de exibição
O serviço IViewLocalizer fornece cadeias de caracteres localizadas para uma exibição. A classe ViewLocalizer
implementa essa interface e encontra o local do recurso no caminho do arquivo de exibição. O seguinte código
mostra como usar a implementação padrão de IViewLocalizer :
@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer
@{
ViewData["Title"] = Localizer["About"];
}
<p>@Localizer["Use this area to provide additional information."]</p>
A implementação padrão de IViewLocalizer encontra o arquivo de recurso com base no nome de arquivo da
exibição. Não há nenhuma opção para usar um arquivo de recurso compartilhado global. ViewLocalizer
implementa o localizador usando IHtmlLocalizer e, portanto, o Razor não codifica em HTML a cadeia de
caracteres localizada. Parametrize cadeias de recurso e o IViewLocalizer codificará em HTML os parâmetros,
mas não a cadeia de caracteres de recurso. Considere a seguinte marcação do Razor:
@Localizer["<i>Hello</i> <b>{0}!</b>", UserManager.GetUserName(User)]
Um arquivo de recurso em francês pode conter o seguinte:
CHAVE VALOR
<i>Hello</i> <b>{0}!</b> <i>Bonjour</i> <b>{0} !</b>
A exibição renderizada contém a marcação HTML do arquivo de recurso.

Observação: em geral, recomendamos localizar somente o texto e não o HTML.
Para usar um arquivo de recurso compartilhado em uma exibição, injete IHtmlLocalizer<T> :
@using Localization.Services

@inject IHtmlLocalizer<SharedResource> SharedLocalizer
@{
ViewData["Title"] = Localizer["About"];
}
<h1>@SharedLocalizer["Hello!"]</h1>
Localização de DataAnnotations
As mensagens de erro de DataAnnotations são localizadas com IStringLocalizer<T> . Usando a opção
ResourcesPath = "Resources" , as mensagens de erro em RegisterViewModel podem ser armazenadas em um
dos seguintes caminhos:
Resources/ViewModels.Account.RegisterViewModel.fr.resx
Resources/ViewModels/Account/RegisterViewModel.fr.resx

{
[Required(ErrorMessage = "The Email field is required.")]
[EmailAddress(ErrorMessage = "The Email field is not a valid email address.")]
[Display(Name = "Email")]
[Required(ErrorMessage = "The Password field is required.")]

[StringLength(8, ErrorMessage = "The {0} must be at least {2} characters long.", MinimumLength = 6)]
[Display(Name = "Password")]
[Display(Name = "Confirm password")]
[Compare("Password", ErrorMessage = "The password and confirmation password do not match.")]
public string ConfirmPassword { get; set; }
}
No ASP.NET Core MVC 1.1.0 e superior, atributos que não sejam de validação são localizados. O ASP.NET
Core MVC 1.0 não pesquisa cadeias de caracteres localizadas para atributos que não sejam de validação.
Usando uma cadeia de caracteres de recurso para várias classes
O seguinte código mostra como usar uma cadeia de caracteres de recurso para atributos de validação com
várias classes:

{
services.AddMvc()
.AddDataAnnotationsLocalization(options => {
options.DataAnnotationLocalizerProvider = (type, factory) =>
factory.Create(typeof(SharedResource));
});
}
No código anterior, SharedResource é a classe correspondente ao resx em que as mensagens de validação são
armazenadas. Com essa abordagem, DataAnnotations usará apenas SharedResource , em vez de o recurso para
cada classe.
Fornecer recursos localizados para as culturas e os idiomas aos quais

você dá suporte
SupportedCultures e SupportedUICultures
O ASP.NET Core permite que você especifique dois valores de cultura, SupportedCultures e
SupportedUICultures . O objeto CultureInfo para SupportedCultures determina os resultados das funções
dependentes de cultura, como data, hora, número e formatação de moeda. SupportedCultures também
determina a ordem de classificação de texto, convenções de uso de maiúsculas e comparações de cadeia de
caracteres. Consulte CultureInfo.CurrentCulture para obter mais informações sobre como o servidor obtém a
Cultura. O SupportedUICultures determina quais cadeias de caracteres traduzidas (de arquivos .resx) são
pesquisadas pelo ResourceManager. O ResourceManager apenas pesquisa cadeias de caracteres específicas a
uma cultura determinadas por CurrentUICulture . Cada thread no .NET tem objetos CurrentCulture e
CurrentUICulture . O ASP.NET Core inspeciona esses valores durante a renderização de funções dependentes
de cultura. Por exemplo, se a cultura do thread atual estiver definida como "en-US" (inglês, Estados Unidos),
DateTime.Now.ToLongDateString() exibirá "Thursday, February 18, 2016", mas se CurrentCulture estiver
definida como "es-ES" (espanhol, Espanha), o resultado será "jueves, 18 de febrero de 2016".
Arquivos de recurso
Um arquivo de recurso é um mecanismo útil para separar cadeias de caracteres localizáveis do código. Cadeias
de caracteres traduzidas para o idioma não padrão são arquivos de recurso .resx isolados. Por exemplo, talvez
você queira criar um arquivo de recurso em espanhol chamado Welcome.es.resx contendo cadeias de caracteres
traduzidas. "es" são o código de idioma para o espanhol. Para criar esse arquivo de recurso no Visual Studio:
1. No Gerenciador de Soluções, clique com o botão direito do mouse na pasta que conterá o arquivo de
recurso > Adicionar > Novo Item.
2. Na caixa Pesquisar modelos instalados, insira "recurso" e nomeie o arquivo.
3. Insira o valor da chave (cadeia de caracteres nativa) na coluna Nome e a cadeia de caracteres traduzida
na coluna Valor.
O Visual Studio mostra o arquivo Welcome.es.resx.
Nomenclatura do arquivo de recurso

Os recursos são nomeados com o nome completo do tipo de sua classe menos o nome do assembly. Por
exemplo, um recurso em francês em um projeto cujo assembly principal é LocalizationWebsite.Web.dll para a
classe LocalizationWebsite.Web.Startup será nomeado Startup.fr.resx. Um recurso para a classe
LocalizationWebsite.Web.Controllers.HomeController será nomeado Controllers.HomeController.fr.resx. Se o
namespace da classe de destino não for o mesmo que o nome do assembly, você precisará do nome completo
do tipo. Por exemplo, no projeto de exemplo, um recurso para o tipo ExtraNamespace.Tools será nomeado
ExtraNamespace.Tools.fr.resx.
No projeto de exemplo, o método ConfigureServices define o ResourcesPath como "Resources", de modo que
o caminho relativo do projeto para o arquivo de recurso em francês do controlador principal seja
Resources/Controllers.HomeController.fr.resx. Como alternativa, você pode usar pastas para organizar arquivos
de recurso. Para o controlador principal, o caminho será Resources/Controllers/HomeController.fr.resx. Se você
não usar a opção ResourcesPath , o arquivo .resx entrará no diretório base do projeto. O arquivo de recurso para
HomeController será nomeado Controllers.HomeController.fr.resx. A opção de usar a convenção de
nomenclatura de ponto ou caminho depende de como você deseja organizar os arquivos de recurso.
NOME DO RECURSO NOMENCLATURA DE PONTO OU CAMINHO
Resources/Controllers.HomeController.fr.resx Ponto
Resources/Controllers/HomeController.fr.resx Caminho
Os arquivos de recurso que usam @inject IViewLocalizer em exibições do Razor seguem um padrão
semelhante. O arquivo de recurso de uma exibição pode ser nomeado usando a nomenclatura de ponto ou de
caminho. Os arquivos de recurso da exibição do Razor simulam o caminho de seu arquivo de exibição
associado. Supondo que definimos o ResourcesPath como "Resources", o arquivo de recurso em francês
associado à exibição Views/Home/About.cshtml pode ser um dos seguintes:
Resources/Views/Home/About.fr.resx
Resources/Views.Home.About.fr.resx
Se você não usar a opção ResourcesPath , o arquivo .resx de uma exibição estará localizado na mesma pasta da
exibição.
RootNamespaceAttribute
O atributo RootNamespace fornece o namespace raiz de um assembly quando o namespace raiz de um
assembly é diferente do nome do assembly.
Se o namespace raiz de um assembly é diferente do nome do assembly:
A localização não funciona por padrão.
A localização falha devido à maneira como os recursos são pesquisados dentro do assembly. RootNamespace
é um valor de tempo de build que não está disponível para o processo em execução.
Se o RootNamespace é diferente de AssemblyName , inclua o seguinte no AssemblyInfo.cs (com valores de
parâmetro substituídos pelos valores reais):
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]

[assembly: RootNamespace("App Root Namespace")]
O código anterior permite a resolução bem-sucedida de arquivos resx.
Comportamento de fallback da cultura

Ao procurar por um recurso, a localização participa do "fallback de cultura". Começando com a cultura
solicitada, se ela não for encontrada, ela será revertida para a cultura pai dessa cultura. Além disso, a
propriedade CultureInfo.Parent representa a cultura pai. Isso normalmente (mas nem sempre) significa a
remoção do significante do ISO. Por exemplo, o dialeto do espanhol falado no México é "es-MX". Ele tem o pai
"es", ou seja, espanhol, não específico de nenhum país.
Imagine que seu site receba uma solicitação de um recurso “Boas-vindas" usando a cultura"fr-CA". O sistema
de localização procura os seguintes recursos, em ordem, e seleciona a primeira correspondência:
Welcome.fr-CA.resx
Welcome.fr.resx
Welcome.resx (se o NeutralResourcesLanguage for "fr-CA")
Por exemplo, se você remover o designador de cultura ".fr" e tiver a cultura definida como francês, o arquivo de
recurso padrão será lido e as cadeias de caracteres serão localizadas. O Gerenciador de Recursos designa um
padrão ou um recurso de fallback para quando nenhuma opção atende à cultura solicitada. Se você deseja
apenas retornar a chave quando um recurso está ausente para a cultura solicitada, não deve ter um arquivo de
recurso padrão.
Gerar arquivos de recurso com o Visual Studio
Se você criar um arquivo de recurso no Visual Studio sem uma cultura no nome do arquivo (por exemplo,
Welcome.resx), o Visual Studio criará uma classe do C# com uma propriedade para cada cadeia de caracteres.
Geralmente isso não é o desejado com o ASP.NET Core. Normalmente você não tem um arquivo de recurso
.resx padrão (um arquivo .resx sem o nome de cultura). Sugerimos que você crie o arquivo .resx com um nome
de cultura (por exemplo Welcome.fr.resx). Quando você criar um arquivo .resx com um nome de cultura, o
Visual Studio não gerará o arquivo de classe. A nossa previsão é que muitos desenvolvedores não criarão um
arquivo de recurso de idioma padrão.
Adicionar outras culturas
Cada combinação de idioma e cultura (que não seja o idioma padrão) exige um arquivo de recurso exclusivo.
Crie arquivos de recurso para diferentes culturas e localidades criando novos arquivos de recurso, nos quais os
códigos ISO e de idioma fazem parte do nome do arquivo (por exemplo, en-us, fr-ca e en-gb). Esses códigos
ISO são colocados entre o nome do arquivo e a extensão de arquivo .resx, como em Welcome.es-MX.resx
(espanhol/México).
Implementar uma estratégia para selecionar o idioma e a cultura para

cada solicitação
Configurar a localização
A localização é configurada no método Startup.ConfigureServices :
services.AddLocalization(options => options.ResourcesPath = "Resources");
services.AddMvc()
.AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix)
.AddDataAnnotationsLocalization();
AddLocalizationAdiciona os serviços de localização ao contêiner de serviços. O código acima também

define o caminho de recursos como "Resources".
AddViewLocalization Adiciona suporte para os arquivos de exibição localizados. Nesta amostra, a
localização de exibição se baseia no sufixo do arquivo de exibição. Por exemplo, "fr" no arquivo
Index.fr.cshtml.
AddDataAnnotationsLocalization Adiciona suporte para as mensagens de validação DataAnnotations
localizadas por meio de abstrações IStringLocalizer .
Middleware de localização
A cultura atual em uma solicitação é definida no Middleware de localização. O middleware de localização é
habilitado no método Startup.Configure . O middleware de localização precisa ser configurado antes de
qualquer middleware que possa verificar a cultura de solicitação (por exemplo, app.UseMvcWithDefaultRoute() ).
{
new CultureInfo("fr"),
};
app.UseRequestLocalization(new RequestLocalizationOptions
{
DefaultRequestCulture = new RequestCulture("en-US"),
// Formatting numbers, dates, etc.
SupportedCultures = supportedCultures,
// UI strings that we have localized.
SupportedUICultures = supportedCultures
});
// To configure external authentication,
// see: http://go.microsoft.com/fwlink/?LinkID=532715
UseRequestLocalization inicializa um objeto RequestLocalizationOptions . Em cada solicitação, a lista de

RequestCultureProvider em RequestLocalizationOptions é enumerada e o primeiro provedor que pode
determinar com êxito a cultura de solicitação é usado. Os provedores padrão são obtidos da classe
RequestLocalizationOptions :
1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider
A lista padrão é apresentada do mais específico ao menos específico. Mais adiante neste artigo, veremos como
você pode alterar a ordem e até mesmo adicionar um provedor de cultura personalizado. Se nenhum dos
provedores pode determinar a cultura de solicitação, o DefaultRequestCulture é usado.
QueryStringRequestCultureProvider
Alguns aplicativos usarão uma cadeia de caracteres de consulta para definir a cultura e a cultura da interface do
usuário. Para aplicativos que usam a abordagem do cabeçalho Accept-Language ou do cookie, a adição de uma
cadeia de caracteres de consulta à URL é útil para depurar e testar o código. Por padrão, o
QueryStringRequestCultureProvider é registrado como o primeiro provedor de localização na lista
RequestCultureProvider . Passe os parâmetros culture e ui-culture da cadeia de caracteres de consulta. O
seguinte exemplo define a cultura específica (idioma e região) como espanhol/México:
http://localhost:5000/?culture=es-MX&ui-culture=es-MX
Se você passar somente uma das duas ( culture ou ui-culture ), o provedor da cadeia de caracteres de
consulta definirá os dois valores usando aquela que foi passada. Por exemplo, a definição apenas da cultura
definirá a Culture e a UICulture :
http://localhost:5000/?culture=es-MX
CookieRequestCultureProvider
Em geral, aplicativos de produção fornecerão um mecanismo para definir a cultura com o cookie de cultura do
ASP.NET Core. Use o método MakeCookieValue para criar um cookie.
O CookieRequestCultureProvider DefaultCookieName retorna o nome padrão do cookie usado para acompanhar
as informações de cultura preferencial do usuário. O nome padrão do cookie é .AspNetCore.Culture .
O formato do cookie é c=%LANGCODE%|uic=%LANGCODE% , em que c é Culture e uic é UICulture , por exemplo:
c=en-UK|uic=en-US
Se você especificar apenas as informações de cultura e a cultura da interface do usuário, a cultura especificada
será usada para as informações de cultura e para a cultura da interface do usuário.
O cabeçalho HTTP Accept-Language
O cabeçalho Accept-Language é configurável na maioria dos navegadores e originalmente foi criado para
especificar o idioma do usuário. Essa configuração indica que o navegador foi definido para enviar ou herdou
do sistema operacional subjacente. O cabeçalho HTTP Accept-Language de uma solicitação do navegador não
é uma maneira infalível de detectar o idioma preferencial do usuário (consulte Definindo preferências de
idioma em um navegador). Um aplicativo de produção deve incluir uma maneira para que um usuário
personalize sua opção de cultura.
Definir o cabeçalho HTTP Accept-Language no IE
1. No ícone de engrenagem, toque em Opções da Internet.
2. Toque em Idiomas.
3. Toque em Definir Preferências de Idioma.

4. Toque em Adicionar um idioma.
5. Adicione o idioma.
6. Toque no idioma e, em seguida, em Mover Para Cima.
Usar um provedor personalizado
Suponha que você deseje permitir que os clientes armazenem seus idiomas e culturas nos bancos de dados.
Você pode escrever um provedor para pesquisar esses valores para o usuário. O seguinte código mostra como
adicionar um provedor personalizado:
private const string enUSCulture = "en-US";
services.Configure<RequestLocalizationOptions>(options =>
{
{
new CultureInfo(enUSCulture),
};
options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);

options.SupportedCultures = supportedCultures;
options.SupportedUICultures = supportedCultures;
options.RequestCultureProviders.Insert(0, new CustomRequestCultureProvider(async context =>

{
// My custom request culture logic
return new ProviderCultureResult("en");
}));
});
Use RequestLocalizationOptions para adicionar ou remover provedores de localização.

Definir a cultura de forma programática
Este projeto de exemplo Localization.StarterWeb no GitHub contém a interface do usuário para definir a
Culture . O arquivo Views/Shared/_SelectLanguagePartial.cshtml permite que você selecione a cultura na lista
de culturas compatíveis:
@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.Extensions.Options

@inject IOptions<RequestLocalizationOptions> LocOptions
@{
var requestCulture = Context.Features.Get<IRequestCultureFeature>();
var cultureItems = LocOptions.Value.SupportedUICultures
.Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
.ToList();
var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}
<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">

<form id="selectLanguage" asp-controller="Home"
asp-action="SetLanguage" asp-route-returnUrl="@returnUrl"
<label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label>
<select name="culture"
onchange="this.form.submit();"
asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
</select>
</form>
</div>
O arquivo Views/Shared/_SelectLanguagePartial.cshtml é adicionado à seção footer do arquivo de layout

para que ele fique disponível para todos os exibições:
<div class="container body-content" style="margin-top:60px">
@RenderBody()
<hr>
<footer>
<div class="row">
<p>© @System.DateTime.Now.Year - Localization</p>
</div>
<div class="col-md-6 text-right">
@await Html.PartialAsync("_SelectLanguagePartial")
</div>
</div>
</footer>
</div>
O método SetLanguage define o cookie de cultura.
[HttpPost]
public IActionResult SetLanguage(string culture, string returnUrl)
{
Response.Cookies.Append(
CookieRequestCultureProvider.DefaultCookieName,
CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) }
);
}
Não é possível conectar o _SelectLanguagePartial.cshtml ao código de exemplo para este projeto. O projeto
Localization.StarterWeb no GitHub contém o código para o fluxo do RequestLocalizationOptions para uma
parcial do Razor por meio do contêiner de Injeção de Dependência.
Termos de globalização e localização

O processo de localização do aplicativo também exige uma compreensão básica dos conjuntos de caracteres
relevantes geralmente usados no desenvolvimento moderno de software e uma compreensão dos problemas
associados a eles. Embora todos os computadores armazenem texto como números (códigos), diferentes
sistemas armazenam o mesmo texto usando números diferentes. O processo de localização se refere à
tradução da interface do usuário do aplicativo para uma cultura/localidade específica.
Possibilidade de localização é um processo intermediário usado para verificar se um aplicativo globalizado está
pronto para localização.
O formato RFC 4646 para o nome de cultura é <languagecode2>-<country/regioncode2> , em que
<languagecode2> é o código de idioma e <country/regioncode2> é o código de subcultura. Por exemplo, es-CL
para Espanhol (Chile), en-US para inglês (Estados Unidos) e en-AU para inglês (Austrália). O RFC 4646 é uma
combinação de um código de cultura de duas letras minúsculas ISO 639 associado a um idioma e um código
de subcultura de duas letras maiúsculas ISO 3166 associado a um país ou uma região. Consulte Nome da
cultura de idioma.
Muitas vezes, internacionalização é abreviada como "I18N". A abreviação usa a primeira e última letras e o
número de letras entre elas e, portanto, 18 significa o número de letras entre o primeiro "I" e o último "N". O
mesmo se aplica a Globalização (G11N ) e Localização (L10N ).
Termos:
Globalização (G11N ): o processo de fazer com que um aplicativo dê suporte a diferentes idiomas e regiões.
Localização (L10N ): o processo de personalizar um aplicativo para determinado idioma e região.
Internacionalização (I18N ): descreve a globalização e a localização.
Cultura: um idioma e, opcionalmente, uma região.
Cultura neutra: uma cultura que tem um idioma especificado, mas não uma região. (por exemplo, "en", "es")
Cultura específica: uma cultura que tem um idioma e uma região especificados. (por exemplo, "en-US", "en-
GB", "es-CL")
Cultura pai: a cultura neutra que contém uma cultura específica. (por exemplo, "en" é a cultura pai de "en-
US" e "en-GB")
Localidade: uma localidade é o mesmo que uma cultura.
Recursos adicionais
O projeto Localization.StarterWeb usado no artigo.
Globalizando e localizando aplicativos do .NET
Recursos em arquivos .resx
Kit de Ferramentas de Aplicativo Multilíngue da Microsoft
Configurar a localização de objeto portátil no
ASP.NET Core
Por Sébastien Ros e Scott Addie

Este artigo explica as etapas para usar arquivos PO (Objeto Portátil) em um aplicativo ASP.NET Core com a
estrutura Orchard Core.
Observação: o Orchard Core não é um produto da Microsoft. Consequentemente, a Microsoft não fornece
suporte para esse recurso.
O que é um arquivo PO?

Os arquivos PO são distribuídos como arquivos de texto que contém cadeias de caracteres traduzidas em
determinado idioma. Algumas vantagens do uso de arquivos PO em vez de arquivos .resx incluem:
Os arquivos PO dão suporte à pluralização, ao contrário dos arquivos .resx.
Os arquivos PO não são compilados como os arquivos .resx. Dessa forma, não são necessárias ferramentas
especializadas nem etapas de build.
Os arquivos PO funcionam bem com ferramentas de colaboração de edição online.
Exemplo
Este é um arquivo PO de exemplo que contém a tradução de duas cadeias de caracteres em francês, incluindo uma
com sua forma plural:
fr.po
#: Services/EmailService.cs:29
msgid "Enter a comma separated list of email addresses."
msgstr "Entrez une liste d'emails séparés par une virgule."
#: Views/Email.cshtml:112
msgid "The email address is \"{0}\"."
msgid_plural "The email addresses are \"{0}\"."
msgstr[0] "L'adresse email est \"{0}\"."
msgstr[1] "Les adresses email sont \"{0}\""
Este exemplo usa a seguinte sintaxe:

#: : um comentário que indica o contexto da cadeia de caracteres a ser traduzida. A mesma cadeia de
caracteres pode ser traduzida de modo diferente, dependendo do local em que ela está sendo usada.
msgid : a cadeia de caracteres não traduzida.
msgstr : a cadeia de caracteres traduzida.
No caso de suporte à pluralização, entradas adicionais podem ser definidas.

msgid_plural : a cadeia de caracteres no plural não traduzida.
msgstr[0] : a cadeia de caracteres traduzida para o caso 0.
msgstr[N] : a cadeia de caracteres traduzida para o caso N.
A especificação de arquivo PO pode ser encontrada aqui.
Configurando o suporte a arquivos PO no ASP.NET Core

Este exemplo se baseia em um aplicativo ASP.NET Core MVC gerado com base em um modelo de projeto do
Visual Studio 2017.
Referenciando o pacote
Adicione uma referência ao pacote NuGet OrchardCore.Localization.Core . Ele está disponível em MyGet na fonte
do pacote a seguir: https://www.myget.org/F/orchardcore-preview/api/v3/index.json
O arquivo .csproj agora contém uma linha semelhante à seguinte (o número de versão pode variar):
<PackageReference Include="OrchardCore.Localization.Core" Version="1.0.0-beta1-3187" />
Registrando o serviço
Adicione os serviços necessários ao método ConfigureServices de Startup.cs:

{
services.AddMvc()
.AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix);
services.AddPortableObjectLocalization();
services.Configure<RequestLocalizationOptions>(options =>
{
var supportedCultures = new List<CultureInfo>
{
new CultureInfo("en"),
new CultureInfo("fr-FR"),
};
options.DefaultRequestCulture = new RequestCulture("en-US");

options.SupportedCultures = supportedCultures;
options.SupportedUICultures = supportedCultures;
});
}
Adicione o middleware necessário ao método Configure de Startup.cs:

{
{
}
else
{
}
app.UseRequestLocalization();
}
Adicione o código a seguir à exibição do Razor de sua escolha. About.cshtml é usado neste exemplo.
<p>@Localizer["Hello world!"]</p>
Uma instância IViewLocalizer é injetada e usada para traduzir o texto “Olá, Mundo!”.
Criando um arquivo PO
Crie um arquivo chamado .po na pasta raiz do aplicativo. Neste exemplo, o nome do arquivo é fr.po porque o
idioma francês é usado:
msgid "Hello world!"

msgstr "Bonjour le monde!"
Esse arquivo armazena a cadeia de caracteres a ser traduzida e a cadeia de caracteres traduzida do francês. As
traduções são revertidas para a cultura pai, se necessário. Neste exemplo, o arquivo fr.po é usado se a cultura
solicitada é fr-FR ou fr-CA .
Testando o aplicativo
Execute o aplicativo e navegue para a URL /Home/About . O texto Olá, Mundo! é exibido.
Navegue para a URL /Home/About?culture=fr-FR . O texto Bonjour le monde! é exibido.
Pluralização
Os arquivos PO dão suporte a formas de pluralização, que são úteis quando a mesma cadeia de caracteres precisa
ser traduzida de modo diferente de acordo com uma cardinalidade. Essa tarefa torna-se complicada pelo fato de
que cada idioma define regras personalizadas para selecionar qual cadeia de caracteres será usada de acordo com
a cardinalidade.
O pacote de Localização do Orchard fornece uma API para invocar essas diferentes formas plurais
automaticamente.
Criando arquivos PO de pluralização
Adicione o seguinte conteúdo ao arquivo fr.po mencionado anteriormente:
msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."
Consulte O que é um arquivo PO? para obter uma explicação do que representa cada entrada neste exemplo.
Adicionando um idioma usando diferentes formas de pluralização
Cadeias de caracteres em inglês e francês foram usadas no exemplo anterior. O inglês e o francês têm apenas duas
formas de pluralização e compartilham as mesmas regras de forma, o que significa que uma cardinalidade de um é
mapeada para a primeira forma plural. Qualquer outra cardinalidade é mapeada para a segunda forma plural.
Nem todos os idiomas compartilham as mesmas regras. Isso é ilustrado com o idioma tcheco, que tem três formas
plurais.
Crie o arquivo cs.po da seguinte maneira e observe como a pluralização precisa de três traduções diferentes:

msgstr "Ahoj světe!!"
msgid "There is one item."

msgid_plural "There are {0} items."
msgstr[0] "Existuje jedna položka."
msgstr[1] "Existují {0} položky."
msgstr[2] "Existuje {0} položek."
Para aceitar localizações para o tcheco, adicione "cs" à lista de culturas com suporte no método
ConfigureServices :
var supportedCultures = new List<CultureInfo>

{
new CultureInfo("en"),
new CultureInfo("fr-FR"),
new CultureInfo("fr"),
new CultureInfo("cs")
};
Edite o arquivo Views/Home/About.cshtml para renderizar cadeias de caracteres localizadas no plural para várias
cardinalidades:
<p>@Localizer.Plural(1, "There is one item.", "There are {0} items.")</p>

Observação: em um cenário do mundo real, uma variável é usada para representar a contagem. Aqui, repetimos o
mesmo código com três valores diferentes para expor um caso muito específico.
Ao mudar as culturas, o seguinte é observado:
Para /Home/About :
There is one item.

There are 2 items.
There are 5 items.
Para /Home/About?culture=fr :
Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.
Para /Home/About?culture=cs :
Existuje jedna položka.

Existují 2 položky.
Existuje 5 položek.
Observe que, para a cultura do tcheco, as três traduções são diferentes. As culturas do francês e do inglês
compartilham a mesma construção para as duas últimas cadeias de caracteres traduzidas.
Tarefas avançadas
Contextualizando cadeias de caracteres
Os aplicativos costumam conter as cadeias de caracteres a serem traduzidas em vários locais. A mesma cadeia de
caracteres pode ter uma tradução diferente em determinados locais em um aplicativo (exibições do Razor ou
arquivos de classe). Um arquivo PO dá suporte à noção de um contexto de arquivo, que pode ser usado para
categorizar a cadeia de caracteres que está sendo representada. Usando um contexto de arquivo, uma cadeia de
caracteres pode ser traduzida de forma diferente, dependendo do contexto de arquivo (ou de sua ausência).
Os serviços de localização de PO usam o nome da classe completa ou da exibição que é usado ao traduzir uma
cadeia de caracteres. Isso é feito definindo o valor na entrada msgctxt .
Considere uma adição mínima ao exemplo anterior de fr.po. Uma exibição do Razor localizada em
Views/Home/About.cshtml pode ser definida com o contexto de arquivo definindo o valor da entrada msgctxt
reservada:
msgctxt "Views.Home.About"
Com o msgctxt definido assim, a tradução de texto ocorre durante a navegação para /Home/About?culture=fr-FR .A
tradução não ocorre durante a navegação para /Home/Contact?culture=fr-FR .
Quando não é encontrada a correspondência de nenhuma entrada específica com um contexto de arquivo
fornecido, o mecanismo de fallback do Orchard Core procura um arquivo PO apropriado sem contexto. Supondo
que não haja nenhum contexto de arquivo específico definido para Views/Home/Contact.cshtml, a navegação para
/Home/Contact?culture=fr-FR carrega um arquivo PO, como:

Alterando o local dos arquivos PO

A localização padrão dos arquivos PO pode ser alterada em ConfigureServices :
services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");
Neste exemplo, os arquivos PO são carregados da pasta Localization.

Implementando uma lógica personalizada para encontrar arquivos de localização
Quando uma lógica mais complexa é necessária para localizar arquivos PO, a interface
OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider pode ser implementada e registrada
como um serviço. Isso é útil quando arquivos PO podem ser armazenados em locais variáveis ou quando os
arquivos precisam ser encontrados em uma hierarquia de pastas.
Usando um idioma pluralizado padrão diferente
O pacote inclui um método de extensão Plural específico a duas formas plurais. Para idiomas que exigem mais
formas plurais, crie um método de extensão. Com um método de extensão, você não precisará fornecer nenhum
arquivo de localização para o idioma padrão – as cadeias de caracteres originais já estão disponíveis diretamente
no código.
Use a sobrecarga Plural(int count, string[] pluralForms, params object[] arguments) mais genérica que aceita
uma matriz de cadeia de caracteres de traduções.
Middleware de Reconfiguração de URL no ASP.NET
Core
Por Luke Latham e Mikael Mengistu

A reconfiguração de URL é o ato de modificar URLs de solicitação com base em uma ou mais regras
predefinidas. A reconfiguração de URL cria uma abstração entre locais de recursos e seus endereços, de forma
que os locais e endereços não estejam totalmente vinculados. Há vários cenários em que a reconfiguração de
URL é útil:
Mover ou substituir recursos de servidor temporária ou permanentemente mantendo localizadores estáveis
para esses recursos.
Dividir o processamento de solicitação entre diferentes aplicativos ou áreas de um aplicativo.
Remover, adicionar ou reorganizar segmentos de URL em solicitações de entrada.
Otimizar URLs públicas para SEO (Otimização do Mecanismo de Pesquisa).
Permitir o uso de URLs públicas amigáveis para ajudar as pessoas a prever o conteúdo que encontrarão
seguindo um link.
Redirecionar solicitações não seguras para pontos de extremidade seguros.
Impedir hotlinking de imagem.
Defina regras para alterar a URL de várias maneiras, incluindo Regex, regras do módulo mod_rewrite do Apache,
regras do Módulo de Reconfiguração do IIS e uso de uma lógica de regra personalizada. Este documento
apresenta a reconfiguração de URL com instruções sobre como usar o Middleware de Reconfiguração de URL
em aplicativos ASP.NET Core.
NOTE
A reconfiguração de URL pode reduzir o desempenho de um aplicativo. Sempre que possível, você deve limitar o número e
a complexidade de regras.
Redirecionamento e reconfiguração de URL

A diferença entre os termos redirecionamento de URL e reconfiguração de URL pode parecer sutil no primeiro
momento, mas tem implicações importantes no fornecimento de recursos aos clientes. O Middleware de
Reconfiguração de URL do ASP.NET Core pode atender às necessidades de ambos.
Um redirecionamento de URL é uma operação do lado do cliente, na qual o cliente é instruído a acessar um
recurso em outro endereço. Isso exige a ida e vinda para o servidor. A URL de redirecionamento retornada para
o cliente é exibida na barra de endereços do navegador quando o cliente faz uma nova solicitação para o recurso.
Se /resource é redirecionado para /different-resource , o cliente solicita /resource . O servidor responde que
o cliente deve obter o recurso em /different-resource com um código de status que indica que o
redirecionamento é temporário ou permanente. O cliente executa uma nova solicitação para o recurso na URL
de redirecionamento.
Ao redirecionar solicitações para uma URL diferente, indique se o redirecionamento é permanente ou
temporário. O código de status 301 (Movido Permanentemente) é usado quando o recurso tem uma nova URL
permanente e você deseja instruir o cliente que todas as solicitações futuras para o recurso devem usar a nova
URL. O cliente pode armazenar a resposta em cache quando um código de status 301 é recebido. O código de
status 302 (Encontrado) é usado quando o redirecionamento é temporário ou geralmente sujeito à alteração,
como aquele em que o cliente não deve armazenar e reutilizar a URL de redirecionamento no futuro. Para obter
mais informações, consulte RFC 2616: definições de código de status.
Uma reconfiguração de URL é uma operação do servidor usada para fornecer um recurso de outro endereço de
recurso. A reconfiguração de uma URL não exige a ida e vinda para o servidor. A URL reconfigurada não é
retornada para o cliente e não será exibida na barra de endereços do navegador. Quando /resource é
reconfigurado para /different-resource , o cliente solicita /resource e o servidor busca internamente o recurso
em /different-resource . Embora o cliente possa ter a capacidade de recuperar o recurso na URL reconfigurada,
o cliente não será informado de que o recurso existe na URL reconfigurada quando fizer a solicitação e receber a
resposta.
Aplicativo de exemplo de reconfiguração de URL

Explore os recursos do Middleware de Reconfiguração de URL com o aplicativo de exemplo de reconfiguração
de URL. O aplicativo aplica as regras de reconfiguração e redirecionamento e mostra a URL reconfigurada ou
redirecionada.
Quando usar o Middleware de Reconfiguração de URL

Use o Middleware de Reconfiguração de URL quando não puder usar o módulo de Reconfiguração de URL com
o IIS no Windows Server, o módulo mod_rewrite do Apache no Apache Server, a reconfiguração de URL no
Nginx ou quando o aplicativo estiver hospedado no servidor HTTP.sys (anteriormente chamado WebListener).
As principais razões para o uso das tecnologias de reconfiguração de URL baseadas em servidor no IIS, Apache
ou Nginx são que o middleware não dá suporte aos recursos completos desses módulos e o desempenho do
middleware provavelmente não corresponderá ao desempenho dos módulos. No entanto, há alguns recursos
dos módulos de servidor que não funcionam com projetos do ASP.NET Core, como as restrições IsFile e
IsDirectory do módulo de Reconfiguração de IIS. Nesses cenários, use o middleware.
Pacote
Para incluir o middleware em seu projeto, adicione uma referência ao pacote Microsoft.AspNetCore.Rewrite . Esse
recurso está disponível para aplicativos direcionados ao ASP.NET Core 1.1 ou posterior.
Extensão e opções
Estabeleça as regras de reconfiguração e redirecionamento de URL criando uma instância da classe
RewriteOptions com métodos de extensão para cada uma das regras. Encadeie várias regras na ordem em que
deseja que sejam processadas. As RewriteOptions são passadas para o Middleware de Reconfiguração de URL,
conforme ele é adicionado ao pipeline de solicitação com app.UseRewriter(options); .

{
using (StreamReader apacheModRewriteStreamReader =
File.OpenText("ApacheModRewrite.txt"))
using (StreamReader iisUrlRewriteStreamReader =
File.OpenText("IISUrlRewrite.xml"))
{
.AddRedirect("redirect-rule/(.*)", "redirected/$1")
.AddRewrite(@"^rewrite-rule/(\d+)/(\d+)", "rewritten?var1=$1&var2=$2",
skipRemainingRules: true)
.AddApacheModRewrite(apacheModRewriteStreamReader)
.AddIISUrlRewrite(iisUrlRewriteStreamReader)
.Add(MethodRules.RedirectXMLRequests)
.Add(new RedirectImageRequests(".png", "/png-images"))
.Add(new RedirectImageRequests(".jpg", "/jpg-images"));
}
app.Run(context => context.Response.WriteAsync(

$"Rewritten or Redirected Url: " +
$"{context.Request.Path + context.Request.QueryString}"));
}

{
.AddApacheModRewrite(env.ContentRootFileProvider, "ApacheModRewrite.txt")
.AddIISUrlRewrite(env.ContentRootFileProvider, "IISUrlRewrite.xml")
.Add(RedirectXMLRequests)
}
Redirecionar não www para www

Três opções permitem que o aplicativo redirecione solicitações não www para www :
AddRedirectToWwwPermanent(RewriteOptions) – Redireciona permanentemente a solicitação para o
subdomínio www se a solicitação é não www . Redireciona com um código de status
Status308PermanentRedirect.
AddRedirectToWww (RewriteOptions) – Redireciona a solicitação para o subdomínio www se a solicitação de
entrada é não www . Redireciona com um código de status Status307TemporaryRedirect.
AddRedirectToWww (RewriteOptions, Int32) – Redireciona a solicitação para o subdomínio www se a
solicitação de entrada é não www . Permite que você forneça o código de status para a resposta. Use os
campos da classe StatusCodes para atribuições para AddRedirectToWww .
Redirecionamento de URL
Use AddRedirect para redirecionar as solicitações. O primeiro parâmetro contém o regex para correspondência
no caminho da URL de entrada. O segundo parâmetro é a cadeia de caracteres de substituição. O terceiro
parâmetro, se presente, especifica o código de status. Se você não especificar o código de status, ele usará como
padrão 302 (Encontrado), que indica que o recurso foi movido temporariamente ou substituído.

{
{
}

}

{
.AddRedirect("redirect-rule/(.*)", "redirected/$1");
}
Em um navegador com as ferramentas para desenvolvedores habilitadas, faça uma solicitação para o aplicativo
de exemplo com o caminho /redirect-rule/1234/5678 . O regex corresponde ao caminho de solicitação em
redirect-rule/(.*) e o caminho é substituído por /redirected/1234/5678 . A URL de redirecionamento é
enviada novamente ao cliente com um código de status 302 (Encontrado). O navegador faz uma nova solicitação
na URL de redirecionamento, que é exibida na barra de endereços do navegador. Como nenhuma regra no
aplicativo de exemplo corresponde à URL de redirecionamento, a segunda solicitação recebe uma resposta 200
(OK) do aplicativo e o corpo da resposta mostra a URL de redirecionamento. Uma ida e vinda é feita para o
servidor quando uma URL é redirecionada.
WARNING
Tenha cuidado ao estabelecer as regras de redirecionamento. As regras de redirecionamento são avaliadas em cada
solicitação para o aplicativo, incluindo após um redirecionamento. É fácil criar acidentalmente um loop de
redirecionamentos infinitos.
Solicitação original: /redirect-rule/1234/5678

A parte da expressão contida nos parênteses é chamada um grupo de captura. O ponto ( . ) da expressão
significa corresponder a qualquer caractere. O asterisco ( * ) indica corresponder ao caractere zero precedente
ou mais vezes. Portanto, os dois últimos segmentos de caminho da URL, 1234/5678 , são capturados pelo grupo
de captura (.*) . Qualquer valor que você fornecer na URL de solicitação após redirect-rule/ é capturado por
esse único grupo de captura.
Na cadeia de caracteres de substituição, os grupos capturados são injetados na cadeia de caracteres com o cifrão
( $ ) seguido do número de sequência da captura. O primeiro valor de grupo de captura é obtido com $1 , o
segundo com $2 e eles continuam em sequência para os grupos de captura no regex. Há apenas um grupo
capturado no regex da regra de redirecionamento no aplicativo de exemplo, para que haja apenas um grupo
injetado na cadeia de caracteres de substituição, que é $1 . Quando a regra é aplicada, a URL se torna
/redirected/1234/5678 .
Redirecionamento de URL para um ponto de extremidade seguro

Use AddRedirectToHttps para redirecionar solicitações HTTP para o mesmo host e caminho usando HTTPS (
https:// ). Se o código de status não for fornecido, o middleware usará como padrão 302 ( Encontrado). Se a
porta não for fornecida, o middleware usará null como padrão, o que significa que o protocolo é alterado para
https:// e o cliente acessa o recurso na porta 443. O exemplo mostra como definir o código de status como
301 (Movido Permanentemente) e alterar a porta para 5001.

{
.AddRedirectToHttps(301, 5001);
}
Use AddRedirectToHttpsPermanent para redirecionar solicitações não seguras para o mesmo host e caminho com
o protocolo HTTPS seguro ( https:// na porta 443). O middleware define o código de status como 301
(Movido Permanentemente).

{
.AddRedirectToHttpsPermanent();
}
NOTE
Ao redirecionar para HTTPS sem a necessidade de regras de redirecionamento adicionais, é recomendável usar Middleware
de Redirecionamento HTTPS. Para obter mais informações, veja o tópico Impor HTTPS.
O aplicativo de exemplo pode demonstrar como usar AddRedirectToHttps ou AddRedirectToHttpsPermanent .

Adicione o método de extensão às RewriteOptions . Faça uma solicitação não segura para o aplicativo em
qualquer URL. Ignore o aviso de segurança do navegador de que o certificado autoassinado não é confiável ou
crie uma exceção para confiar no certificado.
Solicitação original usando AddRedirectToHttps(301, 5001) : http://localhost:5000/secure
Solicitação original usando AddRedirectToHttpsPermanent : http://localhost:5000/secure
Reconfiguração de URL
Use AddRewrite para criar uma regra para a reconfiguração de URLs. O primeiro parâmetro contém o regex
para correspondência no caminho da URL de entrada. O segundo parâmetro é a cadeia de caracteres de
substituição. O terceiro parâmetro, skipRemainingRules: {true|false} , indica para o middleware se ele deve ou
não ignorar regras de reconfiguração adicionais se a regra atual é aplicada.
{
{
}

}

{
skipRemainingRules: true);
}
Solicitação original: /rewrite-rule/1234/5678
A primeira coisa que é observada no regex é o acento circunflexo ( ^ ) no início da expressão. Isso significa que a
correspondência começa no início do caminho da URL.
No exemplo anterior com a regra de redirecionamento, redirect-rule/(.*) , não há nenhum acento circunflexo
no início do regex; portanto, qualquer caractere pode preceder redirect-rule/ no caminho para uma
correspondência bem-sucedida.
CAMINHO CORRESPONDER A
/redirect-rule/1234/5678 Sim
/my-cool-redirect-rule/1234/5678 Sim
/anotherredirect-rule/1234/5678 Sim
A regra de reconfiguração, ^rewrite-rule/(\d+)/(\d+) , corresponde apenas a caminhos se eles são iniciados

com rewrite-rule/ . Observe a diferença na correspondência entre a regra de reconfiguração abaixo e a regra de
redirecionamento acima.
/rewrite-rule/1234/5678 Sim
/my-cool-rewrite-rule/1234/5678 Não
/anotherrewrite-rule/1234/5678 Não
Após a parte ^rewrite-rule/ da expressão, há dois grupos de captura, (\d+)/(\d+) . O \d significa

corresponder a um dígito (número ). O sinal de adição ( + ) significa corresponder a um ou mais caracteres
anteriores. Portanto, a URL precisa conter um número seguido de uma barra "/" seguida de outro número. Esses
grupos de captura são injetados na URL reconfigurada como $1 e $2 . A cadeia de caracteres de substituição
da regra de reconfiguração coloca os grupos capturados na cadeia de consulta. O caminho solicitado de
/rewrite-rule/1234/5678 foi reconfigurado para obter o recurso em /rewritten?var1=1234&var2=5678 . Se uma
cadeia de consulta estiver presente na solicitação original, ela será preservada quando a URL for reconfigurada.
Não há nenhuma ida e vinda para o servidor para obtenção do recurso. Se o recurso existir, ele será buscado e
retornado ao cliente com um código de status 200 (OK). Como o cliente não é redirecionado, a URL na barra de
endereços do navegador não é alterada. Quanto ao cliente, a operação de reconfiguração de URL nunca ocorreu.
NOTE
Use skipRemainingRules: true sempre que possível, porque as regras de correspondência são um processo caro e
reduzem o tempo de resposta do aplicativo. Para a resposta mais rápida do aplicativo:
Ordene as regras de reconfiguração da regra com correspondência mais frequente para a regra com correspondência
menos frequente.
Ignore o processamento das regras restantes quando ocorrer uma correspondência e nenhum processamento de regra
adicional for necessário.
mod_rewrite do Apache
Aplique as regras do mod_rewrite do Apache com AddApacheModRewrite . Verifique se o arquivo de regras foi
implantado com o aplicativo. Para obter mais informações e exemplos de regras de mod_rewrite, consulte
mod_rewrite do Apache.
Um StreamReader é usado para ler as regras do arquivo de regras ApacheModRewrite.txt.
{
{
}

}
O primeiro parâmetro usa um IFileProvider , que é fornecido por meio da Injeção de Dependência. O
IHostingEnvironment é injetado para fornecer o ContentRootFileProvider . O segundo parâmetro é o caminho
para o arquivo de regras, que é ApacheModRewrite.txt no aplicativo de exemplo.

{
.AddApacheModRewrite(env.ContentRootFileProvider, "ApacheModRewrite.txt");
}
O aplicativo de exemplo redireciona solicitações de /apache-mod-rules-redirect/(.\*) para /redirected?id=$1 .

O código de status da resposta é 302 (Encontrado).
# Rewrite path with additional sub directory

RewriteRule ^/apache-mod-rules-redirect/(.*) /redirected?id=$1 [L,R=302]
Solicitação original: /apache-mod-rules-redirect/1234
O middleware dá suporte às seguintes variáveis de servidor do mod_rewrite do Apache:

CONN_REMOTE_ADDR
HTTP_ACCEPT
HTTP_CONNECTION
HTTP_COOKIE
HTTP_FORWARDED
HTTP_HOST
HTTP_REFERER
HTTP_USER_AGENT
HTTPS
IPV6
QUERY_STRING
REMOTE_ADDR
REMOTE_PORT
REQUEST_FILENAME
REQUEST_METHOD
REQUEST_SCHEME
REQUEST_URI
SCRIPT_FILENAME
SERVER_ADDR
SERVER_PORT
SERVER_PROTOCOL
TIME
TIME_DAY
TIME_HOUR
TIME_MIN
TIME_MON
TIME_SEC
TIME_WDAY
TIME_YEAR
Regras do Módulo de Reconfiguração de URL do IIS
Para usar regras que se aplicam ao Módulo de Reconfiguração de URL do IIS, use AddIISUrlRewrite . Verifique
se o arquivo de regras foi implantado com o aplicativo. Não instrua o middleware a usar o arquivo web.config
quando ele estiver em execução no IIS do Windows Server. Com o IIS, essas regras devem ser armazenadas
fora do web.config para evitar conflitos com o módulo de Reconfiguração do IIS. Para obter mais informações e
exemplos de regras do Módulo de Reconfiguração de URL do IIS, consulte Usando o Módulo de Reconfiguração
de URL 2.0 e Referência de configuração do Módulo de Reconfiguração de URL.
Um StreamReader é usado para ler as regras do arquivo de regras IISUrlRewrite.xml.
{
{
}

}
O primeiro parâmetro usa um IFileProvider , enquanto o segundo é o caminho para o arquivo de regras XML,
que é IISUrlRewrite.xml no aplicativo de exemplo.

{
.AddIISUrlRewrite(env.ContentRootFileProvider, "IISUrlRewrite.xml");
}
O aplicativo de exemplo reconfigura as solicitações de /iis-rules-rewrite/(.*) para /rewritten?id=$1 .A

resposta é enviada ao cliente com um código de status 200 (OK).
<rewrite>
<rules>
<rule name="Rewrite segment to id querystring" stopProcessing="true">
<match url="îis-rules-rewrite/(.*)$" />
<action type="Rewrite" url="rewritten?id={R:1}" appendQueryString="false"/>
</rule>
</rules>
</rewrite>
Solicitação original: /iis-rules-rewrite/1234

Caso você tenha um Módulo de Reconfiguração do IIS ativo com regras no nível do servidor configuradas que
poderiam afetar o aplicativo de maneiras indesejadas, desabilite o Módulo de Reconfiguração do IIS em um
aplicativo. Para obter mais informações, consulte Desabilitando módulos do IIS.
Recursos sem suporte
O middleware liberado com o ASP.NET Core 2.x não dá suporte aos seguintes recursos do Módulo de
Reconfiguração de URL do IIS:
Regras de saída
Variáveis de servidor personalizadas
Curingas
LogRewrittenUrl
O middleware liberado com o ASP.NET Core 1.x não dá suporte aos seguintes recursos do Módulo de
Reconfiguração de URL do IIS:
Regras globais
Regras de saída
Mapas de Reconfiguração
Ação de CustomResponse
Variáveis de servidor personalizadas
Curingas
Action:CustomResponse
LogRewrittenUrl
Variáveis de servidor compatíveis
O middleware dá suporte às seguintes variáveis de servidor do Módulo de Reconfiguração de URL do IIS:
CONTENT_LENGTH
CONTENT_TYPE
HTTP_ACCEPT
HTTP_CONNECTION
HTTP_COOKIE
HTTP_HOST
HTTP_REFERER
HTTP_URL
HTTP_USER_AGENT
HTTPS
LOCAL_ADDR
QUERY_STRING
REMOTE_ADDR
REMOTE_PORT
REQUEST_FILENAME
REQUEST_URI
NOTE
Também obtenha um IFileProvider por meio de um PhysicalFileProvider . Essa abordagem pode fornecer maior
flexibilidade para o local dos arquivos de regras de reconfiguração. Verifique se os arquivos de regras de reconfiguração são
implantados no servidor no caminho fornecido.
PhysicalFileProvider fileProvider = new PhysicalFileProvider(Directory.GetCurrentDirectory());
Regra baseada em método

Use Add(Action<RewriteContext> applyRule) para implementar sua própria lógica de regra em um método. O
RewriteContext expõe o HttpContext para uso no método. O RewriteContext.Result determina como o
processamento de pipeline adicional é manipulado.
REWRITECONTEXT.RESULT AÇÃO
RuleResult.ContinueRules (padrão) Continuar aplicando regras
RuleResult.EndResponse Parar de aplicar regras e enviar a resposta
RuleResult.SkipRemainingRules Parar de aplicar regras e enviar o contexto para o próximo

middleware

{
{
}

}
{
.Add(RedirectXMLRequests);
}
O aplicativo de exemplo demonstra um método que redireciona as solicitações para caminhos que terminam
com .xml. Se você faz uma solicitação para /file.xml , ela é redirecionada para /xmlfiles/file.xml . O código de
status é definido como 301 (Movido Permanentemente). Para um redirecionamento, é necessário definir
explicitamente o código de status da resposta; caso contrário, será retornado um código de status 200 (OK) e o
redirecionamento não ocorrerá no cliente.
public static void RedirectXMLRequests(RewriteContext context)

{
var request = context.HttpContext.Request;
// Because we're redirecting back to the same app, stop

// processing if the request has already been redirected
if (request.Path.StartsWithSegments(new PathString("/xmlfiles")))
{
return;
}
if (request.Path.Value.EndsWith(".xml", StringComparison.OrdinalIgnoreCase))
{
response.StatusCode = StatusCodes.Status301MovedPermanently;
context.Result = RuleResult.EndResponse;
response.Headers[HeaderNames.Location] =
"/xmlfiles" + request.Path + request.QueryString;
}
}
Solicitação original: /file.xml
Regra baseada em IRule

Use Add(IRule) para encapsular sua própria lógica de regra em uma classe que implementa a interface IRule .
O uso de uma IRule fornece maior flexibilidade em relação ao uso da abordagem de regra baseada em
método. A classe de implementação pode incluir um construtor, no qual você pode passar parâmetros para o
método ApplyRule .
{
{
}

}

{
}
Os valores dos parâmetros no aplicativo de exemplo para a extension e o newPath são verificados para atender
a várias condições. A extension precisa conter um valor que precisa ser .png, .jpg ou .gif. Se o newPath não é
válido, uma ArgumentException é gerada. Se você faz uma solicitação para image.png, ela é redirecionada para
/png-images/image.png . Se você faz uma solicitação para image.jpg, ela é redirecionada para
/jpg-images/image.jpg . O código de status é definido como 301 ( Movido Permanentemente) e o
context.Result é definida para parar o processamento de regras e enviar a resposta.
public class RedirectImageRequests : IRule
{
private readonly string _extension;
private readonly PathString _newPath;
public RedirectImageRequests(string extension, string newPath)

{
if (string.IsNullOrEmpty(extension))
{
throw new ArgumentException(nameof(extension));
}
if (!Regex.IsMatch(extension, @"^\.(png|jpg|gif)$"))
{
throw new ArgumentException("Invalid extension", nameof(extension));
}
if (!Regex.IsMatch(newPath, @"(/[A-Za-z0-9]+)+?"))
{
throw new ArgumentException("Invalid path", nameof(newPath));
}
_extension = extension;
_newPath = new PathString(newPath);
}
public void ApplyRule(RewriteContext context)

{
var request = context.HttpContext.Request;
// Because we're redirecting back to the same app, stop

// processing if the request has already been redirected
if (request.Path.StartsWithSegments(new PathString(_newPath)))
{
return;
}
if (request.Path.Value.EndsWith(_extension, StringComparison.OrdinalIgnoreCase))
{
response.StatusCode = StatusCodes.Status301MovedPermanently;
context.Result = RuleResult.EndResponse;
response.Headers[HeaderNames.Location] =
_newPath + request.Path + request.QueryString;
}
}
}
Solicitação original: /image.png
Solicitação original: /image.jpg

Exemplos do regex
CADEIA DE CARACTERES DE
CADEIA DE CARACTERES DO REGEX & SUBSTITUIÇÃO &
GOAL EXEMPLO DE CORRESPONDÊNCIA EXEMPLO DE SAÍDA
Reconfigurar o caminho na cadeia de ^path/(.*)/(.*) path?var1=$1&var2=$2

consulta /path/abc/123 /path?var1=abc&var2=123
Barra "/" à direita da faixa (.*)/$ $1

/path/ /path
Impor barra "/" à direita (.*[^/])$ $1/

/path /path/
Evitar a reconfiguração de solicitações ^(.*)(?<!\.axd)$ ou rewritten/$1

específicas ^(?!.*\.axd$)(.*)$ /rewritten/resource.htm
Sim: /resource.htm /resource.axd
Não: /resource.axd
Reorganizar segmentos de URL path/(.*)/(.*)/(.*) path/$3/$2/$1

path/1/2/3 path/3/2/1
Substituir um segmento de URL ^(.*)/segment2/(.*) $1/replaced/$2

/segment1/segment2/segment3 /segment1/replaced/segment3
Recursos adicionais
Inicialização de aplicativos
Middleware
Expressões regulares no .NET
Linguagem de expressão regular – referência rápida
mod_rewrite do Apache
Usando o Módulo de Reconfiguração de URL 2.0 (para IIS )
Referência de configuração do Módulo de Reconfiguração de URL
Fórum do Módulo de Reconfiguração de URL do IIS
Manter uma estrutura de URL simples
10 dicas e truques de reconfiguração de URL
Inserir ou não inserir uma barra "/"
Provedores de arquivos no ASP.NET Core

O ASP.NET Core abstrai o acesso ao sistema de arquivos por meio do uso de provedores de arquivos. Os
provedores de arquivos são usados em toda a estrutura do ASP.NET Core:
IHostingEnvironment expõe o conteúdo raiz do aplicativo e a raiz da Web como tipos IFileProvider .
Middleware de Arquivos Estáticos usa provedores de arquivos para localizar arquivos estáticos.
Razor usa provedores de arquivos para localizar páginas e modos de exibição.
As ferramentas do .NET Core usam provedores de arquivos e padrões glob para especificar quais arquivos
devem ser publicados.
Interfaces de provedor de arquivo

A interface principal é IFileProvider. IFileProvider expõe métodos para:
Obter informações sobre o arquivo (IFileInfo).
Obter informações sobre o diretório (IDirectoryContents).
Configurar notificações de alteração (usando um IChangeToken).
IFileInfo fornece métodos e propriedades para trabalhar com arquivos:
Exists
IsDirectory
Nome
Length (em bytes)
Data de LastModified
Você pode ler o arquivo usando o método IFileInfo.CreateReadStream.
O aplicativo de amostra demonstra como configurar um provedor de arquivos em Startup.ConfigureServices para
uso em todo o aplicativo por meio da injeção de dependência.
Implementações do provedor de arquivos

Três implementações de IFileProvider estão disponíveis.
IMPLEMENTAÇÃO DESCRIÇÃO
PhysicalFileProvider O provedor físico é usado para acessar os arquivos físicos do

sistema.
ManifestEmbeddedFileProvider O provedor inserido de manifesto é usado para acessar

arquivos incorporados em assemblies.
CompositeFileProvider O provedor composto é usado para fornecer acesso

combinado a arquivos e diretórios de um ou mais provedores.
IMPLEMENTAÇÃO DESCRIÇÃO
PhysicalFileProvider O provedor físico é usado para acessar os arquivos físicos do

sistema.
EmbeddedFileProvider O provedor inserido é usado para acessar arquivos inseridos

em assemblies.
CompositeFileProvider O provedor composto é usado para fornecer acesso

combinado a arquivos e diretórios de um ou mais provedores.
PhysicalFileProvider
O PhysicalFileProvider fornece acesso ao sistema de arquivos físico. O PhysicalFileProvider usa o tipo
System.IO.File (para o provedor físico) e delimita todos os caminhos para um diretório e seus filhos. Esse escopo
impede o acesso ao sistema de arquivos fora do diretório especificado e seus filhos. Ao criar uma instância para
esse provedor, um caminho de diretório é necessário e serve como o caminho base para todas as solicitações feitas
usando o provedor. Você pode criar uma instância de um provedor PhysicalFileProvider diretamente, ou pode
solicitar um IFileProvider em um construtor por meio de uma injeção de dependência.
Tipos estáticos
O código a seguir mostra como criar um PhysicalFileProvider e usá-lo para obter o conteúdo do diretório e as
informações do arquivo:
var provider = new PhysicalFileProvider(applicationRoot);

var contents = provider.GetDirectoryContents(string.Empty);
var fileInfo = provider.GetFileInfo("wwwroot/js/site.js");
Tipos no exemplo anterior:

provider é um IFileProvider .
contents é um IDirectoryContents .
fileInfo é um IFileInfo .
O provedor de arquivos pode ser usado para percorrer o diretório especificado por applicationRoot ou chamar
GetFileInfo para obter as informações de um arquivo. O provedor de arquivos não tem acesso fora do diretório
applicationRoot .
O aplicativo de amostra cria o provedor na classe Startup.ConfigureServices do aplicativo usando

IHostingEnvironment.ContentRootFileProvider:
var physicalProvider = _env.ContentRootFileProvider;
Obter tipos de provedor de arquivos com injeção de dependência

Injete o provedor em qualquer construtor de classe e atribua-o a um campo local. Use o campo em todos os
métodos da classe para acessar arquivos.
No aplicativo de amostra, a classe IndexModel recebe uma instância IFileProvider para obter o conteúdo do
diretório para o caminho base do aplicativo.
Pages/Index.cshtml.cs:
{
private readonly IFileProvider _fileProvider;
public IndexModel(IFileProvider fileProvider)

{
_fileProvider = fileProvider;
}
public IDirectoryContents DirectoryContents { get; private set; }
public void OnGet()

{
DirectoryContents = _fileProvider.GetDirectoryContents(string.Empty);
}
}
Os IDirectoryContents são iterados na página.

Pages/Index.cshtml:
<ul>
@foreach (var item in Model.DirectoryContents)
{
if (item.IsDirectory)
{
<li><strong>@item.Name</strong></li>
}
else
{
<li>@item.Name - @item.Length bytes</li>
}
}
</ul>
No aplicativo de amostra, a classe HomeController recebe uma instância IFileProvider para obter o conteúdo do
diretório para o caminho base do aplicativo.
Controllers/HomeController.cs:

{
public HomeController(IFileProvider fileProvider)

{
_fileProvider = fileProvider;
}

{
var contents = _fileProvider.GetDirectoryContents(string.Empty);
return View(contents);
}
}
Os IDirectoryContents são iterados na exibição.

Views/Home/Index.cshtml:
<ul>
@foreach (IFileInfo item in Model)
{
if (item.IsDirectory)
{
<li><strong>@item.Name</strong></li>
}
else
{
<li>@item.Name - @item.Length bytes</li>
}
}
</ul>
ManifestEmbeddedFileProvider
O ManifestEmbeddedFileProvider é usado para acessar arquivos inseridos em assemblies. O
ManifestEmbeddedFileProvider usa um manifesto compilado no assembly para reconstruir os caminhos originais
dos arquivos inseridos.
NOTE
O ManifestEmbeddedFileProvider está disponível no ASP.NET Core 2.1 ou posterior. Para acessar arquivos inseridos em
assemblies no ASP.NET Core 2.0 ou anterior, confira a versão ASP.NET Core 1.x deste tópico.
Para gerar um manifesto dos arquivos inseridos, defina a propriedade <GenerateEmbeddedFilesManifest> como
true . Especifique os arquivos para inserir com <EmbeddedResource>:
<PropertyGroup>
<GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
<ItemGroup>
<EmbeddedResource Include="Resource.txt" />
</ItemGroup>
</Project>
Use padrões glob para especificar um ou mais arquivos a serem inseridos no assembly.
O aplicativo de amostra cria um ManifestEmbeddedFileProvider e passa o assembly atualmente em execução para
seu construtor.
Startup.cs:
var manifestEmbeddedProvider =
new ManifestEmbeddedFileProvider(Assembly.GetEntryAssembly());
Sobrecargas adicionais permitem:

Especificar um caminho de arquivo relativo.
Delimitar os arquivos segundo a data da última modificação.
Nomear o recurso inserido que contém o manifesto do arquivo inserido.
SOBRECARGA DESCRIÇÃO
ManifestEmbeddedFileProvider(Assembly, String) Aceita um parâmetro de caminho relativo root opcional.

Especifique o root para delimitar as chamadas para
GetDirectoryContents para os recursos no caminho fornecido.
ManifestEmbeddedFileProvider(Assembly, String, Aceita um parâmetro de caminho relativo root opcional e

DateTimeOffset) um parâmetro de data lastModified (DateTimeOffset). A
data de lastModified tem como escopo a data da última
modificação para as instâncias de IFileInfo retornadas pelo
IFileProvider.
ManifestEmbeddedFileProvider(Assembly, String, String, Aceita um caminho relativo root opcional, data de

DateTimeOffset) lastModified e parâmetros manifestName . O
manifestName representa o nome do recurso inserido que
contém o manifesto.
EmbeddedFileProvider
O EmbeddedFileProvider é usado para acessar arquivos inseridos em assemblies. Especifique os arquivos para
inserir na propriedade <EmbeddedResource> no arquivo do projeto:
<ItemGroup>
<EmbeddedResource Include="Resource.txt" />
</ItemGroup>
Use padrões glob para especificar um ou mais arquivos a serem inseridos no assembly.
O aplicativo de amostra cria um EmbeddedFileProvider e passa o assembly atualmente em execução para seu
construtor.
Startup.cs:
var embeddedProvider = new EmbeddedFileProvider(Assembly.GetEntryAssembly());
Recursos inseridos não expõem diretórios. Em vez disso, o caminho para o recurso (por meio de seu namespace) é
inserido no nome de arquivo usando separadores . . No aplicativo de amostra, o baseNamespace é
FileProviderSample. .
O construtor EmbeddedFileProvider(Assembly, String) aceita um parâmetro baseNamespace opcional. Especifique o

namespace de base para delimitar as chamadas para GetDirectoryContents para os recursos no namespace
fornecido.
CompositeFileProvider
O CompositeFileProvider combina instâncias de IFileProvider , expondo uma interface única para trabalhar com
arquivos de vários provedores. Ao criar o CompositeFileProvider , passe uma ou mais instâncias de IFileProvider
para o construtor.
No aplicativo de amostra, um PhysicalFileProvider e um ManifestEmbeddedFileProvider fornecem arquivos para
um CompositeFileProvider registrado no contêiner de serviço do aplicativo:
var physicalProvider = _env.ContentRootFileProvider;
var manifestEmbeddedProvider =
new ManifestEmbeddedFileProvider(Assembly.GetEntryAssembly());
var compositeProvider =
new CompositeFileProvider(physicalProvider, manifestEmbeddedProvider);
services.AddSingleton<IFileProvider>(compositeProvider);
No aplicativo de amostra, um PhysicalFileProvider e um EmbeddedFileProvider fornecem arquivos para um

CompositeFileProvider registrado no contêiner de serviço do aplicativo:
var physicalProvider = _hostingEnvironment.ContentRootFileProvider;

var embeddedProvider = new EmbeddedFileProvider(Assembly.GetEntryAssembly());
var compositeProvider = new CompositeFileProvider(physicalProvider, embeddedProvider);
services.AddSingleton<IFileProvider>(compositeProvider);
Monitorar as alterações
O método IFileProvider.Watch proporciona um cenário para monitorar um ou mais arquivos ou diretórios quanto
a alterações. Watch aceita uma cadeia de caracteres de caminho, que pode usar padrões glob para especificar
vários arquivos. Watch retorna um IChangeToken. O token de alteração expõe:
HasChanged: uma propriedade que pode ser inspecionada para determinar se uma alteração ocorreu.
RegisterChangeCallback: chamado quando são detectadas alterações na cadeia de caracteres do caminho
especificado. Cada token de alteração chama apenas seu retorno de chamada associado em resposta a uma
única alteração. Para permitir o monitoramento constante, use um TaskCompletionSource (mostrado abaixo) ou
recrie instâncias de IChangeToken em resposta a alterações.
No aplicativo de amostra, o aplicativo de console WatchConsole é configurado para exibir uma mensagem sempre
que um arquivo de texto é modificado:
private static PhysicalFileProvider _fileProvider =

new PhysicalFileProvider(Directory.GetCurrentDirectory());

{
Console.WriteLine("Monitoring quotes.txt for changes (Ctrl-c to quit)...");
while (true)
{
MainAsync().GetAwaiter().GetResult();
}
}
private static async Task MainAsync()

{
IChangeToken token = _fileProvider.Watch("quotes.txt");
var tcs = new TaskCompletionSource<object>();
token.RegisterChangeCallback(state =>
((TaskCompletionSource<object>)state).TrySetResult(null), tcs);
await tcs.Task.ConfigureAwait(false);
Console.WriteLine("quotes.txt changed");
}
private static PhysicalFileProvider _fileProvider =
new PhysicalFileProvider(Directory.GetCurrentDirectory());

{
Console.WriteLine("Monitoring quotes.txt for changes (Ctrl-c to quit)...");
while (true)
{
MainAsync().GetAwaiter().GetResult();
}
}
private static async Task MainAsync()

{
IChangeToken token = _fileProvider.Watch("quotes.txt");
var tcs = new TaskCompletionSource<object>();
token.RegisterChangeCallback(state =>
((TaskCompletionSource<object>)state).TrySetResult(null), tcs);
await tcs.Task.ConfigureAwait(false);
Console.WriteLine("quotes.txt changed");
}
Alguns sistemas de arquivos, como contêineres do Docker e compartilhamentos de rede, podem não enviar
notificações de alteração de forma confiável. Defina a variável de ambiente DOTNET_USE_POLLING_FILE_WATCHER como
1 ou true para sondar o sistema de arquivos a cada quatro segundos em relação a alterações.
Padrões glob
Os caminhos do sistema de arquivos usam padrões curinga chamados padrões glob (ou globbing ). Especifique
grupos de arquivos com esses padrões. Os dois caracteres curinga são * e ** :
*
Corresponde a qualquer coisa no nível da pasta atual, qualquer nome de arquivo ou qualquer extensão de arquivo.
As correspondências são terminadas pelos caracteres / e . no caminho do arquivo.
**
Coincide a qualquer coisa em vários níveis de diretório. Pode ser usada para fazer a correspondência recursiva com
vários arquivos em uma hierarquia de diretórios.
Exemplos de padrão glob
directory/file.txt
Corresponde a um arquivo específico em um diretório específico.
directory/*.txt
Corresponde a todos os arquivos com a extensão .txt em um diretório específico.
directory/*/appsettings.json
Corresponde a todos os arquivos appsettings.json em diretórios que estão exatamente um nível abaixo da pasta
diretório.
directory/**/*.txt
Corresponde a todos os arquivos com a extensão .txt encontrados em qualquer lugar abaixo da pasta diretório.
Solicitar recursos no ASP.NET Core
Por Steve Smith

Os detalhes de implementação de servidor Web relacionados a solicitações HTTP e respostas são definidos em
interfaces. Essas interfaces são usadas pelas implementações de servidor e pelo middleware para criar e modificar
o pipeline de hospedagem do aplicativo.
Interfaces de recurso
O ASP.NET Core define várias interfaces de recurso HTTP em Microsoft.AspNetCore.Http.Features , que são
usadas pelos servidores para identificar os recursos para os quais eles dão suporte. As seguintes interfaces de
recurso manipulam solicitações e respostas de retorno:
IHttpRequestFeature Define a estrutura de uma solicitação HTTP, incluindo o protocolo, o caminho, a cadeia de
caracteres de consulta, os cabeçalhos e o corpo.
IHttpResponseFeature Define a estrutura de uma resposta HTTP, incluindo o código de status, os cabeçalhos e o
corpo da resposta.
IHttpAuthenticationFeature Define o suporte para identificar os usuários com base em um ClaimsPrincipal e
especificando um manipulador de autenticação.
IHttpUpgradeFeature Define o suporte para Upgrades de HTTP, que permitem ao cliente especificar quais
protocolos adicionais ele desejará usar se o servidor quiser mudar os protocolos.
IHttpBufferingFeature Define métodos para desabilitar o buffer de solicitações e/ou respostas.
IHttpConnectionFeature Define propriedades para portas e endereços locais e remotos.
Define o suporte para anular conexões ou detectar se uma solicitação foi encerrada
IHttpRequestLifetimeFeature
prematuramente, como por uma desconexão do cliente.
IHttpSendFileFeature Define um método para enviar arquivos de forma assíncrona.
IHttpWebSocketFeature Define uma API para dar suporte a soquetes da Web.
IHttpRequestIdentifierFeature Adiciona uma propriedade que pode ser implementada para identificar as
solicitações de forma exclusiva.
ISessionFeature Define abstrações ISessionFactory e ISession para dar suporte a sessões de usuário.
ITlsConnectionFeature Define uma API para recuperar os certificados de cliente.
ITlsTokenBindingFeature Define métodos para trabalhar com parâmetros de associação de token de TLS.
NOTE
ISessionFeature não é um recurso de servidor, mas é implementado por SessionMiddleware (consulte Gerenciando o
estado do aplicativo).
Coleções de recursos
A propriedade Features de HttpContext fornece uma interface para obter e definir os recursos HTTP disponíveis
para a solicitação atual. Como a coleção de recursos é mutável, mesmo no contexto de uma solicitação, o
middleware pode ser usado para modificar a coleção e adicionar suporte para recursos adicionais.
Middleware e recursos de solicitação

Embora os servidores sejam responsáveis por criar a coleção de recursos, o middleware pode adicionar recursos a
essa coleção e consumi-los. Por exemplo, o StaticFileMiddleware acessa o recurso IHttpSendFileFeature . Se o
recurso existir, ele será usado para enviar o arquivo estático solicitado de seu caminho físico. Caso contrário, um
método alternativo mais lento será usado para enviar o arquivo. Quando disponível, o IHttpSendFileFeature
permite que o sistema operacional abra o arquivo e faça uma cópia direta de modo kernel para a placa de rede.
Além disso, o middleware pode adicionar recursos à coleção de recursos estabelecida pelo servidor. Os recursos
existentes podem até mesmo ser substituídos pelo middleware, permitindo que o middleware aumente a
funcionalidade do servidor. Os recursos adicionados à coleção ficam disponíveis imediatamente para outro
middleware ou para o próprio aplicativo subjacente posteriormente no pipeline de solicitação.
Combinando implementações personalizadas de servidor e melhorias específicas de middleware, o conjunto
preciso de recursos exigido por um aplicativo pode ser construído. Isso permite que os recursos ausentes sejam
adicionados, sem a necessidade de uma alteração no servidor, além de garantir que somente a quantidade mínima
de recursos seja exposta, limitando a área da superfície de ataque e melhorando o desempenho.
Resumo
As interfaces de recurso definem recursos HTTP específicos para os quais uma solicitação específica pode dar
suporte. Os servidores definem coleções de recursos e o conjunto inicial de recursos compatíveis com o servidor,
mas o middleware pode ser usado para aprimorar esses recursos.
Recursos adicionais
Servidores
Middleware
OWIN (Open Web Interface para .NET)
Acessar o HttpContext no ASP.NET Core
Os aplicativos ASP.NET Core acessam o HttpContext por meio da interface IHttpContextAccessor e da

implementação padrão do HttpContextAccessor. Só é necessário usar o IHttpContextAccessor quando você
precisar acessar o HttpContext em um serviço.
Usar o HttpContext de Razor Pages

O PageModel das Razor Pages expõe a propriedade HttpContext:

{
public void OnGet()

{
Message = HttpContext.Request.PathBase;
}
}
Usar o HttpContext de uma exibição do Razor

As exibições do Razor expõem o HttpContext diretamente por meio de uma propriedade RazorPage.Context na
exibição. O exemplo a seguir recupera o nome de usuário atual em um aplicativo de Intranet usando a
Autenticação do Windows:
@{
var username = Context.User.Identity.Name;
}
Usar o HttpContext de um controlador

Os controladores expõem a propriedade ControllerBase.HttpContext:

{
{
var pathBase = HttpContext.Request.PathBase;
// Do something with the PathBase.
return View();
}
}
Usar o HttpContext de middleware

Ao trabalhar com componentes personalizados de middleware, o HttpContext é passado para o método Invoke
ou InvokeAsync e pode ser acessado quando o middleware for configurado:
public class MyCustomMiddleware
{
public Task InvokeAsync(HttpContext context)
{
// Middleware initialization optionally using HttpContext
}
}
Usar o HttpContext de componentes personalizados

Para outras estruturas e componentes personalizados que exigem acesso ao HttpContext , a abordagem
recomendada é registrar uma dependência usando o contêiner integrado de injeção de dependência. O contêiner
de injeção de dependência fornece o IHttpContextAccessor para todas as classes que o declaram como uma
dependência em seus construtores.

{
services.AddMvc()
services.AddHttpContextAccessor();
services.AddTransient<IUserRepository, UserRepository>();
}

{
services.AddMvc();
services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
services.AddTransient<IUserRepository, UserRepository>();
}
No exemplo anterior:
o UserRepository declara sua dependência no IHttpContextAccessor .
A dependência é fornecida quando a injeção de dependência resolve a cadeia de dependências e cria uma
instância do UserRepository .
public class UserRepository : IUserRepository

{
private readonly IHttpContextAccessor _httpContextAccessor;
public UserRepository(IHttpContextAccessor httpContextAccessor)

{
_httpContextAccessor = httpContextAccessor;
}
public void LogCurrentUser()

{
var username = _httpContextAccessor.HttpContext.User.Identity.Name;
service.LogAccessRequest(username);
}
}
Detectar alterações com tokens de alteração no
ASP.NET Core
Por Luke Latham

Um token de alteração é um bloco de construção de uso geral e de baixo nível, usado para controlar as alterações.
Interface IChangeToken
IChangeToken propaga notificações de que ocorreu uma alteração. IChangeToken reside no namespace
Microsoft.Extensions.Primitives. Para aplicativos que não usam o metapacote Microsoft.AspNetCore.All (ASP.NET
Core 2.1 ou posterior), veja o pacote NuGet Microsoft.Extensions.Primitives no arquivo de projeto.
IChangeToken tem duas propriedades:
ActiveChangedCallbacks indique se o token gera retornos de chamada de forma proativa. Se
ActiveChangedCallbacks é definido como false , um retorno de chamada nunca é chamado e o aplicativo
precisa sondar HasChanged em busca de alterações. Também é possível que um token nunca seja cancelado se
não ocorrerem alterações ou o ouvinte de alteração subjacente for removido ou desabilitado.
HasChanged obtém um valor que indica se uma alteração ocorreu.
A interface tem um método, RegisterChangeCallback(Action<Object>, Object), que registra um retorno de
chamada que é invocado quando o token é alterado. HasChanged precisa ser definido antes de o retorno de
chamada ser invocado.
Classe ChangeToken
ChangeToken é uma classe estática usada para propagar notificações de que ocorreu uma alteração. ChangeToken
reside no namespace Microsoft.Extensions.Primitives. Para aplicativos que não usam o metapacote
Microsoft.AspNetCore.All, veja o pacote NuGet Microsoft.Extensions.Primitives no arquivo de projeto.
O método ChangeToken OnChange(Func<IChangeToken>, Action) registra um Action para chamar sempre que
o token é alterado:
Func<IChangeToken> produz o token.
Action é chamado quando o token é alterado.
ChangeTokentem uma sobrecarga OnChange<TState>(Func<IChangeToken>, Action<TState>, TState) que usa
um parâmetro TState adicional que é passado para o consumidor de token Action .
OnChange retorna um IDisposable. A chamada a Dispose interrompe a escuta do token de outras alterações e
libera os recursos do token.
Usos de exemplo de tokens de alteração no ASP.NET Core

Tokens de alteração são usados nas áreas proeminentes do monitoramento do ASP.NET Core de alterações em
objetos:
Para monitorar as alterações em arquivos, o método Watch de IFileProvider cria um IChangeToken para os
arquivos especificados ou para pasta a ser inspecionada.
Tokens IChangeToken podem ser adicionados a entradas de cache para disparar remoções do cache após as
alterações.
Para alterações TOptions , a implementação padrão de OptionsMonitor de IOptionsMonitor tem uma
sobrecarga que aceita uma ou mais instâncias IOptionsChangeTokenSource. Cada instância retorna um
IChangeToken para registrar um retorno de chamada de notificação de alteração para o controle de alterações
de opções.
Monitorando alterações de configuração

Por padrão, os modelos do ASP.NET Core usam arquivos de configuração JSON (appsettings.json,
appsettings.Development.json e appsettings.Production.json) para carregar as definições de configuração do
aplicativo.
Esses arquivos são configurados com o método de extensão AddJsonFile(IConfigurationBuilder, String, Boolean,
Boolean) no ConfigurationBuilder que aceita um parâmetro reloadOnChange (ASP.NET Core 1.1 e posterior).
reloadOnChange indica se a configuração deve ser recarregada após alterações de arquivo. Confira essa
configuração no método prático CreateDefaultBuilder do WebHost:

.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: true);
A configuração baseada em arquivo é representada por FileConfigurationSource. A FileConfigurationSource usa

o IFileProvider para monitorar arquivos.
Por padrão, o IFileMonitor é fornecido por um PhysicalFileProvider, que usa FileSystemWatcher para monitorar
as alterações no arquivo de configuração.
O aplicativo de exemplo demonstra duas implementações para monitorar as alterações de configuração. Se o
arquivo appsettings.json é alterado ou a versão do Ambiente do arquivo é alterada, cada implementação executa
um código personalizado. O aplicativo de exemplo grava uma mensagem no console.
O FileSystemWatcher de um arquivo de configuração pode disparar vários retornos de chamada de token para
uma única alteração de arquivo de configuração. A implementação da amostra protege contra esse problema
verificando os hashes de arquivo nos arquivos de configuração. A verificação de hashes de arquivo garante que,
pelo menos, um dos arquivos de configuração foi alterado antes de executar o código personalizado. A amostra
usa o hash de arquivo SHA1 (Utilities/Utilities.cs):
public static byte[] ComputeHash(string filePath)
{
var runCount = 1;
while(runCount < 4)
{
try
{
if (File.Exists(filePath))
{
using (var fs = File.OpenRead(filePath))
{
return System.Security.Cryptography.SHA1.Create().ComputeHash(fs);
}
}
else
{
throw new FileNotFoundException();
}
}
catch (IOException ex)
{
if (runCount == 3 || ex.HResult != -2147024864)
{
throw;
}
else
{
Thread.Sleep(TimeSpan.FromSeconds(Math.Pow(2, runCount)));
runCount++;
}
}
}
return new byte[20];

}
Uma nova tentativa é implementada com uma retirada exponencial. A nova tentativa está presente porque o
bloqueio de arquivo pode ocorrer, o que impede temporariamente a computação de um novo hash em um dos
arquivos.
Token de alteração de inicialização simples
Registre um retorno de chamada Action do consumidor de token para notificações de alteração no token de
recarregamento de configuração (Startup.cs):
ChangeToken.OnChange(
() => config.GetReloadToken(),
(state) => InvokeChanged(state),
env);
config.GetReloadToken() fornece o token. O retorno de chamada é o método InvokeChanged :

private void InvokeChanged(IHostingEnvironment env)
{
byte[] appsettingsHash = ComputeHash("appSettings.json");
byte[] appsettingsEnvHash =
ComputeHash($"appSettings.{env.EnvironmentName}.json");
if (!_appsettingsHash.SequenceEqual(appsettingsHash) ||
!_appsettingsEnvHash.SequenceEqual(appsettingsEnvHash))
{
_appsettingsHash = appsettingsHash;
_appsettingsEnvHash = appsettingsEnvHash;
WriteConsole("Configuration changed (Simple Startup Change Token)");

}
}
O state do retorno de chamada é usado para passar o IHostingEnvironment . Isso é útil para determinar o arquivo
de configuração JSON appsettings correto a ser monitorado, appsettings.<Environment>.json. Hashes de arquivo
são usados para impedir que a instrução WriteConsole seja executada várias vezes, devido a vários retornos de
chamada de token quando o arquivo de configuração é alterado somente uma vez.
Esse sistema é executado, desde que o aplicativo esteja em execução e não possa ser desabilitado pelo usuário.
Monitorando alterações de configuração como um serviço
A amostra implementa:
Monitoramento de token de inicialização básica.
Monitoramento como serviço.
Um mecanismo para habilitar e desabilitar o monitoramento.
A amostra estabelece uma interface IConfigurationMonitor (Extensions/ConfigurationMonitor.cs):
public interface IConfigurationMonitor

{
bool MonitoringEnabled { get; set; }
string CurrentState { get; set; }
}
O construtor da classe implementada, ConfigurationMonitor , registra um retorno de chamada para notificações de

alteração:
public ConfigurationMonitor(IConfiguration config, IHostingEnvironment env)

{
_env = env;
ChangeToken.OnChange<IConfigurationMonitor>(
() => config.GetReloadToken(),
InvokeChanged,
this);
}
public bool MonitoringEnabled { get; set; } = false;

public string CurrentState { get; set; } = "Not monitoring";
config.GetReloadToken() fornece o token. InvokeChanged é o método de retorno de chamada. O state nesta

instância é uma referência à instância IConfigurationMonitor que é usada para acessar o estado de
monitoramento. Duas propriedades são usadas:
MonitoringEnabled indica se o retorno de chamada deve executar seu código personalizado.
CurrentState descreve o estado atual de monitoramento para uso na interface do usuário.
O método InvokeChanged é semelhante à abordagem anterior, exceto que ele:

Não executa o código, a menos que MonitoringEnabled seja true .
Anota o state atual e sua saída WriteConsole .
private void InvokeChanged(IConfigurationMonitor state)

{
if (MonitoringEnabled)
{
byte[] appsettingsHash = ComputeHash("appSettings.json");
byte[] appsettingsEnvHash =
ComputeHash($"appSettings.{_env.EnvironmentName}.json");
if (!_appsettingsHash.SequenceEqual(appsettingsHash) ||
!_appsettingsEnvHash.SequenceEqual(appsettingsEnvHash))
{
string message = $"State updated at {DateTime.Now}";
_appsettingsHash = appsettingsHash;
_appsettingsEnvHash = appsettingsEnvHash;
WriteConsole($"Configuration changed (ConfigurationMonitor Class) {message}, state:

{state.CurrentState}");
}
}
}
Uma instância ConfigurationMonitor é registrada como um serviço em ConfigureServices de Startup.cs:
services.AddSingleton<IConfigurationMonitor, ConfigurationMonitor>();
A página Índice oferece ao usuário o controle sobre o monitoramento de configuração. A instância de

IConfigurationMonitor é injetada no IndexModel :
public IndexModel(
IConfiguration config,
IConfigurationMonitor monitor,
FileService fileService)
{
_config = config;
_monitor = monitor;
_fileService = fileService;
}
Um botão habilita e desabilita o monitoramento:
<button class="btn btn-danger" asp-page-handler="StopMonitoring">Stop Monitoring</button>

public IActionResult OnPostStartMonitoring()
{
_monitor.MonitoringEnabled = true;
_monitor.CurrentState = "Monitoring!";
}
public IActionResult OnPostStopMonitoring()

{
_monitor.MonitoringEnabled = false;
_monitor.CurrentState = "Not monitoring";
}
Quando OnPostStartMonitoring é disparado, o monitoramento é habilitado e o estado atual é desmarcado.

Quando OnPostStopMonitoring é disparado, o monitoramento é desabilitado e o estado é definido para refletir que
o monitoramento não está ocorrendo.
Monitorando alterações de arquivos armazenados em cache

O conteúdo do arquivo pode ser armazenado em cache em memória usando IMemoryCache. O cache na
memória é descrito no tópico Cache na memória. Sem realizar etapas adicionais, como a implementação descrita
abaixo, dados obsoletos (desatualizados) são retornados de um cache se os dados de origem são alterados.
Não levando em conta o status de um arquivo de origem armazenado em cache durante a renovação de um
período de expiração deslizante resulta em dados de cache obsoletos. Cada solicitação de dados renova o período
de expiração deslizante, mas o arquivo nunca é recarregado no cache. Os recursos do aplicativo que usam o
conteúdo armazenado em cache do arquivo estão sujeitos ao possível recebimento de conteúdo obsoleto.
O uso de tokens de alteração em um cenário de cache de arquivo impede o conteúdo de arquivo obsoleto no
cache. O aplicativo de exemplo demonstra uma implementação da abordagem.
A amostra usa GetFileContent para:
Retornar o conteúdo do arquivo.
Implementar um algoritmo de repetição com retirada exponencial para abranger casos em que um bloqueio de
arquivo está impedindo temporariamente a leitura de um arquivo.
Utilities/Utilities.cs:
public async static Task<string> GetFileContent(string filePath)
{
var runCount = 1;
while(runCount < 4)
{
try
{
if (File.Exists(filePath))
{
using (var fileStreamReader = File.OpenText(filePath))
{
return await fileStreamReader.ReadToEndAsync();
}
}
else
{
throw new FileNotFoundException();
}
}
catch (IOException ex)
{
if (runCount == 3 || ex.HResult != -2147024864)
{
throw;
}
else
{
await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, runCount)));
runCount++;
}
}
}
return null;
}
Um FileServiceé criado para manipular pesquisas de arquivos armazenados em cache. A chamada de método
GetFileContent do serviço tenta obter o conteúdo do arquivo do cache em memória e retorná-lo para o chamador
(Services/FileService.cs).
Se o conteúdo armazenado em cache não é encontrado com a chave de cache, as seguintes ações são executadas:
1. O conteúdo do arquivo é obtido com GetFileContent .
2. Um token de alteração é obtido do provedor de arquivo com IFileProviders.Watch. O retorno de chamada do
token é disparado quando o arquivo é modificado.
3. O conteúdo do arquivo é armazenado em cache com um período de expiração deslizante. O token de alteração
é anexado com MemoryCacheEntryExtensions.AddExpirationToken para remover a entrada do cache se o
arquivo é alterado enquanto ele é armazenado em cache.
public class FileService
{
private readonly IMemoryCache _cache;
private List<string> _tokens = new List<string>();
public FileService(IMemoryCache cache, IHostingEnvironment env)

{
_cache = cache;
_fileProvider = env.ContentRootFileProvider;
}
public async Task<string> GetFileContents(string fileName)

{
// For the purposes of this example, files are stored
// in the content root of the app. To obtain the physical
// path to a file at the content root, use the
// ContentRootFileProvider on IHostingEnvironment.
var filePath = _fileProvider.GetFileInfo(fileName).PhysicalPath;
string fileContent;
// Try to obtain the file contents from the cache.

if (_cache.TryGetValue(filePath, out fileContent))
{
return fileContent;
}
// The cache doesn't have the entry, so obtain the file

// contents from the file itself.
fileContent = await GetFileContent(filePath);
if (fileContent != null)
{
// Obtain a change token from the file provider whose
// callback is triggered when the file is modified.
var changeToken = _fileProvider.Watch(fileName);
// Configure the cache entry options for a five minute

// sliding expiration and use the change token to
// expire the file in the cache if the file is
// modified.
var cacheEntryOptions = new MemoryCacheEntryOptions()
.SetSlidingExpiration(TimeSpan.FromMinutes(5))
.AddExpirationToken(changeToken);
// Put the file contents into the cache.

_cache.Set(filePath, fileContent, cacheEntryOptions);
return fileContent;
}
}
}
O FileService é registrado no contêiner de serviço junto com o serviço de cache da memória ( Startup.cs):
services.AddMemoryCache();
services.AddSingleton<FileService>();
O modelo de página carrega o conteúdo do arquivo usando o serviço ( Pages/Index.cshtml.cs):
var fileContent = await _fileService.GetFileContents("poem.txt");

Classe CompositeChangeToken
Para representar uma ou mais instâncias de IChangeToken em um único objeto, use a classe
CompositeChangeToken.
var firstCancellationTokenSource = new CancellationTokenSource();

var secondCancellationTokenSource = new CancellationTokenSource();
var firstCancellationToken = firstCancellationTokenSource.Token;

var secondCancellationToken = secondCancellationTokenSource.Token;
var firstCancellationChangeToken = new CancellationChangeToken(firstCancellationToken);

var secondCancellationChangeToken = new CancellationChangeToken(secondCancellationToken);
var compositeChangeToken =
new CompositeChangeToken(
new List<IChangeToken>
{
firstCancellationChangeToken,
secondCancellationChangeToken
});
HasChanged nos relatórios de token compostos true se um token representado HasChanged é true .
ActiveChangeCallbacks nos relatórios de token compostos true se um token representado
ActiveChangeCallbacks é true . Se ocorrerem vários eventos de alteração simultâneos, o retorno de chamada de
alteração composto será invocado exatamente uma vez.
Recursos adicionais
Cache de resposta no ASP.NET Core
Middleware no ASP.NET Core de cache de resposta
Auxiliar de Marca de Cache Distribuído no ASP.NET Core
OWIN (Open Web Interface para .NET) com o
ASP.NET Core
Por Steve Smith e Rick Anderson

O ASP.NET Core dá suporte para OWIN (Open Web Interface para .NET). O OWIN permite que os aplicativos
Web sejam separados dos servidores Web. Ele define uma maneira padrão de usar o middleware em um
pipeline para manipular solicitações e respostas associadas. O middleware e os aplicativos ASP.NET Core
podem interoperar com aplicativos, servidores e middleware baseados no OWIN.
O OWIN fornece uma camada de desacoplamento que permite duas estruturas com modelos de objeto
diferentes para ser usadas juntas. O pacote Microsoft.AspNetCore.Owin fornece duas implementações de
adaptador:
ASP.NET Core para OWIN
OWIN para ASP.NET Core
Isso permite que o ASP.NET Core seja hospedado em um servidor/host compatível com OWIN ou que outros
componentes compatíveis com OWIN sejam executados no ASP.NET Core.
NOTE
O uso desses adaptadores implica um custo de desempenho. Os aplicativos que usam somente componentes do ASP.NET
Core não devem usar o pacote Microsoft.AspNetCore.Owin ou os adaptadores.
Executando o middleware do OWIN no pipeline do ASP.NET Core

O suporte ao OWIN do ASP.NET Core é implantado como parte do pacote Microsoft.AspNetCore.Owin . Importe
o suporte ao OWIN para seu projeto instalando esse pacote.
O middleware do OWIN está em conformidade com a especificação do OWIN, que exige uma interface
Func<IDictionary<string, object>, Task> e a definição de chaves específicas (como owin.ResponseBody ). O
seguinte middleware simples do OWIN exibe “Olá, Mundo”:
public Task OwinHello(IDictionary<string, object> environment)

{
string responseText = "Hello World via OWIN";
byte[] responseBytes = Encoding.UTF8.GetBytes(responseText);
// OWIN Environment Keys: http://owin.org/spec/spec/owin-1.0.0.html

var responseStream = (Stream)environment["owin.ResponseBody"];
var responseHeaders = (IDictionary<string, string[]>)environment["owin.ResponseHeaders"];
responseHeaders["Content-Length"] = new string[] {

responseBytes.Length.ToString(CultureInfo.InvariantCulture) };
responseHeaders["Content-Type"] = new string[] { "text/plain" };
return responseStream.WriteAsync(responseBytes, 0, responseBytes.Length);

}
A assinatura de exemplo retorna uma Task e aceita uma IDictionary<string, object> , conforme solicitado pelo
OWIN.
O código a seguir mostra como adicionar o middleware OwinHello (mostrado acima) ao pipeline do ASP.NET
Core com o método de extensão UseOwin .

{
app.UseOwin(pipeline =>
{
pipeline(next => OwinHello);
});
}
Configure outras ações a serem executadas no pipeline do OWIN.
NOTE
Os cabeçalhos de resposta devem ser modificados apenas antes da primeira gravação no fluxo de resposta.
NOTE
Não é recomendado fazer várias chamadas a UseOwin por motivos de desempenho. Os componentes do OWIN
funcionarão melhor se forem agrupados.
app.UseOwin(pipeline =>
{
pipeline(async (next) =>
{
// do something before
await OwinHello(new OwinEnvironment(HttpContext));
// do something after
});
});
Usando a hospedagem do ASP.NET Core em um servidor baseado no

OWIN
Os servidores baseados no OWIN podem hospedar aplicativos ASP.NET Core. Um desses servidores é o
Nowin, um servidor Web do OWIN no .NET. Na amostra para este artigo, incluí um projeto que referencia o
Nowin e usa-o para criar um IServer com capacidade de auto-hospedar o ASP.NET Core.
using System;
using System.IO;
using System.Linq;
namespace NowinSample
{
{
{
.UseNowin()
.Build();
host.Run();
}
}
}
O IServer é uma interface que requer uma propriedade Features e um método Start .
Start é responsável por configurar e iniciar o servidor, que, nesse caso, é feito por meio de uma série de
chamadas à API fluente que definem endereços analisados do IServerAddressesFeature. Observe que a
configuração fluente da variável _builder especifica que as solicitações serão manipuladas pelo appFunc
definido anteriormente no método. Esse Func é chamado em cada solicitação para processar as solicitações de
entrada.
Adicionaremos também uma extensão IWebHostBuilder para facilitar a adição e configuração do servidor
Nowin.
using System;
using Microsoft.AspNetCore.Hosting.Server;
using Nowin;
using NowinSample;
namespace Microsoft.AspNetCore.Hosting
{
public static class NowinWebHostBuilderExtensions
{
public static IWebHostBuilder UseNowin(this IWebHostBuilder builder)
{
return builder.ConfigureServices(services =>
{
services.AddSingleton<IServer, NowinServer>();
});
}
public static IWebHostBuilder UseNowin(this IWebHostBuilder builder, Action<ServerBuilder> configure)

{
{
services.Configure(configure);
});
return builder.UseNowin();
}
}
}
Com isso em vigor, invoque a extensão no Program.cs para executar um aplicativo ASP.NET Core usando este
servidor personalizado:
using System;
using System.IO;
using System.Linq;
namespace NowinSample
{
{
{
.UseNowin()
.Build();
host.Run();
}
}
}
Saiba mais sobre os Servidores ASP.NET.
Executar o ASP.NET Core em um servidor baseado no OWIN e usar

seu suporte do WebSockets
Outro exemplo de como os recursos dos servidores baseados no OWIN podem ser aproveitados pelo ASP.NET
Core é o acesso a recursos como o WebSockets. O servidor Web do OWIN no .NET usado no exemplo anterior
tem suporte para Soquetes da Web internos, que podem ser aproveitados por um aplicativo ASP.NET Core. O
exemplo abaixo mostra um aplicativo Web simples que dá suporte a Soquetes da Web e repete tudo o que foi
enviado ao servidor por meio do WebSockets.

{
{
{
{
await EchoWebSocket(webSocket);
}
else
{
await next();
}
});
app.Run(context =>
{
return context.Response.WriteAsync("Hello World");
});
}
private async Task EchoWebSocket(WebSocket webSocket)

{
byte[] buffer = new byte[1024];
WebSocketReceiveResult received = await webSocket.ReceiveAsync(
new ArraySegment<byte>(buffer), CancellationToken.None);
while (!webSocket.CloseStatus.HasValue)
{
// Echo anything we receive
await webSocket.SendAsync(new ArraySegment<byte>(buffer, 0, received.Count),
received.MessageType, received.EndOfMessage, CancellationToken.None);
received = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer),

}
await webSocket.CloseAsync(webSocket.CloseStatus.Value,
webSocket.CloseStatusDescription, CancellationToken.None);
}
}
Essa amostra é configurada usando o mesmo NowinServer que o anterior – a única diferença está em como o
aplicativo é configurado em seu método Configure . Um teste usando um cliente simples do WebSocket
demonstra o aplicativo:
Ambiente do OWIN
Você pode construir um ambiente do OWIN usando o HttpContext .
var environment = new OwinEnvironment(HttpContext);

var features = new OwinFeatureCollection(environment);
Chaves do OWIN
O OWIN depende de um objeto IDictionary<string,object> para transmitir informações em uma troca de
Solicitação/Resposta HTTP. O ASP.NET Core implementa as chaves listadas abaixo. Consulte a especificação
primária, extensões e as Diretrizes de chaves do OWIN e chaves comuns.
Dados de solicitação (OWIN v1.0.0)
CHAVE VALOR (TIPO) DESCRIÇÃO
owin.RequestScheme String
owin.RequestMethod String
owin.RequestPathBase String
owin.RequestPath String
owin.RequestQueryString String
owin.RequestProtocol String
owin.RequestHeaders IDictionary<string,string[]>
owin.RequestBody Stream
Dados de solicitação (OWIN v1.1.0)

owin.RequestId String Opcional
Dados de resposta (OWIN v1.0.0)

owin.ResponseStatusCode int Opcional
owin.ResponseReasonPhrase String Opcional
owin.ResponseHeaders IDictionary<string,string[]>
owin.ResponseBody Stream
Outros dados (OWIN v1.0.0)

owin.CallCancelled CancellationToken
owin.Version String
Chaves comuns
ssl.ClientCertificate X509Certificate
ssl.LoadClientCertAsync Func<Task>
server.RemoteIpAddress String
server.RemotePort String
server.LocalIpAddress String
server.LocalPort String
server.IsLocal bool
server.OnSendingHeaders Action<Action<object>,object>
SendFiles v0.3.0
sendfile.SendAsync Consulte Assinatura do delegado Por solicitação
Opaque v0.3.0
opaque.Version String
opaque.Upgrade OpaqueUpgrade Consulte Assinatura do delegado
opaque.Stream Stream
opaque.CallCancelled CancellationToken
WebSocket v0.3.0
websocket.Version String
websocket.Accept WebSocketAccept Consulte Assinatura do delegado
websocket.AcceptAlt Sem especificação
websocket.SubProtocol String Consulte a etapa 5.5 RFC6455 Seção

4.2.2
websocket.SendAsync WebSocketSendAsync Consulte Assinatura do delegado
websocket.ReceiveAsync WebSocketReceiveAsync Consulte Assinatura do delegado
websocket.CloseAsync WebSocketCloseAsync Consulte Assinatura do delegado
websocket.CallCancelled CancellationToken
websocket.ClientCloseStatus int Opcional
websocket.ClientCloseDescription String Opcional
Recursos adicionais
Middleware
Servidores
Tarefas em segundo plano com serviços hospedados
no ASP.NET Core
Por Luke Latham

No ASP.NET Core, as tarefas em segundo plano podem ser implementadas como serviços hospedados. Um
serviço hospedado é uma classe com lógica de tarefa em segundo plano que implementa a interface
IHostedService. Este tópico fornece três exemplos de serviço hospedado:
Tarefa em segundo plano que é executada com um temporizador.
Serviço hospedado que ativa um serviço com escopo. O serviço com escopo pode usar a injeção de
dependência.
Tarefas em segundo plano na fila que são executadas sequencialmente.
Este aplicativo de exemplo é fornecido em duas versões:
Host da Web – O Host da Web é útil para hospedar aplicativos web. O código de exemplo mostrado neste
tópico é da versão do host da web do exemplo. Para obter mais informações, consulte o tópico Host da Web.
Host Genérico – O Host Genérico é novo no ASP.NET Core 2.1. Para obter mais informações, confira o tópico
Host Genérico.
Pacote
Referencie o metapacote Microsoft.AspNetCore.App ou adicione uma referência de pacote ao pacote
Microsoft.Extensions.Hosting.
Interface IHostedService
Os serviços hospedados implementam a interface IHostedService. A interface define dois métodos para objetos
que são gerenciados pelo host:
StartAsync(CancellationToken) - StartAsync contém a lógica para iniciar a tarefa em segundo plano. Ao
usar o host Web, StartAsync é chamado depois que o servidor é iniciado e
IApplicationLifetime.ApplicationStarted é disparado. Ao usar o host genérico, StartAsync é chamado
antes de ApplicationStarted ser disparado.
StopAsync(CancellationToken) – é disparado quando o host está executando um desligamento normal.
StopAsync contém a lógica para encerrar a tarefa em segundo plano e descartar todos os recursos não
gerenciados. Se o aplicativo for desligado inesperadamente (por exemplo, em uma falha do processo do
aplicativo), StopAsync não poderá ser chamado.
O serviço hospedado é ativado uma única vez na inicialização do aplicativo e desligado normalmente durante o
desligamento do aplicativo. Quando IDisposable é implementado, os recursos podem ser descartados quando o
contêiner de serviço é descartado. Se um erro for gerado durante a execução da tarefa em segundo plano,
Dispose deverá ser chamado mesmo se StopAsync não for chamado.
Tarefas em segundo plano temporizadas

Uma tarefa em segundo plano temporizada usa a classe System.Threading.Timer. O temporizador dispara o
método DoWork da tarefa. O temporizador é desabilitado em StopAsync e descartado quando o contêiner de
serviço é descartado em Dispose :
internal class TimedHostedService : IHostedService, IDisposable

{
private Timer _timer;
public TimedHostedService(ILogger<TimedHostedService> logger)

{
_logger = logger;
}

{
_logger.LogInformation("Timed Background Service is starting.");
_timer = new Timer(DoWork, null, TimeSpan.Zero,

}
private void DoWork(object state)

{
_logger.LogInformation("Timed Background Service is working.");
}

{
_logger.LogInformation("Timed Background Service is stopping.");
_timer?.Change(Timeout.Infinite, 0);
}

{
_timer?.Dispose();
}
}
O serviço está registrado em Startup.ConfigureServices com o método de extensão AddHostedService :
services.AddHostedService<TimedHostedService>();
Consumindo um serviço com escopo em uma tarefa em segundo

plano
Para usar os serviços com escopo dentro de um IHostedService , crie um escopo. Por padrão, nenhum escopo é
criado para um serviço hospedado.
O serviço da tarefa em segundo plano com escopo contém a lógica da tarefa em segundo plano. No exemplo a
seguir, um ILogger é injetado no serviço:
internal interface IScopedProcessingService
{
void DoWork();
}
internal class ScopedProcessingService : IScopedProcessingService

{
public ScopedProcessingService(ILogger<ScopedProcessingService> logger)

{
_logger = logger;
}
public void DoWork()

{
_logger.LogInformation("Scoped Processing Service is working.");
}
}
O serviço hospedado cria um escopo para resolver o serviço da tarefa em segundo plano com escopo para
chamar seu método DoWork :
internal class ConsumeScopedServiceHostedService : IHostedService
{
public ConsumeScopedServiceHostedService(IServiceProvider services,

ILogger<ConsumeScopedServiceHostedService> logger)
{
Services = services;
_logger = logger;
}
public IServiceProvider Services { get; }

{
"Consume Scoped Service Hosted Service is starting.");
DoWork();
}
private void DoWork()

{
"Consume Scoped Service Hosted Service is working.");
using (var scope = Services.CreateScope())

{
var scopedProcessingService =
scope.ServiceProvider
.GetRequiredService<IScopedProcessingService>();
scopedProcessingService.DoWork();
}
}

{
"Consume Scoped Service Hosted Service is stopping.");
}
}
Os serviços são registrados em Startup.ConfigureServices . A implementação IHostedService é registrada com

o método de extensão AddHostedService :
services.AddHostedService<ConsumeScopedServiceHostedService>();
services.AddScoped<IScopedProcessingService, ScopedProcessingService>();
Tarefas em segundo plano na fila

Uma fila de tarefas em segundo plano é baseada no QueueBackgroundWorkItem do .NET 4.x (provisoriamente
agendado para ser integrado ao ASP.NET Core 3.0):
public interface IBackgroundTaskQueue
{
void QueueBackgroundWorkItem(Func<CancellationToken, Task> workItem);
Task<Func<CancellationToken, Task>> DequeueAsync(

CancellationToken cancellationToken);
}
public class BackgroundTaskQueue : IBackgroundTaskQueue

{
private ConcurrentQueue<Func<CancellationToken, Task>> _workItems =
new ConcurrentQueue<Func<CancellationToken, Task>>();
private SemaphoreSlim _signal = new SemaphoreSlim(0);
public void QueueBackgroundWorkItem(

Func<CancellationToken, Task> workItem)
{
if (workItem == null)
{
throw new ArgumentNullException(nameof(workItem));
}
_workItems.Enqueue(workItem);
_signal.Release();
}
public async Task<Func<CancellationToken, Task>> DequeueAsync(

{
await _signal.WaitAsync(cancellationToken);
_workItems.TryDequeue(out var workItem);
return workItem;
}
}
No QueueHostedService , as tarefas em segundo plano na fila são removidas da fila e executadas como um
BackgroundService, que é uma classe base para implementar um IHostedService de longa execução:
public class QueuedHostedService : BackgroundService
{
public QueuedHostedService(IBackgroundTaskQueue taskQueue,

{
TaskQueue = taskQueue;
_logger = loggerFactory.CreateLogger<QueuedHostedService>();
}
public IBackgroundTaskQueue TaskQueue { get; }
protected async override Task ExecuteAsync(

{
_logger.LogInformation("Queued Hosted Service is starting.");
while (!cancellationToken.IsCancellationRequested)
{
var workItem = await TaskQueue.DequeueAsync(cancellationToken);
try
{
await workItem(cancellationToken);
}
{
_logger.LogError(ex,
$"Error occurred executing {nameof(workItem)}.");
}
}
_logger.LogInformation("Queued Hosted Service is stopping.");

}
}
Os serviços são registrados em Startup.ConfigureServices . A implementação IHostedService é registrada com

o método de extensão AddHostedService :
services.AddHostedService<QueuedHostedService>();
services.AddSingleton<IBackgroundTaskQueue, BackgroundTaskQueue>();
Na classe de modelo de página de índice, a IBackgroundTaskQueue é injetada no construtor e atribuída à Queue :
public IndexModel(IBackgroundTaskQueue queue,

IApplicationLifetime appLifetime,
ILogger<IndexModel> logger)
{
Queue = queue;
_logger = logger;
}
public IBackgroundTaskQueue Queue { get; }
Quando o botão Adicionar Tarefa é selecionado na página de índice, o método OnPostAddTask é executado. O
QueueBackgroundWorkItem é chamado para enfileirar o item de trabalho:
public IActionResult OnPostAddTask()
{
Queue.QueueBackgroundWorkItem(async token =>
{
var guid = Guid.NewGuid().ToString();
for (int delayLoop = 0; delayLoop < 3; delayLoop++)

{
$"Queued Background Task {guid} is running. {delayLoop}/3");
await Task.Delay(TimeSpan.FromSeconds(5), token);
}
$"Queued Background Task {guid} is complete. 3/3");
});
}
Recursos adicionais
Implementar tarefas em segundo plano em microsserviços com IHostedService e a classe BackgroundService
System.Threading.Timer
Aprimorar um aplicativo por meio de um assembly
externo no ASP.NET Core com IHostingStartup
Por Luke Latham

Uma implementação IHostingStartup (inicialização de hospedagem) adiciona melhorias a um aplicativo
durante a inicialização de um assembly externo. Por exemplo, uma biblioteca externa pode usar uma
implementação de inicialização de hospedagem para fornecer serviços ou provedores de configuração
adicionais a um aplicativo. IHostingStartup está disponível no ASP.NET Core 2.0 ou posterior.
Atributo HostingStartup
Um atributo HostingStartup indica a presença de um assembly de inicialização de hospedagem para ativar em
tempo de execução.
O assembly de entrada ou o assembly que contém a classe Startup é automaticamente examinado para o
atributo HostingStartup . A lista de assemblies a ser pesquisada para os atributos HostingStartup é carregada
no tempo de execução da configuração em WebHostDefaults.HostingStartupAssembliesKey. A lista de
assemblies para excluir da descoberta é carregada de WebHostDefaults.HostingStartupExcludeAssembliesKey.
Para obter mais informações, consulte Host da Web: assemblies de inicialização de hospedagem e Host da Web:
assemblies de exclusão da inicialização de hospedagem.
No exemplo a seguir, o namespace do assembly de inicialização de hospedagem é StartupEnhancement . A classe
que contém o código de inicialização de hospedagem é StartupEnhancementHostingStartup :
[assembly: HostingStartup(typeof(StartupEnhancement.StartupEnhancementHostingStartup))]
O atributo normalmente está localizado no arquivo de classe de implementação

HostingStartup
IHostingStartup do assembly de inicialização de hospedagem.
Descobrir assemblies de inicialização de hospedagem carregados

Para descobrir os assemblies de inicialização de hospedagem carregados, habilite o registro em log e verifique
os logs do aplicativo. Erros que ocorrem quando os assemblies carregados são registrados em log. Os
assemblies de inicialização de hospedagem carregados são registrados em log no nível Depuração e todos os
erros são registrados.
Desabilitar o carregamento automático de assemblies de inicialização

de hospedagem
Para desabilitar o carregamento automático de assemblies de inicialização de hospedagem, use uma das
seguintes abordagens:
Para impedir o carregamento de todos os assemblies de inicialização de hospedagem, defina o seguinte para
true ou 1 :
Configuração do host Impedir inicialização de hospedagem.
A variável de ambiente ASPNETCORE_PREVENTHOSTINGSTARTUP .
Para evitar o carregamento de assemblies específicos de inicialização de hospedagem, defina uma das
opções a seguir como uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de
inicialização de hospedagem para excluir na inicialização:
Configuração do host Assemblies de exclusão de inicialização de hospedagem.
A variável de ambiente ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES .
Para desabilitar o carregamento automático de assemblies de inicialização de hospedagem, defina um dos
seguintes como true ou 1 :
Configuração do host Impedir inicialização de hospedagem.
A variável de ambiente ASPNETCORE_PREVENTHOSTINGSTARTUP .
Se a configuração do host e a variável de ambiente estiverem definidas, a configuração do host controlará o
comportamento.
A desabilitação de assemblies de inicialização de hospedagem usando a configuração do host ou a variável de
ambiente desabilita o assembly globalmente e poderá desabilitar várias características de um aplicativo.
Projeto
Crie uma inicialização de hospedagem com qualquer um dos seguintes tipos de projeto:
Biblioteca de classes
Aplicativo de console sem um ponto de entrada
Biblioteca de classes
Uma melhoria da inicialização de hospedagem pode ser fornecida em uma biblioteca de classes. A biblioteca
contém um atributo HostingStartup .
O código de exemplo inclui um aplicativo Razor Pages, HostingStartupApp e uma biblioteca de classes,
HostingStartupLibrary. A biblioteca de classes:
Contém uma classe de inicialização de hospedagem, ServiceKeyInjection , que implementa
IHostingStartup . ServiceKeyInjection adiciona um par de cadeias de caracteres de serviço à configuração
do aplicativo usando o provedor de configuração na memória (AddInMemoryCollection).
Inclui um atributo HostingStartup que identifica o namespace e a classe de inicialização de hospedagem.
O método Configure da classe ServiceKeyInjection usa um IWebHostBuilder para adicionar melhorias a um
aplicativo. IHostingStartup.Configure no assembly de inicialização de hospedagem é chamado pelo tempo de
execução antes de Startup.Configure no código do usuário, o que permite que o código de usuário substitua
qualquer configuração fornecida pelo assembly de inicialização de hospedagem.
HostingStartupLibrary/ServiceKeyInjection.cs:
[assembly: HostingStartup(typeof(HostingStartupLibrary.ServiceKeyInjection))]
namespace HostingStartupLibrary
{
public class ServiceKeyInjection : IHostingStartup
{
{
builder.ConfigureAppConfiguration(config =>
{
{
{"DevAccount_FromLibrary", "DEV_1111111-1111"},
{"ProdAccount_FromLibrary", "PROD_2222222-2222"}
};
config.AddInMemoryCollection(dict);
});
}
}
}
A página de índice do aplicativo lê e renderiza os valores de configuração para as duas chaves definidas pelo
assembly de inicialização de hospedagem da biblioteca de classes:
HostingStartupApp/Pages/Index.cshtml.cs:

{
public IndexModel(IConfiguration config)
{
ServiceKey_Development_Library = config["DevAccount_FromLibrary"];
ServiceKey_Production_Library = config["ProdAccount_FromLibrary"];
ServiceKey_Development_Package = config["DevAccount_FromPackage"];
ServiceKey_Production_Package = config["ProdAccount_FromPackage"];
}
public string ServiceKey_Development_Library { get; private set; }

public string ServiceKey_Production_Library { get; private set; }
public string ServiceKey_Development_Package { get; private set; }
public string ServiceKey_Production_Package { get; private set; }
public void OnGet()

{
}
}
O código de exemplo também inclui um projeto de pacote do NuGet que fornece uma inicialização de
hospedagem separada, HostingStartupPackage. O pacote tem as mesmas características da biblioteca de
classes descrita anteriormente. O pacote:
Contém uma classe de inicialização de hospedagem, ServiceKeyInjection , que implementa
IHostingStartup . ServiceKeyInjection adiciona um par de cadeias de caracteres de serviço para a
configuração do aplicativo.
Inclui um atributo HostingStartup .
HostingStartupPackage/ServiceKeyInjection.cs:
[assembly: HostingStartup(typeof(HostingStartupPackage.ServiceKeyInjection))]
namespace HostingStartupPackage
{
public class ServiceKeyInjection : IHostingStartup
{
{
builder.ConfigureAppConfiguration(config =>
{
{
{"DevAccount_FromPackage", "DEV_3333333-3333"},
{"ProdAccount_FromPackage", "PROD_4444444-4444"}
};
config.AddInMemoryCollection(dict);
});
}
}
}
A página de índice do aplicativo lê e renderiza os valores de configuração para as duas chaves definidas pelo
assembly de inicialização de hospedagem do pacote:
HostingStartupApp/Pages/Index.cshtml.cs:

{
public IndexModel(IConfiguration config)
{
ServiceKey_Development_Library = config["DevAccount_FromLibrary"];
ServiceKey_Production_Library = config["ProdAccount_FromLibrary"];
ServiceKey_Development_Package = config["DevAccount_FromPackage"];
ServiceKey_Production_Package = config["ProdAccount_FromPackage"];
}
public string ServiceKey_Development_Library { get; private set; }

public string ServiceKey_Production_Library { get; private set; }
public string ServiceKey_Development_Package { get; private set; }
public string ServiceKey_Production_Package { get; private set; }
public void OnGet()

{
}
}
Aplicativo de console sem um ponto de entrada

Essa abordagem só está disponível para aplicativos .NET Core, não para .NET Framework.
Uma melhoria de inicialização de hospedagem dinâmica que não requer uma referência de tempo de
compilação para a ativação pode ser fornecida em um aplicativo de console sem um ponto de entrada. O
aplicativo contém um atributo HostingStartup . Para criar uma inicialização de hospedagem dinâmica:
1. Uma biblioteca de implementação é criada com base na classe que contém a implementação
IHostingStartup . A biblioteca de implementação é tratada como um pacote normal.
2. Um aplicativo de console sem um ponto de entrada referencia o pacote de biblioteca da implementação. Um
aplicativo de console é usado, pois:
Um arquivo de dependências é um ativo de aplicativo executável, então uma biblioteca não pode
fornecer um arquivo de dependências.
Uma biblioteca não pode ser adicionada diretamente ao repositório de pacotes de tempo de
execução, o que exige um projeto executável que tem como alvo o tempo de execução compartilhado.
3. O aplicativo de console é publicado para obter as dependências da inicialização de hospedagem. Uma
consequência de publicar o aplicativo de console é que as dependências não utilizadas são cortadas do
arquivo de dependências.
4. O aplicativo e seu arquivo de dependências é colocado no repositório do pacote de tempo de execução. Para
descobrir o assembly de inicialização de hospedagem e seu arquivo de dependências, eles são referenciados
em um par de variáveis de ambiente.
O assembly de aplicativo do console referencia o pacote Microsoft.AspNetCore.Hosting.Abstractions:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Hosting.Abstractions"
Version="2.1.1" />
</ItemGroup>
</Project>
Um atributo HostingStartup identifica uma classe como uma implementação de IHostingStartup para o
carregamento e a execução durante a criação do IWebHost. No seguinte exemplo, o namespace é
StartupEnhancement e a classe é StartupEnhancementHostingStartup :
[assembly: HostingStartup(typeof(StartupEnhancement.StartupEnhancementHostingStartup))]
Uma classe implementa IHostingStartup . O método Configure da classe usa um IWebHostBuilder para
adicionar melhorias a um aplicativo. IHostingStartup.Configure no assembly de inicialização de hospedagem é
chamado pelo tempo de execução antes de Startup.Configure no código do usuário, o que permite que o
código de usuário substitua qualquer configuração fornecida pelo assembly de inicialização de hospedagem.
namespace StartupEnhancement
{
public class StartupEnhancementHostingStartup : IHostingStartup
{
{
// Use the IWebHostBuilder to add app enhancements.
}
}
}
Ao criar um projeto IHostingStartup , o arquivo de dependências (*.deps.json) define o local runtime do

assembly como a pasta bin:
"targets": {
".NETCoreApp,Version=v2.1": {
"StartupEnhancement/1.0.0": {
"dependencies": {
"Microsoft.AspNetCore.Hosting.Abstractions": "2.1.1"
},
"runtime": {
"StartupEnhancement.dll": {}
}
}
}
}
Apenas uma parte do arquivo é mostrada. O nome do assembly no exemplo é StartupEnhancement .
Especificar o assembly de inicialização de hospedagem

Para uma biblioteca de classes ou inicialização de hospedagem fornecida pelo aplicativo de console, especifique
o nome do assembly de inicialização de hospedagem na variável de ambiente
ASPNETCORE_HOSTINGSTARTUPASSEMBLIES . A variável de ambiente é uma lista de assemblies delimitada por ponto e
vírgula.
Apenas assemblies de inicialização de hospedagem são examinados quanto ao atributo HostingStartup . Para o
aplicativo de exemplo, HostingStartupApp, para descobrir as inicializações de hospedagem descritas
anteriormente, a variável de ambiente é definida como o seguinte valor:
HostingStartupLibrary;HostingStartupPackage;StartupDiagnostics
Um assembly de inicialização de hospedagem também pode ser definido usando a configuração do host
Assemblies de inicialização de hospedagem.
Quando há vários assemblies de inicialização de hospedagem, os métodos Configure são executados na ordem
em que os assemblies são listados.
Ativação
As opções para ativação da inicialização de hospedagem são:
Repositório de tempo de execução – A ativação não requer uma referência de tempo de compilação para a
ativação. O aplicativo de exemplo coloca os arquivos de dependências e o assembly de inicialização de
hospedagem em uma pasta, implantação, para facilitar a implantação da inicialização de hospedagem em
um ambiente multicomputador. A pasta implantação também inclui um script do PowerShell que cria ou
modifica variáveis de ambiente no sistema de implantação para habilitar a inicialização de hospedagem.
Referência de tempo de compilação necessária para a ativação
Pacote do NuGet
Pasta Lixeira do projeto
Repositório de tempo de execução
A implementação de inicialização de hospedagem é colocada no repositório de tempo de execução. Uma
referência de tempo de compilação para o assembly não é exigida pelo aplicativo aprimorado.
Depois que a inicialização de hospedagem é compilada, o arquivo de projeto de inicialização de hospedagem
serve como o arquivo de manifesto para o comando dotnet store.
dotnet store --manifest <PROJECT_FILE> --runtime <RUNTIME_IDENTIFIER>
Esse comando coloca o assembly de inicialização de hospedagem e outras dependências que não fazem parte
da estrutura compartilhada no repositório de tempo de execução do perfil do usuário em:
Windows
macOS
Linux
%USERPROFILE%\.dotnet\store\x64\<TARGET_FRAMEWORK_MONIKER>\<ENHANCEMENT_ASSEMBLY_NAME>\
<ENHANCEMENT_VERSION>\lib\<TARGET_FRAMEWORK_MONIKER>\
Se você desejar colocar o assembly e as dependências para uso global, adicione a opção -o|--output ao
comando dotnet store com o seguinte caminho:
Windows
macOS
Linux
%PROGRAMFILES%\dotnet\store\x64\<TARGET_FRAMEWORK_MONIKER>\<ENHANCEMENT_ASSEMBLY_NAME>\
<ENHANCEMENT_VERSION>\lib\<TARGET_FRAMEWORK_MONIKER>\
Modificar e colocar o arquivo de dependências da inicialização de hospedagem

O local do tempo de execução é especificado no arquivo *.deps.json. Para ativar a melhoria, o elemento
runtime deve especificar o local do assembly de tempo de execução da melhoria. Preceda o local runtime com
lib/<TARGET_FRAMEWORK_MONIKER>/ :
"targets": {
".NETCoreApp,Version=v2.1": {
"StartupEnhancement/1.0.0": {
"dependencies": {
"Microsoft.AspNetCore.Hosting.Abstractions": "2.1.1"
},
"runtime": {
"lib/netcoreapp2.1/StartupEnhancement.dll": {}
}
}
}
}
No código de exemplo (projeto StartupDiagnostics), a modificação do arquivo *.deps.json é executada por um

script do PowerShell. O script do PowerShell é disparado automaticamente por um destino de build no arquivo
de projeto.
O arquivo *.deps.json da implementação deve estar em um local acessível.
Para uso por usuário, coloque o arquivo na pasta additonalDeps das configurações .dotnet do perfil do
usuário:
Windows
macOS
Linux
%USERPROFILE%\.dotnet\x64\additionalDeps\<ENHANCEMENT_ASSEMBLY_NAME>\shared\Microsoft.NETCore.App\
<SHARED_FRAMEWORK_VERSION>\
Para uso global, coloque o arquivo na pasta additonalDeps da instalação do .NET Core:
Windows
macOS
Linux
%PROGRAMFILES%\dotnet\additionalDeps\<ENHANCEMENT_ASSEMBLY_NAME>\shared\Microsoft.NETCore.App\
<SHARED_FRAMEWORK_VERSION>\
Observe que a versão da estrutura compartilhada reflete a versão do tempo de execução compartilhado usado
pelo aplicativo de destino. O tempo de execução compartilhado é mostrado no arquivo *.runtimeconfig.json. No
aplicativo de exemplo (HostingStartupApp), o tempo de execução compartilhado é especificado no arquivo
HostingStartupApp.runtimeconfig.json.
Listar o arquivo de dependências da inicialização de hospedagem
O local do arquivo *.deps.json da implementação é listado na variável de ambiente DOTNET_ADDITIONAL_DEPS .
Se o arquivo for colocado na pasta .dotnet do perfil do usuário, defina o valor da variável de ambiente para:
Windows
macOS
Linux
%USERPROFILE%\.dotnet\x64\additionalDeps\
Se o arquivo for colocado na instalação do .NET Core para uso global, forneça o caminho completo para o
arquivo:
Windows
macOS
Linux
%PROGRAMFILES%\dotnet\additionalDeps\<ENHANCEMENT_ASSEMBLY_NAME>\shared\Microsoft.NETCore.App\
<SHARED_FRAMEWORK_VERSION>\<ENHANCEMENT_ASSEMBLY_NAME>.deps.json
Para o aplicativo de exemplo (HostingStartupApp) localizar o arquivo de dependências

(HostingStartupApp.runtimeconfig.json), o arquivo de dependências é colocado no perfil do usuário.
Windows
macOS
Linux
Use a variável de ambiente DOTNET_ADDITIONAL_DEPS para o valor a seguir:
%UserProfile%\.dotnet\x64\additionalDeps\StartupDiagnostics\
Para obter exemplos de como definir variáveis de ambiente para vários sistemas operacionais, confira Usar
vários ambientes.
Implantação
Para facilitar a implantação de uma inicialização de hospedagem em um ambiente multicomputador, o
aplicativo de exemplo cria uma pasta implantação na saída publicada que contém:
O assembly de inicialização de hospedagem.
O arquivo de dependências de inicialização de hospedagem.
Um script do PowerShell que cria ou modifica ASPNETCORE_HOSTINGSTARTUPASSEMBLIES e
DOTNET_ADDITIONAL_DEPS para dar suporte à ativação da inicialização de hospedagem. Execute o script de um
prompt de comando do PowerShell administrativo no sistema de implantação.
Pacote NuGet
Uma melhoria da inicialização de hospedagem pode ser fornecida em pacote do NuGet. O pacote tem um
atributo HostingStartup . Os tipos de inicialização de hospedagem fornecidos pelo pacote são disponibilizados
para o aplicativo usando qualquer uma das seguintes abordagens:
O arquivo de projeto do aplicativo aprimorado faz uma referência de pacote para a inicialização de
hospedagem no arquivo de projeto do aplicativo (uma referência de tempo de compilação). Com a
referência de tempo de compilação em vigor, o assembly de inicialização de hospedagem e todas as suas
dependências são incorporados ao arquivo de dependência do aplicativo (*.deps.json). Essa abordagem se
aplica a um pacote de assembly de inicialização de hospedagem publicado para nuget.org.
O arquivo de dependências da inicialização de hospedagem fica disponível para o aplicativo avançado,
conforme descrito na seção Repositório de tempo de execução (sem uma referência de tempo de
compilação).
Para obter mais informações sobre pacotes do NuGet e o repositório de tempo de execução, consulte os
tópicos a seguir:
Como criar um pacote do NuGet com ferramentas de plataforma cruzada
Publicando pacotes
Repositório de pacote de tempo de execução
Pasta Lixeira do projeto
Uma melhoria da inicialização de hospedagem pode ser fornecida por um assemby implantado na lixeira no
aplicativo aprimorado. Os tipos de inicialização de hospedagem fornecidos pelo assembly são disponibilizados
para o aplicativo usando uma das seguintes abordagens:
O arquivo de projeto do aplicativo aprimorado faz uma referência de assembly para a inicialização de
hospedagem (uma referência de tempo de compilação). Com a referência de tempo de compilação em vigor,
o assembly de inicialização de hospedagem e todas as suas dependências são incorporados ao arquivo de
dependência do aplicativo (*.deps.json). Essa abordagem é aplicável quando o cenário de implantação faz
chamadas para mover o assembly compilado da biblioteca de inicialização de hospedagem (arquivo DLL )
para o projeto consumidor ou para um local acessível pelo projeto consumidor e uma referência de tempo
de compilação é feita para o assembly de inicialização de hospedagem.
O arquivo de dependências da inicialização de hospedagem fica disponível para o aplicativo avançado,
conforme descrito na seção Repositório de tempo de execução (sem uma referência de tempo de
compilação).
Código de exemplo
O código de exemplo (como baixar) demonstra cenários de implementação de inicialização de hospedagem:
Dois assemblies de inicialização de hospedagem (bibliotecas de classes) definem um par chave-valor de
configuração na memória cada:
Pacote do NuGet (HostingStartupPackage)
Biblioteca de classes (HostingStartupLibrary)
Uma inicialização de hospedagem é ativada de um assembly implantado pelo repositório de tempo de
execução (StartupDiagnostics). O assembly adiciona dois middlewares ao aplicativo na inicialização que
fornecem informações de diagnóstico sobre:
Serviços registrados
Endereço (esquema, host, base do caminho, caminho, cadeia de caracteres de consulta)
Conexão (IP remoto, porta remota, IP local, porta local, certificado do cliente)
Cabeçalhos de solicitação
Para executar a amostra:
Ativação de um pacote do NuGet
1. Compile o pacote HostingStartupPackage com o comando dotnet pack.
2. Adicione o nome do assembly do pacote do HostingStartupPackage para a variável de ambiente
ASPNETCORE_HOSTINGSTARTUPASSEMBLIES .
3. Compile e execute o aplicativo. Uma referência de pacote está presente no aplicativo aprimorado (uma
referência de tempo de compilação). Um <PropertyGroup> no arquivo de projeto do aplicativo especifica
a saída do projeto de pacote (../HostingStartupPackage/bin/Debug) como uma origem de pacote. Isso
permite que o aplicativo use o pacote sem carregar o pacote para nuget.org. Para mais informações,
consulte as notas no arquivo de projeto do HostingStartupApp.
<PropertyGroup>
<RestoreSources>$(RestoreSources);https://api.nuget.org/v3/index.json;../HostingStartupPackage/bin/De
bug</RestoreSources>
</PropertyGroup>
4. Observe que os valores de chave de configuração do serviço renderizados pela página de índice
correspondem aos valores definidos pelo método ServiceKeyInjection.Configure do pacote.
Se você fizer alterações no projeto HostingStartupPackage e recompilá-lo, limpe os caches de pacote do NuGet
locais para garantir que o HostingStartupApp receba o pacote atualizado e não um pacote obsoleto do cache
local. Para limpar os caches locais do NuGet, execute o seguinte comando dotnet nuget locals:
dotnet nuget locals all --clear
Ativação de uma biblioteca de classes

1. Compile a biblioteca de classes HostingStartupLibrary com o comando dotnet build.
2. Adicione nome do assembly da biblioteca de classes do HostingStartupLibrary à variável de ambiente
3. A pasta lixeira implanta o assembly da biblioteca de classes para o aplicativo ao copiar o arquivo
HostingStartupLibrary.dll da saída compilada da biblioteca de classes para a pasta lixeira/Depurar do
aplicativo.
4. Compile e execute o aplicativo. Um <ItemGroup> do arquivo de projeto do aplicativo referencia o
assembly da biblioteca de classes (.\lixeira\Depurar\netcoreapp2.1\HostingStartupLibrary.dll) (uma
referência de tempo de compilação). Para mais informações, consulte as notas no arquivo de projeto do
HostingStartupApp.
<ItemGroup>
<Reference Include=".\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll">
<HintPath>.\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll</HintPath>
<SpecificVersion>False</SpecificVersion>
</Reference>
</ItemGroup>
5. Observe que os valores de chave de configuração do serviço renderizados pela página de índice
correspondem aos valores definidos pelo método ServiceKeyInjection.Configure da biblioteca de
classes.
Ativação de um assembly implantado pelo repositório de tempo de execução
1. O projeto StartupDiagnostics usa o PowerShell para modificar seu arquivo StartupDiagnostics.deps.json.
O PowerShell é instalado por padrão em um sistema operacional Windows começando no Windows 7
SP1 e no Windows Server 2008 R2 SP1. Para obter o PowerShell em outras plataformas, confira
Instalando o Windows PowerShell.
2. Compilar o projeto StartupDiagnostics. Depois que o projeto é compilado, um destino de compilação no
arquivo de projeto automaticamente:
Dispara o script do PowerShell para modificar o arquivo StartupDiagnostics.deps.json.
Move o arquivo StartupDiagnostics.deps.json para a pasta additionalDeps do perfil do usuário.
3. Execute o comando dotnet store em um prompt de comando no diretório de inicialização de
hospedagem para armazenar o assembly e suas dependências no repositório de tempo de execução do
perfil do usuário:
dotnet store --manifest StartupDiagnostics.csproj --runtime <RID>
Para Windows, o comando usa o win7-x64 RID (identificador de tempo de execução). Ao fornecer a
inicialização de hospedagem para um tempo de execução diferente, substitua o RID correto.
4. Defina as variáveis de ambiente:
Adicione o nome do assembly de StartupDiagnostics para a variável de ambiente
No Windows, defina a variável de ambiente DOTNET_ADDITIONAL_DEPS como
%UserProfile%\.dotnet\x64\additionalDeps\StartupDiagnostics\ . No macOS/Linux, defina a variável de
ambiente DOTNET_ADDITIONAL_DEPS como
/Users/<USER>/.dotnet/x64/additionalDeps/StartupDiagnostics/ , em que <USER> é o perfil do usuário
que contém a inicialização de hospedagem.
5. Execute o aplicativo de exemplo.
6. Solicite o ponto de extremidade /services para ver os serviços registrados do aplicativo. Solicite o
ponto de extremidade /diag para ver as informações de diagnóstico.
Metapacote Microsoft.AspNetCore.App
para ASP.NET Core 2.1
Este recurso exige o ASP.NET Core 2.1 e posterior direcionado ao .NET Core 2.1 e posterior.
O metapacote Microsoft.AspNetCore.App para ASP.NET Core:
Não tem dependências de terceiros, com exceção de Json.NET, Remotion.Linq e IX-Async.
Essas dependências de terceiros são consideradas necessárias para garantir o
funcionamento dos principais recursos das estruturas.
Inclui todos os pacotes com suporte pela equipe do ASP.NET Core, exceto aqueles que
contêm dependências de terceiros (que não sejam aqueles mencionados anteriormente).
Inclui todos os pacotes com suporte pela equipe do Entity Framework Core, exceto aqueles
que contêm dependências de terceiros (que não sejam aqueles mencionados
anteriormente).
Todos os recursos do ASP.NET Core 2.1 e posterior e do Entity Framework Core 2.1 e
posterior são incluídos no pacote Microsoft.AspNetCore.App . Os modelos de projeto padrão
direcionados para ASP.NET Core 2.1 e posterior usam este pacote. Recomendamos que
aplicativos voltados para o ASP.NET Core 2.1 e posterior e o Entity Framework Core 2.1 e
posterior usem o pacote Microsoft.AspNetCore.App .
O número de versão do metapacote Microsoft.AspNetCore.App representa a versão do
ASP.NET Core e a versão do Entity Framework Core.
O uso do metapacote Microsoft.AspNetCore.App fornece restrições de versões que protegem
seu aplicativo:
Se um pacote incluído tem uma dependência (não direta) transitiva em um pacote no
Microsoft.AspNetCore.App , e os números de versão forem diferentes, o NuGet gera um
erro.
Outros pacotes adicionados ao seu aplicativo não podem alterar a versão dos pacotes
incluídos no Microsoft.AspNetCore.App .
A consistência de versão garante uma experiência confiável. Microsoft.AspNetCore.App foi
projetado para evitar combinações de versão não testado de bits relacionados que estão
sendo usados juntos no mesmo aplicativo.
Aplicativos que usam o metapacote Microsoft.AspNetCore.App aproveitam automaticamente a
estrutura compartilhada do ASP.NET Core. Quando você usa o metapacote
Microsoft.AspNetCore.App , nenhum ativo dos pacotes NuGet do ASP.NET Core referenciados
é implantado com o aplicativo, porque a estrutura compartilhada do ASP.NET Core contém
esses ativos. Os ativos na estrutura compartilhada são pré-compilados para melhorar o tempo
de inicialização do aplicativo. Para obter mais informações, veja "estrutura compartilhada" em
Empacotamento de distribuição do .NET Core.
O seguinte arquivo de projeto referencia o metapacote Microsoft.AspNetCore.App do ASP.NET
Core e representa um modelo típico do ASP.NET Core 2.1:
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
</Project>
A marcação anterior representa um modelo típico de ASP.NET Core 2.1 e posterior. Ela não
especifica um número de versão para a referência de pacote Microsoft.AspNetCore.App .
Quando a versão não for especificada, uma versão implícita será especificada pelo SDK, ou
seja, Microsoft.NET.Sdk.Web . Recomendamos que você conte com a versão implícita
especificada pelo SDK, e não defina explicitamente o número de versão na referência de
pacote. Se tiver dúvidas sobre essa abordagem, deixe um comentário do GitHub na Discussão
para a versão implícita do Microsoft.AspNetCore.App.
A versão implícita é definida como major.minor.0 para aplicativos portátil. O mecanismo de
roll forward estrutura compartilhada executará o aplicativo na versão compatível mais recente
entre as estruturas compartilhadas instaladas. Para garantir que a mesma versão seja usada
no desenvolvimento, no teste e na produção, certifique-se de que a mesma versão da
estrutura compartilhada seja instalada em todos os ambientes. Para aplicativos independentes,
o número de versão implícita é definido como major.minor.patch da estrutura compartilhada
incluída no SDK instalado.
Especificar um número de versão na referência Microsoft.AspNetCore.App não garante que a
versão da estrutura compartilhada será escolhida. Por exemplo, suponha que a versão "2.1.1"
foi especificada, mas "2.1.3" está instalada. Nesse caso, o aplicativo usará "2.1.3". Embora não
seja recomendado, você pode desabilitar o roll forward (patch e/ou secundária). Para obter
mais informações sobre como efetuar roll forward do host dotnet e como configurar seu
comportamento, veja Efetuar roll forward do host dotnet.
<Project Sdk deve ser definido como Microsoft.NET.Sdk.Web para usar o
Microsoft.AspNetCore.App da versão implícita. Quando <Project Sdk="Microsoft.NET.Sdk">
(sem o .Web à direita) é usado:
O aviso a seguir é gerado:
Aviso NU1604: a dependência de projeto Microsoft.AspNetCore.App não tem um
limite inferior inclusivo. Inclua um limite inferior na versão de dependência para
garantir resultados consistentes de restauração.
Esse é um problema conhecido com o SDK do .NET Core 2.1 e será corrigido no SDK
do .NET Core 2.2.
Atualizar o ASP.NET Core

O Microsoft.AspNetCore.App metapacote não é um pacote tradicional atualizado do NuGet.
Semelhante ao Microsoft.NETCore.App , Microsoft.AspNetCore.App representa um tempo de
execução compartilhado, que tem semântica de controle de versão especial tratada fora do
NuGet. Para obter mais informações, veja Pacotes, metapacotes e estruturas.
Para atualizar o ASP.NET Core:
Em computadores de desenvolvimento e servidores de compilação: baixe e instale o SDK
do .NET Core.
Nos servidores de implantação: baixe e instale o tempo de execução do .NET Core.
Os aplicativos efetuarão roll forward para a versão mais recente instalada na reinicialização do
aplicativo. Não é necessário atualizar o número de versão Microsoft.AspNetCore.App no
arquivo de projeto. Para obter mais informações, consulte Roll forward de aplicativos
dependentes de estrutura.
Se seu aplicativo tiver usado Microsoft.AspNetCore.All , veja Migração do
Microsoft.AspNetCore.All para Microsoft.AspNetCore.App.
Metapacote Microsoft.AspNetCore.All para
ASP.NET Core 2.0
NOTE
Recomendamos que os aplicativos direcionados ao ASP.NET Core 2.1 e posterior usem o metapacote
Microsoft.AspNetCore.App em vez desse pacote. Veja Migração do Microsoft.AspNetCore.All para
Microsoft.AspNetCore.App neste artigo.
Este recurso exige o ASP.NET Core 2.x direcionado ao .NET Core 2.x.
O Metapacote do Microsoft.AspNetCore.All para ASP.NET Core inclui:
Todos os pacotes com suporte da equipe do ASP.NET Core.
Todos os pacotes com suporte pelo Entity Framework Core.
Dependências internas e de terceiros usadas por ASP.NET Core e pelo Entity Framework Core.
Todos os recursos do ASP.NET Core 2.x e do Entity Framework Core 2.x são incluídos no pacote
Microsoft.AspNetCore.All . Os modelos de projeto padrão direcionados para ASP.NET Core 2.0 usam
este pacote.
O número de versão do metapacote Microsoft.AspNetCore.All representa a versão do ASP.NET Core e a
versão do Entity Framework Core.
Aplicativos que usam o metapacote Microsoft.AspNetCore.All aproveitam automaticamente o novo
Repositório de Tempo de Execução do .NET Core. O Repositório de Tempo de Execução contém todos os
ativos de tempo de execução necessários para executar aplicativos ASP.NET Core 2.x. Quando você usa o
metapacote Microsoft.AspNetCore.All , nenhum ativo dos pacotes NuGet do ASP.NET Core
referenciados é implantado com o aplicativo —, porque o Repositório de Tempo de Execução do .NET
Core contém esse ativos. Os ativos no Repositório de Tempo de Execução são pré-compilados para
melhorar o tempo de inicialização do aplicativo.
Use o processo de filtragem de pacote para remover os pacotes não utilizados. Pacotes filtrados são
excluídos na saída do aplicativo publicado.
O seguinte arquivo .csproj referencia os metapacotes Microsoft.AspNetCore.All para o ASP.NET Core:
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
</Project>
Controle de versão implícita

No ASP.NET Core 2.1 ou posterior, você pode especificar a referência de pacote
Microsoft.AspNetCore.All sem uma versão. Quando a versão não for especificada, uma versão implícita
será especificada pelo SDK ( Microsoft.NET.Sdk.Web ). Recomendamos que você conte com a versão
implícita especificada pelo SDK, e não defina explicitamente o número de versão na referência de pacote.
Caso tenha dúvidas sobre essa abordagem, deixe um comentário no GitHub na Discussion for the
Microsoft.AspNetCore.App implicit version (Discussão sobre a versão implícita do
Microsoft.AspNetCore.App).
A versão implícita é definida como major.minor.0 para aplicativos portátil. O mecanismo de roll forward
da estrutura compartilhada executará o aplicativo na versão compatível mais recente entre as estruturas
compartilhadas instaladas. Para garantir que a mesma versão seja usada no desenvolvimento, no teste e
na produção, certifique-se de que a mesma versão da estrutura compartilhada seja instalada em todos os
ambientes. Para aplicativos autossuficientes, o número de versão implícita é definido como o
major.minor.patch da estrutura compartilhada agrupada no SDK instalado.
A especificação de um número de versão na referência de pacote Microsoft.AspNetCore.All não

assegura que a versão da estrutura compartilhada será escolhida. Por exemplo, suponha que a versão
"2.1.1" foi especificada, mas "2.1.3" está instalada. Nesse caso, o aplicativo usará "2.1.3". Embora não seja
recomendado, você pode desabilitar o roll forward (patch e/ou secundária). Para obter mais informações
sobre como efetuar roll forward do host dotnet e como configurar seu comportamento, veja Efetuar roll
forward do host dotnet.
O SDK do projeto precisa ser definido como Microsoft.NET.Sdk.Web no arquivo de projeto para usar a
versão implícita do Microsoft.AspNetCore.All . Quando o SDK Microsoft.NET.Sdk for especificado (
<Project Sdk="Microsoft.NET.Sdk"> na parte superior do arquivo de projeto), o seguinte aviso será
gerado:
Aviso NU1604: a dependência do projeto Microsoft.AspNetCore.All não contém um limite inferior
inclusivo. Inclua um limite inferior na versão de dependência para garantir resultados consistentes de
restauração.
Esse é um problema conhecido com o SDK do .NET Core 2.1 e será corrigido no SDK do .NET Core 2.2.
Migração do Microsoft.AspNetCore.All para

Os pacotes a seguir estão incluídos no Microsoft.AspNetCore.All , mas não no pacote
Microsoft.AspNetCore.App .
Microsoft.AspNetCore.ApplicationInsights.HostingStartup
Microsoft.AspNetCore.AzureAppServices.HostingStartup
Microsoft.AspNetCore.AzureAppServicesIntegration
Microsoft.AspNetCore.DataProtection.AzureKeyVault
Microsoft.AspNetCore.DataProtection.AzureStorage
Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv
Microsoft.AspNetCore.SignalR.Redis
Microsoft.Data.Sqlite
Microsoft.Data.Sqlite.Core
Microsoft.EntityFrameworkCore.Sqlite
Microsoft.EntityFrameworkCore.Sqlite.Core
Microsoft.Extensions.Caching.Redis
Microsoft.Extensions.Configuration.AzureKeyVault
Microsoft.Extensions.Logging.AzureAppServices
Microsoft.VisualStudio.Web.BrowserLink
Para mover de Microsoft.AspNetCore.All para Microsoft.AspNetCore.App , se seu aplicativo usa APIs dos
pacotes acima ou de pacotes trazidos por eles, adicione referências a eles em seu projeto.
Todas as dependências dos pacotes anteriores que, de outra forma, não são dependências de
Microsoft.AspNetCore.App não são incluídas implicitamente. Por exemplo:
StackExchange.Redis como uma dependência de Microsoft.Extensions.Caching.Redis

Microsoft.ApplicationInsights como uma dependência de
Microsoft.AspNetCore.ApplicationInsights.HostingStartup
Atualizar o ASP.NET Core 2.1

É recomendável migrar para o metapacote Microsoft.AspNetCore.App para a versão 2.1 e posteriores.
Para continuar usando o metapacote Microsoft.AspNetCore.All e certificar-se de que a versão de patch
mais recente foi implantada:
Em computadores de desenvolvimento e em servidores de build: instale o SDK do .NET Core mais
recente.
Nos servidores de implantação: instale o tempo de execução do .NET Core mais recente. Seu
aplicativo efetuará roll forward para a versão instalada mais recente em uma reinicialização do
aplicativo.
Registro em log de alto desempenho com o
LoggerMessage no ASP.NET Core
Por Luke Latham

Os recursos do LoggerMessage criam delegados armazenáveis em cache que exigem menos alocações de objeto e
sobrecarga de computação reduzida em comparação aos métodos de extensão do agente, como LogInformation ,
LogDebug e LogError . Para cenários de registro em log de alto desempenho, use o padrão LoggerMessage .
LoggerMessage fornece as seguintes vantagens de desempenho em relação aos métodos de extensão do Agente:
Métodos de extensão do agente exigem tipos de valor de conversão boxing, como int , em object . O padrão
LoggerMessage evita a conversão boxing usando campos Action estáticos e métodos de extensão com
parâmetros fortemente tipados.
Os métodos de extensão do agente precisam analisar o modelo de mensagem (cadeia de caracteres de formato
nomeada) sempre que uma mensagem de log é gravada. LoggerMessage exige apenas a análise de um modelo
uma vez quando a mensagem é definida.
O aplicativo de exemplo demonstra recursos do LoggerMessage com um sistema básico de acompanhamento de
aspas. O aplicativo adiciona e exclui aspas usando um banco de dados em memória. Conforme ocorrem essas
operações, são geradas mensagens de log usando o padrão LoggerMessage .
LoggerMessage.Define
Define(LogLevel, EventId, String) cria um delegado Action para registrar uma mensagem em log. Sobrecargas de
Define permitem passar até seis parâmetros de tipo para uma cadeia de caracteres de formato nomeada
(modelo).
A cadeia de caracteres fornecida para o método Define é um modelo e não uma cadeia de caracteres interpolada.
Os espaços reservados são preenchidos na ordem em que os tipos são especificados. Os nomes do espaço
reservado no modelo devem ser descritivos e consistentes em todos os modelos. Eles servem como nomes de
propriedade em dados de log estruturado. Recomendamos o uso da formatação Pascal Case para nomes de
espaço reservado. Por exemplo, {Count} , {FirstName} .
Cada mensagem de log é uma Action mantida em um campo estático criado por LoggerMessage.Define . Por
exemplo, o aplicativo de exemplo cria um campo para descrever uma mensagem de log para uma solicitação GET
para a página de Índice (Internal/LoggerExtensions.cs):
private static readonly Action<ILogger, Exception> _indexPageRequested;
Para a Action , especifique:

O nível de log.
Um identificador de evento exclusivo (EventId) com o nome do método de extensão estático.
O modelo de mensagem (cadeia de caracteres de formato nomeada).
Uma solicitação para a página de Índice do aplicativo de exemplo define:
O nível de log como Information .
A ID do evento como 1 com o nome do método IndexPageRequested .
Modelo de mensagem (cadeia de caracteres de formato nomeada) como uma cadeia de caracteres.
_indexPageRequested = LoggerMessage.Define(
LogLevel.Information,
new EventId(1, nameof(IndexPageRequested)),
"GET request for Index page");
Repositórios de log estruturado podem usar o nome do evento quando recebem a ID do evento para enriquecer o
log. Por exemplo, Serilog usa o nome do evento.
A Action é invocada por meio de um método de extensão fortemente tipado. O método IndexPageRequested
registra uma mensagem para uma solicitação GET da página de Índice no aplicativo de exemplo:
public static void IndexPageRequested(this ILogger logger)

{
_indexPageRequested(logger, null);
}
IndexPageRequested é chamado no agente no método OnGetAsync em Pages/Index.cshtml.cs:

{
_logger.IndexPageRequested();
Quotes = await _db.Quotes.AsNoTracking().ToListAsync();

}
Inspecione a saída do console do aplicativo:
info: LoggerMessageSample.Pages.IndexModel[1]
=> RequestId:0HL90M6E7PHK4:00000001 RequestPath:/ => /Index
GET request for Index page
Para passar parâmetros para uma mensagem de log, defina até seis tipos ao criar o campo estático. O aplicativo de
exemplo registra uma cadeia de caracteres em log ao adicionar aspas definindo um tipo string para o campo
Action :
private static readonly Action<ILogger, string, Exception> _quoteAdded;
O modelo de mensagem de log do delegado recebe seus valores de espaço reservado dos tipos fornecidos. O
aplicativo de exemplo define um delegado para adicionar aspas quando o parâmetro de aspas é uma string :
_quoteAdded = LoggerMessage.Define<string>(
new EventId(2, nameof(QuoteAdded)),
"Quote added (Quote = '{Quote}')");
O método de extensão estático para adicionar aspas, QuoteAdded , recebe o valor do argumento de aspas e passa-o
para o delegado Action :
public static void QuoteAdded(this ILogger logger, string quote)
{
_quoteAdded(logger, quote, null);
}
No modelo da página de Índice (Pages/Index.cshtml.cs), QuoteAdded é chamado para registrar a mensagem em

log:
public async Task<IActionResult> OnPostAddQuoteAsync()

{
_db.Quotes.Add(Quote);
_logger.QuoteAdded(Quote.Text);
}
Inspecione a saída do console do aplicativo:
=> RequestId:0HL90M6E7PHK5:0000000A RequestPath:/ => /Index
Quote added (Quote = 'You can avoid reality, but you cannot avoid the consequences of avoiding reality.
- Ayn Rand')
O aplicativo de exemplo implementa um padrão try – catch para a exclusão de aspas. Uma mensagem
informativa é registrada em log para uma operação de exclusão bem-sucedida. Uma mensagem de erro é
registrada em log para uma operação de exclusão quando uma exceção é gerada. A mensagem de log para a
operação de exclusão sem êxito inclui o rastreamento de pilha da exceção (Internal/LoggerExtensions.cs):
private static readonly Action<ILogger, string, int, Exception> _quoteDeleted;

private static readonly Action<ILogger, int, Exception> _quoteDeleteFailed;
_quoteDeleted = LoggerMessage.Define<string, int>(

new EventId(4, nameof(QuoteDeleted)),
"Quote deleted (Quote = '{Quote}' Id = {Id})");
_quoteDeleteFailed = LoggerMessage.Define<int>(
LogLevel.Error,
new EventId(5, nameof(QuoteDeleteFailed)),
"Quote delete failed (Id = {Id})");
Observe como a exceção é passada para o delegado em QuoteDeleteFailed :
public static void QuoteDeleted(this ILogger logger, string quote, int id)
{
_quoteDeleted(logger, quote, id, null);
}
public static void QuoteDeleteFailed(this ILogger logger, int id, Exception ex)
{
_quoteDeleteFailed(logger, id, ex);
}
No modelo da página de Índice, uma exclusão de aspas bem-sucedida chama o método QuoteDeleted no agente.
Quando as aspas não são encontradas para exclusão, uma ArgumentNullException é gerada. A exceção é
interceptada pela instrução try – catch e registrada em log com uma chamada ao método QuoteDeleteFailed no
agente no bloco catch (Pages/Index.cshtml.cs):
public async Task<IActionResult> OnPostDeleteQuoteAsync(int id)

{
var quote = await _db.Quotes.FindAsync(id);
// DO NOT use this approach in production code!

// You should check quote to see if it's null before removing
// it and saving changes to the database. A try-catch is used
// here for demonstration purposes of LoggerMessage features.
try
{
_db.Quotes.Remove(quote);
_logger.QuoteDeleted(quote.Text, id);
}
catch (ArgumentNullException ex)
{
_logger.QuoteDeleteFailed(id, ex);
}
}
Quando as aspas forem excluídas com êxito, inspecione a saída do console do aplicativo:
Quote deleted (Quote = 'You can avoid reality, but you cannot avoid the consequences of avoiding
reality. - Ayn Rand' Id = 1)
Quando a exclusão de aspas falha, inspecione a saída do console do aplicativo. Observe que a exceção é incluída na
mensagem de log:
fail: LoggerMessageSample.Pages.IndexModel[5]
Quote delete failed (Id = 999)
System.ArgumentNullException: Value cannot be null.
Parameter name: entity
at Microsoft.EntityFrameworkCore.Utilities.Check.NotNull[T](T value, String parameterName)
at Microsoft.EntityFrameworkCore.DbContext.Remove[TEntity](TEntity entity)
at Microsoft.EntityFrameworkCore.Internal.InternalDbSet`1.Remove(TEntity entity)
at LoggerMessageSample.Pages.IndexModel.<OnPostDeleteQuoteAsync>d__14.MoveNext() in
<PATH>\sample\Pages\Index.cshtml.cs:line 87
LoggerMessage.DefineScope
DefineScope(String) cria um delegado Func para definir um escopo de log. Sobrecargas de DefineScope
permitem passar até três parâmetros de tipo para uma cadeia de caracteres de formato nomeada (modelo).
Como é o caso com o método Define , a cadeia de caracteres fornecida ao método DefineScope é um modelo e
não uma cadeia de caracteres interpolada. Os espaços reservados são preenchidos na ordem em que os tipos são
especificados. Os nomes do espaço reservado no modelo devem ser descritivos e consistentes em todos os
modelos. Eles servem como nomes de propriedade em dados de log estruturado. Recomendamos o uso da
formatação Pascal Case para nomes de espaço reservado. Por exemplo, {Count} , {FirstName} .
Defina um escopo de log a ser aplicado a uma série de mensagens de log usando o método DefineScope(String).
O aplicativo de exemplo tem um botão Limpar Tudo para excluir todas as aspas no banco de dados. As aspas são
excluídas com a remoção das aspas individualmente, uma por vez. Sempre que aspas são excluídas, o método
QuoteDeleted é chamado no agente. Um escopo de log é adicionado a essas mensagens de log.
Habilite IncludeScopes na seção de agente do console de appSettings.json:
{
"Logging": {
"Console": {
"IncludeScopes": true
},
"LogLevel": {
}
},
"AllowedHosts": "*"
}
Para criar um escopo de log, adicione um campo para conter um delegado Func para o escopo. O aplicativo de
exemplo cria um campo chamado _allQuotesDeletedScope (Internal/LoggerExtensions.cs):
private static Func<ILogger, int, IDisposable> _allQuotesDeletedScope;
Use DefineScope para criar o delegado. Até três tipos podem ser especificados para uso como argumentos de
modelo quando o delegado é invocado. O aplicativo de exemplo usa um modelo de mensagem que inclui o
número de aspas excluídas (um tipo int ):
_allQuotesDeletedScope = LoggerMessage.DefineScope<int>("All quotes deleted (Count = {Count})");
Forneça um método de extensão estático para a mensagem de log. Inclua os parâmetros de tipo para propriedades
nomeadas exibidos no modelo de mensagem. O aplicativo de exemplo usa uma count de aspas a ser excluída e
retorna _allQuotesDeletedScope :
public static IDisposable AllQuotesDeletedScope(this ILogger logger, int count)

{
return _allQuotesDeletedScope(logger, count);
}
O escopo encapsula as chamadas de extensão de log em um bloco using :

public async Task<IActionResult> OnPostDeleteAllQuotesAsync()
{
var quoteCount = await _db.Quotes.CountAsync();
using (_logger.AllQuotesDeletedScope(quoteCount))
{
foreach (Quote quote in _db.Quotes)
{
_db.Quotes.Remove(quote);
_logger.QuoteDeleted(quote.Text, quote.Id);
}
}
}
Inspecione as mensagens de log na saída do console do aplicativo. O seguinte resultado mostra três aspas
excluídas com a mensagem de escopo de log incluída:
=> RequestId:0HL90M6E7PHK5:0000002E RequestPath:/ => /Index => All quotes deleted (Count = 3)
Quote deleted (Quote = 'Quote 1' Id = 2)
Recursos adicionais
Registro em log
Desenvolver aplicativos ASP.NET Core usando um
observador de arquivo
Por Rick Anderson e Victor Hurdugaci

dotnet watch é uma ferramenta que executa um comando do CLI do .NET Core quando os arquivos de origem
são alterados. Por exemplo, uma alteração de arquivo pode disparar uma compilação, execução de teste ou uma
implantação.
Este tutorial usa um aplicativo de API Web existente com dois pontos de extremidade: um que retorna uma soma e
outro que retorna um produto. O método de produto tem um bug, que é corrigido neste tutorial.
Baixe o aplicativo de exemplo. Ele consiste em dois projetos: WebApp (uma API Web ASP.NET Core) e
WebAppTests (testes de unidade para a API Web).
Em um shell de comando, navegue até a pasta WebApp. Execute o seguinte comando:
dotnet run
O resultado do console mostra mensagens semelhantes à seguinte (indicando que o aplicativo está em execução e
aguarda solicitações):
$ dotnet run
Hosting environment: Development
Content root path: C:/Docs/aspnetcore/tutorials/dotnet-watch/sample/WebApp
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.
Em um navegador da Web, navegue até http://localhost:<port number>/api/math/sum?a=4&b=5 . Você deve ver o

resultado de 9 .
Navegue para o API do produto ( http://localhost:<port number>/api/math/product?a=4&b=5 ). Ele retorna 9 , não
20 , conforme o esperado. Esse problema é corrigido mais adiante no tutorial.
Adicionar dotnet watch a um projeto

A ferramenta de observador de arquivo dotnet watch está incluída com a versão 2.1.300 do SDK do .NET Core. As
etapas a seguir são necessárias ao usar uma versão anterior do SDK do .NET Core.
1. Adicionar uma referência ao pacote de Microsoft.DotNet.Watcher.Tools para o arquivo .csproj:
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.DotNet.Watcher.Tools" Version="2.0.0" />
</ItemGroup>
2. Instale o pacote Microsoft.DotNet.Watcher.Tools executando o seguinte comando:
dotnet restore
Executar os comandos da CLI do .NET Core usando dotnet watch
Qualquer comando da CLI do .NET Core pode ser executado com dotnet watch . Por exemplo:
COMANDO COMANDO COM INSPEÇÃO
dotnet run dotnet watch run
dotnet run -f netcoreapp2.0 dotnet watch run -f netcoreapp2.0
dotnet run -f netcoreapp2.0 -- --arg1 dotnet watch run -f netcoreapp2.0 -- --arg1
dotnet test dotnet watch test
Executar dotnet watch run na pasta WebApp. O resultado do console indica que watch foi iniciado.
Fazer alterações com dotnet watch

Verifique se dotnet watch está em execução.
Corrija o bug no método Product do MathController.cs para que ele retorne o produto e não a soma:
public static int Product(int a, int b)

{
return a * b;
}
Salve o arquivo. O resultado do console indica que o dotnet watch detectou uma alteração de arquivo e reiniciou o
aplicativo.
Verifique se http://localhost:<port number>/api/math/product?a=4&b=5 retorna o resultado correto.
Executar testes usando o dotnet watch

1. Altere o método Product de MathController.cs de volta para retornar a soma. Salve o arquivo.
2. Em um shell de comando, navegue até a pasta WebAppTests.
3. Execute dotnet restore.
4. Execute dotnet watch test . Seu resultado indica que um teste falhou e que o observador está aguardando
as alterações de arquivo:
Total tests: 2. Passed: 1. Failed: 1. Skipped: 0.

Test Run Failed.
5. Corrija o código do método Product para que ele retorne o produto. Salve o arquivo.
dotnet watch detecta a alteração de arquivo e executa os testes novamente. O resultado do console indica a
aprovação nos testes.
Personalizar lista de arquivos a observar

Por padrão, o dotnet-watch controla todos os arquivos que correspondem aos seguintes padrões glob:
**/*.cs
*.csproj
**/*.resx
Mais itens podem ser adicionados à lista de inspeção editando o arquivo .csproj. Os itens podem ser especificados
individualmente ou usando padrões glob.
<ItemGroup>

<Watch Include="**\*.js" Exclude="node_modules\**\*;**\*.js.map;obj\**\*;bin\**\*" />
</ItemGroup>
Recusa de arquivos a serem observados

dotnet-watch pode ser configurado para ignorar as configurações padrão. Para ignorar arquivos específicos,
adicione o atributo Watch="false" à definição de um item no arquivo .csproj:
<ItemGroup>

<Compile Include="Generated.cs" Watch="false" />


<EmbeddedResource Include="Strings.resx" Watch="false" />


<ProjectReference Include="..\ClassLibrary1\ClassLibrary1.csproj" Watch="false" />
</ItemGroup>
Projetos de inspeção personalizados

dotnet-watch não é restrito a projetos C#. Projetos de inspeção personalizados podem ser criados para lidar com
cenários diferentes. Considere o layout de projeto a seguir:
test/
UnitTests/UnitTests.csproj
IntegrationTests/IntegrationTests.csproj
Se a meta é observar ambos os projetos, crie um arquivo de projeto personalizados configurado para observar os
dois projetos:
<Project>
<ItemGroup>
<TestProjects Include="**\*.csproj" />
<Watch Include="**\*.cs" />
</ItemGroup>
<Target Name="Test">
<MSBuild Targets="VSTest" Projects="@(TestProjects)" />
</Target>
<Import Project="$(MSBuildExtensionsPath)\Microsoft.Common.targets" />

</Project>
Para iniciar a observação de arquivo em ambos os projetos, mude para a pasta de teste. Execute o seguinte
comando:
dotnet watch msbuild /t:Test
O VSTest é executado quando há qualquer mudança de arquivo no projeto de teste.
dotnet-watch no GitHub
dotnet-watch faz parte do repositório DotNetTools do GitHub.
Respostas de cache no ASP.NET Core

Saiba como armazenar dados em cache na memória no ASP.NET Core.
Saiba como usar o cache de ASP.NET Core distribuído para melhorar o desempenho e a escalabilidade do
aplicativo, especialmente em um ambiente de nuvem ou de farm de servidores.
Saiba como usar o cache de resposta para reduzir os requisitos de largura de banda e elevar o desempenho de
aplicativos ASP.NET Core.
Saiba como configurar e usar o Middleware de cache de resposta no ASP.NET Core.
Saiba como usar o Auxiliar de marca de cache.
Saiba como usar o Auxiliar de marca de cache distribuído.
Por Rick Anderson, John Luo, e Steve Smith

Noções básicas de cache

O cache pode melhorar significativamente o desempenho e a escalabilidade de um aplicativo, reduzindo o
trabalho necessário para gerar o conteúdo. O armazenamento em cache funciona melhor com dados que
raramente são alterados. O cache faz uma cópia dos dados que pode ser retornada muito mais rapidamente do
que a partir da origem. Você deve escrever e testar seu aplicativo para que ele nunca dependa de dados
armazenados em cache.
O ASP.NET Core dá suporte a vários caches diferentes. O cache mais simples se baseia o IMemoryCache, que
representa um cache armazenado na memória do servidor web. Aplicativos que são executados em um farm
de servidores devem garantir que as sessões sejam aderentes ao usar o cache na memória. Sessões aderentes
garantem que todas as solicitações subsequentes de um cliente vão para o mesmo servidor. Por exemplo, uso
de aplicativos da Web do Azure Application Request Routing (ARR ) para rotear todas as solicitações
subsequentes para o mesmo servidor.
Não adesivo sessões em um farm da web exigem uma cache distribuído para evitar problemas de consistência
de cache. Para alguns aplicativos, um cache distribuído pode dar suporte a mais alta escalabilidade horizontal
que um cache na memória. Usando um cache distribuído libera a memória de cache para um processo externo.
O cache IMemoryCache removerá entradas de cache sob pressão de memória, a menos que a prioridade de
cache seja definida como CacheItemPriority.NeverRemove . Você pode definir o CacheItemPriority para ajustar a
prioridade com que o cache remove itens sob pressão de memória.
O cache de memória pode armazenar qualquer objeto, enquanto a interface de cache distribuída é limitada a
byte[] .
System.Runtime.Caching/MemoryCache
System.Runtime.Caching/MemoryCache (Pacote do NuGet) pode ser usado com:
.NET standard 2.0 ou posterior.
Qualquer implementação do .NET que tem como alvo o .NET Standard 2.0 ou posterior. Por exemplo,
ASP.NET Core 2.0 ou posterior.
.NET framework 4.5 ou posterior.
Extensions / IMemoryCache (descrita neste tópico) é mais recomendada System.Runtime.Caching / MemoryCache
porque ele é melhor integrado ao ASP.NET Core. Por exemplo, IMemoryCache funciona nativamente com o
ASP.NET Core injeção de dependência.
Use System.Runtime.Caching / MemoryCache como uma ponte de compatibilidade ao portar código do ASP.NET
4.x ASP.NET Core.
Diretrizes de cache
Código deveria ter sempre uma opção de fallback para buscar dados e não dependem de um valor em
cache que está sendo disponível.
O cache usa um recurso escasso, de memória. Limitar o crescimento de cache:
Fazer não usar entrada externo como chaves de cache.
Use as expirações para limitar o crescimento de cache.
Usar SetSize, tamanho e SizeLimit para limitar o tamanho do cache
Usando IMemoryCache
O cache na memória é um service que é referenciado em seu aplicativo usando injeção de dependência. Chame
AddMemoryCache em ConfigureServices :

{
{
services.AddMemoryCache();
}

{
}
}
Solicitar o IMemoryCache instância no construtor:

{
private IMemoryCache _cache;
public HomeController(IMemoryCache memoryCache)

{
_cache = memoryCache;
}
IMemoryCache requer o pacote NuGet Extensions.

IMemoryCache requer o pacote NuGet Extensions, que está disponível na Microsoft.AspNetCore.All metapacote.
IMemoryCache requer o pacote NuGet Extensions, que está disponível na metapacote Microsoft.
O seguinte código usa TryGetValue para verificar se um horário está no cache. Se não estiver armazenado em
cache um tempo, uma nova entrada é criada e adicionada ao cache com definir.
public static class CacheKeys
{
public static string Entry { get { return "_Entry"; } }
public static string CallbackEntry { get { return "_Callback"; } }
public static string CallbackMessage { get { return "_CallbackMessage"; } }
public static string Parent { get { return "_Parent"; } }
public static string Child { get { return "_Child"; } }
public static string DependentMessage { get { return "_DependentMessage"; } }
public static string DependentCTS { get { return "_DependentCTS"; } }
public static string Ticks { get { return "_Ticks"; } }
public static string CancelMsg { get { return "_CancelMsg"; } }
public static string CancelTokenSource { get { return "_CancelTokenSource"; } }
}
public IActionResult CacheTryGetValueSet()

{
DateTime cacheEntry;
// Look for cache key.

if (!_cache.TryGetValue(CacheKeys.Entry, out cacheEntry))
{
// Key not in cache, so get data.
cacheEntry = DateTime.Now;
// Set cache options.

// Keep in cache for this time, reset time if accessed.
.SetSlidingExpiration(TimeSpan.FromSeconds(3));
// Save data in cache.

_cache.Set(CacheKeys.Entry, cacheEntry, cacheEntryOptions);
}
return View("Cache", cacheEntry);

}
A hora atual e o tempo em cache são exibidos:
@model DateTime?
<div>
<h2>Actions</h2>
<ul>
<li><a asp-controller="Home" asp-action="CacheTryGetValueSet">TryGetValue and Set</a></li>
<li><a asp-controller="Home" asp-action="CacheGet">Get</a></li>
<li><a asp-controller="Home" asp-action="CacheGetOrCreate">GetOrCreate</a></li>
<li><a asp-controller="Home" asp-action="CacheGetOrCreateAsync">GetOrCreateAsync</a></li>
<li><a asp-controller="Home" asp-action="CacheRemove">Remove</a></li>
</ul>
</div>
<h3>Current Time: @DateTime.Now.TimeOfDay.ToString()</h3>

<h3>Cached Time: @(Model == null ? "No cached entry found" : Model.Value.TimeOfDay.ToString())</h3>
O valor DateTime em cache permanecerá no cache enquanto houver solicitações dentro do tempo limite (e
nenhuma remoção devido à pressão de memória). A imagem abaixo mostra a hora atual e uma hora mais
antiga recuperada do cache:
O código a seguir usa GetOrCreate e GetOrCreateAsync para fazer o cache dos dados.
public IActionResult CacheGetOrCreate()

{
var cacheEntry = _cache.GetOrCreate(CacheKeys.Entry, entry =>
{
entry.SlidingExpiration = TimeSpan.FromSeconds(3);
return DateTime.Now;
});

}
public async Task<IActionResult> CacheGetOrCreateAsync()

{
var cacheEntry = await
_cache.GetOrCreateAsync(CacheKeys.Entry, entry =>
{
entry.SlidingExpiration = TimeSpan.FromSeconds(3);
return Task.FromResult(DateTime.Now);
});

}
O código a seguir chama o método Get para buscar a hora em cache:
public IActionResult CacheGet()

{
var cacheEntry = _cache.Get<DateTime?>(CacheKeys.Entry);
}
Ver métodos IMemoryCache e CacheExtensions métodos para obter uma descrição dos métodos de cache.
MemoryCacheEntryOptions
O exemplo a seguir:
Define o tempo de expiração absoluta. Isso é o tempo máximo que a entrada pode ser armazenado em
cache e impede que o item se torne muito desatualizado quando a expiração deslizante continuamente é
renovada.
Define um tempo de expiração deslizante. Solicitações que acessam esse item em cache redefinirá o relógio
de expiração deslizante.
Define a prioridade de cache para CacheItemPriority.NeverRemove .
Define uma PostEvictionDelegate que será chamado depois que a entrada é removida do cache. O retorno
de chamada é executado em um thread diferente do código que remove o item do cache.
public IActionResult CreateCallbackEntry()

{
// Pin to cache.
.SetPriority(CacheItemPriority.NeverRemove)
// Add eviction callback
.RegisterPostEvictionCallback(callback: EvictionCallback, state: this);
_cache.Set(CacheKeys.CallbackEntry, DateTime.Now, cacheEntryOptions);
return RedirectToAction("GetCallbackEntry");
}
public IActionResult GetCallbackEntry()

{
return View("Callback", new CallbackViewModel
{
CachedTime = _cache.Get<DateTime?>(CacheKeys.CallbackEntry),
Message = _cache.Get<string>(CacheKeys.CallbackMessage)
});
}
public IActionResult RemoveCallbackEntry()

{
_cache.Remove(CacheKeys.CallbackEntry);
return RedirectToAction("GetCallbackEntry");
}
private static void EvictionCallback(object key, object value,

EvictionReason reason, object state)
{
var message = $"Entry was evicted. Reason: {reason}.";
((HomeController)state)._cache.Set(CacheKeys.CallbackMessage, message);
}
Usar SetSize, tamanho e SizeLimit para limitar o tamanho do cache

Um MemoryCache instância pode, opcionalmente, especificar e impor um limite de tamanho. O limite de
tamanho de memória não tem uma unidade de medida de definido porque o cache não tem nenhum
mecanismo para medir o tamanho de entradas. Se o limite de tamanho de memória de cache for definido,
todas as entradas devem especificar o tamanho. O tamanho especificado está em unidades que o
desenvolvedor optar por.
Por exemplo:
Se o aplicativo web foi principalmente cache de cadeias de caracteres, cada tamanho de entrada de cache
pode ser o comprimento da cadeia de caracteres.
O aplicativo pode especificar o tamanho de todas as entradas como 1 e o limite de tamanho é a contagem
de entradas.
O código a seguir cria um sem unidade tamanho fixo MemoryCache acessível pelo injeção de dependência:
// using Microsoft.Extensions.Caching.Memory;
public class MyMemoryCache
{
public MemoryCache Cache { get; set; }
public MyMemoryCache()
{
Cache = new MemoryCache(new MemoryCacheOptions
{
SizeLimit = 1024
});
}
}
SizeLimit não tem unidades. As entradas em cache devem especificar o tamanho em qualquer unidade que
consideram mais apropriados se o tamanho da memória de cache tiver sido definido. Todos os usuários de
uma instância de cache devem usar a mesma unidade de sistema. Uma entrada não será armazenada, se a
soma dos tamanhos da entrada armazenada em cache excede o valor especificado pelo SizeLimit . Se nenhum
limite de tamanho do cache for definido, o tamanho do cache definida na entrada será ignorado.
O código a seguir registra MyMemoryCache com o injeção de dependência contêiner.

{
services.AddSingleton<MyMemoryCache>();
}
MyMemoryCache é criado como um cache de memória independentes para os componentes que reconhecem
esse cache de tamanho limitado e saber como definir o tamanho do cache de entrada adequadamente.
O seguinte código usa MyMemoryCache :
{
private MemoryCache _cache;
public static readonly string MyKey = "_MyKey";
public AboutModel(MyMemoryCache memoryCache)

{
_cache = memoryCache.Cache;
}
[TempData]
public string DateTime_Now { get; set; }

{
if (!_cache.TryGetValue(MyKey, out string cacheEntry))
{
cacheEntry = DateTime.Now.TimeOfDay.ToString();

// Set cache entry size by extension method.
.SetSize(1)
// Set cache entry size via property.

// cacheEntryOptions.Size = 1;

_cache.Set(MyKey, cacheEntry, cacheEntryOptions);
}
DateTime_Now = cacheEntry;
}
}
O tamanho da entrada de cache pode ser definido tamanho ou o SetSize método de extensão:
{
if (!_cache.TryGetValue(MyKey, out string cacheEntry))
{
cacheEntry = DateTime.Now.TimeOfDay.ToString();

// Set cache entry size by extension method.
.SetSize(1)
// Set cache entry size via property.

// cacheEntryOptions.Size = 1;

_cache.Set(MyKey, cacheEntry, cacheEntryOptions);
}
DateTime_Now = cacheEntry;
}
Dependências de cache
O exemplo a seguir mostra como expirar uma entrada de cache, se uma entrada dependente expira. Um
CancellationChangeToken é adicionado ao item em cache. Quando Cancel é chamado de
CancellationTokenSource , ambas as entradas de cache são removidas.
public IActionResult CreateDependentEntries()
{
var cts = new CancellationTokenSource();
_cache.Set(CacheKeys.DependentCTS, cts);
using (var entry = _cache.CreateEntry(CacheKeys.Parent))

{
// expire this entry if the dependant entry expires.
entry.Value = DateTime.Now;
entry.RegisterPostEvictionCallback(DependentEvictionCallback, this);
_cache.Set(CacheKeys.Child,
DateTime.Now,
new CancellationChangeToken(cts.Token));
}
return RedirectToAction("GetDependentEntries");
}
public IActionResult GetDependentEntries()

{
return View("Dependent", new DependentViewModel
{
ParentCachedTime = _cache.Get<DateTime?>(CacheKeys.Parent),
ChildCachedTime = _cache.Get<DateTime?>(CacheKeys.Child),
Message = _cache.Get<string>(CacheKeys.DependentMessage)
});
}
public IActionResult RemoveChildEntry()

{
_cache.Get<CancellationTokenSource>(CacheKeys.DependentCTS).Cancel();
return RedirectToAction("GetDependentEntries");
}
private static void DependentEvictionCallback(object key, object value,

EvictionReason reason, object state)
{
var message = $"Parent entry was evicted. Reason: {reason}.";
((HomeController)state)._cache.Set(CacheKeys.DependentMessage, message);
}
Usando um CancellationTokenSource permite que várias entradas de cache a ser removido como um grupo.
Com o using padrão no código acima, as entradas de cache criado dentro de using bloco herdará as
configurações de expiração e gatilhos.
Observações adicionais
Ao usar um retorno de chamada para preencher novamente um item de cache:
Várias solicitações podem localizar o valor da chave em cache vazio porque o retorno de chamada
não foi concluído.
Isso pode resultar em vários threads repopulação o item em cache.
Quando uma entrada de cache é usada para criar outro, o filho copia a entrada de pai tokens de
expiração e as configurações de expiração com base no tempo. O filho não está expirada pela remoção
manual ou a atualização da entrada pai.
Use PostEvictionCallbacks para definir os retornos de chamada que serão acionados depois que a
entrada de cache é removida do cache.
Recursos adicionais
Detectar alterações com tokens de alteração no ASP.NET Core

Um cache distribuído é um cache compartilhado por vários servidores de aplicativo, normalmente é
mantidos como um serviço externo para os servidores de aplicativo que acessá-lo. Um cache distribuído
pode melhorar o desempenho e escalabilidade de um aplicativo ASP.NET Core, especialmente quando o
aplicativo é hospedado por um serviço de nuvem ou um farm de servidores.
Um cache distribuído tem várias vantagens sobre outros cenários de cache onde os dados armazenados em
cache são armazenados em servidores de aplicativos individuais.
Quando os dados armazenados em cache são distribuídos, os dados:
Está coerente (consistente) em todas as solicitações para vários servidores.
Sobrevive a reinicializações do servidor e as implantações de aplicativo.
Não use memória local.
Configuração de cache distribuído é específico da implementação. Este artigo descreve como configurar o
SQL Server e distribuídos caches Redis. Implementações de terceiros também estão disponíveis, como
NCache (NCache no GitHub). Independentemente de qual implementação for selecionada, o aplicativo
interage com o cache usando o IDistributedCache interface.
Pré-requisitos
Para usar um SQL Server distributed cache, a referência a metapacote do Microsoft ou adicionar uma
referência de pacote para o Microsoft.Extensions.Caching.SqlServer pacote.
Para usar um Redis distributed cache, a referência a metapacote do Microsoft e adicione uma referência de
pacote para o Microsoft.Extensions.Caching.Redis pacote. O pacote do Redis não está incluído no
Microsoft.AspNetCore.App empacotar, portanto, você deve referenciar o pacote de Redis separadamente no
seu arquivo de projeto.
Para usar um SQL Server distributed cache, a referência a metapacote Microsoft.AspNetCore.All ou
adicionar uma referência de pacote para o Microsoft.Extensions.Caching.SqlServer pacote.
Para usar um Redis distributed cache, a referência a metapacote Microsoft.AspNetCore.All ou adicionar uma
referência de pacote para o Microsoft.Extensions.Caching.Redis pacote. O pacote de Redis está incluído no
Microsoft.AspNetCore.All empacotar, para que você não precisa fazer referência ao pacote Redis
separadamente no seu arquivo de projeto.
Para usar um SQL Server distributed cache, adicione uma referência de pacote para o
Microsoft.Extensions.Caching.SqlServer pacote.
Para usar um Redis cache distribuído, adicione uma referência de pacote para o
Microsoft.Extensions.Caching.Redis pacote.
Interface IDistributedCache
O IDistributedCache interface fornece os seguintes métodos para manipular itens na implementação de
cache distribuído:
Get, GetAsync – Aceita uma chave de cadeia de caracteres e recupera um item em cache como um
byte[] matriz se encontrada no cache.
Set, SetAsync – Adiciona um item (como byte[] matriz) para o cache usando uma chave de cadeia de
caracteres.
Refresh, RefreshAsync – Atualiza um item no cache com base em sua chave, redefinindo seu tempo limite
de expiração deslizante (se houver).
Remove, RemoveAsync – Remove um item de cache com base em sua chave de cadeia de caracteres.
Estabeleça serviços de cache distribuídos

Registrar uma implementação de IDistributedCache em Startup.ConfigureServices . Implementações
fornecidos pela estrutura descritas neste tópico incluem:
Cache de memória distribuída
Cache distribuído do SQL Server
Cache distribuído do Redis
Cache de memória distribuída
O Cache de memória distribuída (AddDistributedMemoryCache) é uma implementação fornecidos pela
estrutura de IDistributedCache que armazena os itens na memória. O Cache de memória distribuída não é
um cache distribuído real. Itens armazenados em cache são armazenados por instância do aplicativo no
servidor onde o aplicativo está sendo executado.
O Cache de memória distribuída é uma implementação úteis:
No desenvolvimento e cenários de teste.
Quando um único servidor é usado em consumo de memória e de produção não é um problema.
Implementar os resumos de Cache distribuído memória, armazenamento de dados em cache. Ele permite
para implementar que uma verdadeira distribuído a solução de cache no futuro se vários nós ou
tolerância a falhas que se tornar necessário.
O aplicativo de exemplo utiliza o Cache de memória distribuída quando o aplicativo é executado no ambiente
de desenvolvimento:

{
if (_hostContext.IsDevelopment())
{
}
else
{
services.AddDistributedSqlServerCache(options =>
{
options.ConnectionString =
_config["DistCache_ConnectionString"];
options.SchemaName = "dbo";
options.TableName = "TestCache";
});
}
Cache distribuído do SQL Server

A implementação de Cache distribuído do SQL Server (AddDistributedSqlServerCache) permite que o cache
distribuído usar um banco de dados do SQL Server como seu armazenamento de backup. Para criar uma
tabela de item em cache do SQL Server em uma instância do SQL Server, você pode usar o sql-cache
ferramenta. A ferramenta cria uma tabela com o nome e o esquema que você especificar.
Adicione SqlConfig.Tools para o <ItemGroup> elemento do arquivo de projeto e execute dotnet restore .
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.Extensions.Caching.SqlConfig.Tools"
Version="2.0.2" />
</ItemGroup>
Crie uma tabela no SQL Server executando o sql-cache create comando. Fornecer a instância do SQL
Server ( Data Source ), banco de dados ( Initial Catalog ), esquema (por exemplo, dbo ) e o nome da tabela
(por exemplo, TestCache ):
dotnet sql-cache create "Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=DistCache;Integrated

Security=True;" dbo TestCache
Uma mensagem é registrada para indicar que a ferramenta foi bem-sucedida:
Table and index were created successfully.
A tabela criada pelo sql-cache ferramenta tem o esquema a seguir:
NOTE
Um aplicativo deve manipular valores de cache usando uma instância de IDistributedCache, e não um SqlServerCache.
O aplicativo de exemplo implementa SqlServerCache em um ambiente de desenvolvimento não:

{
if (_hostContext.IsDevelopment())
{
}
else
{
services.AddDistributedSqlServerCache(options =>
{
options.ConnectionString =
_config["DistCache_ConnectionString"];
options.SchemaName = "dbo";
options.TableName = "TestCache";
});
}
NOTE
Um ConnectionString (e, opcionalmente, SchemaName e TableName) normalmente são armazenados fora do controle
do código-fonte (por exemplo, são armazenados pela Secret Manager ou na appSettings. JSON / appsettings. .
{Environment } JSON arquivos). A cadeia de caracteres de conexão pode conter credenciais que devem ser mantidas
fora de sistemas de controle do código-fonte.
Cache Redis distribuído

Redis é um repositório de dados na memória do código-fonte aberto, que geralmente é usado como um
cache distribuído. Você pode usar o Redis localmente, e você pode configurar uma Cache Redis do Azure
para um aplicativo ASP.NET Core hospedados no Azure. Um aplicativo configura a implementação de cache
usando um RedisCache instância (AddDistributedRedisCache):
services.AddDistributedRedisCache(options =>
{
options.Configuration = "localhost";
options.InstanceName = "SampleInstance";
});
Para instalar o Redis em seu computador local:

Instalar o Redis Chocolatey pacote.
Executar redis-server em um prompt de comando.
Usar o cache distribuído

Para usar o IDistributedCache interface, solicitar uma instância de IDistributedCache de qualquer construtor
no aplicativo. A instância é fornecida pela injeção de dependência (DI).
Quando o aplicativo é iniciado, IDistributedCache é injetado no Startup.Configure . A hora atual é
armazenado em cache usando IApplicationLifetime (para obter mais informações, consulte Host da Web:
interface IApplicationLifetime):

IApplicationLifetime lifetime, IDistributedCache cache)
{
lifetime.ApplicationStarted.Register(() =>
{
var currentTimeUTC = DateTime.UtcNow.ToString();
byte[] encodedCurrentTimeUTC = Encoding.UTF8.GetBytes(currentTimeUTC);
var options = new DistributedCacheEntryOptions()
cache.Set("cachedTimeUTC", encodedCurrentTimeUTC, options);
});
O aplicativo de exemplo injeta IDistributedCache para o IndexModel para uso pela página de índice.
Cada vez que a página de índice é carregada, o cache é verificado para o tempo em cache em OnGetAsync . Se
ainda não tiver expirado o tempo em cache, a hora é exibida. Se 20 segundos decorridos desde a última vez
em que o tempo em cache foi acessado (a última vez que esta página foi carregada), a página exibe
armazenado em cache tempo expirado.
Atualizar imediatamente o tempo em cache para a hora atual, selecionando o redefinição de tempo em
cache botão. Os gatilhos de botão a OnPostResetCachedTime método do manipulador.
{
private readonly IDistributedCache _cache;
public IndexModel(IDistributedCache cache)

{
_cache = cache;
}
public string CachedTimeUTC { get; set; }

{
CachedTimeUTC = "Cached Time Expired";
var encodedCachedTimeUTC = await _cache.GetAsync("cachedTimeUTC");
if (encodedCachedTimeUTC != null)
{
CachedTimeUTC = Encoding.UTF8.GetString(encodedCachedTimeUTC);
}
}
public async Task<IActionResult> OnPostResetCachedTime()

{
var currentTimeUTC = DateTime.UtcNow.ToString();
byte[] encodedCurrentTimeUTC = Encoding.UTF8.GetBytes(currentTimeUTC);
var options = new DistributedCacheEntryOptions()
await _cache.SetAsync("cachedTimeUTC", encodedCurrentTimeUTC, options);
}
}
NOTE
Não é necessário usar um tempo de vida Singleton ou com escopo para IDistributedCache instâncias (pelo menos
para as implementações internas).
Você também pode criar uma IDistributedCache da instância onde você pode precisar de uma em vez de usar a DI,
mas a criação de uma instância no código pode tornar seu código mais difícil de testar e viola o princípio de
dependências explícitas.
Recomendações
Ao decidir qual implementação de IDistributedCache é melhor para seu aplicativo, considere o seguinte:
Infraestrutura existente
Requisitos de desempenho
Custo
Experiência da equipe
Soluções de cache normalmente se baseiam em armazenamento na memória para fornecer recuperação
rápida de dados armazenados em cache, mas a memória é um recurso limitado e caros expandir. Loja apenas
dados usados normalmente em um cache.
Em geral, um cache Redis fornece maior taxa de transferência e latência mais baixa que o cache de SQL
Server. No entanto, é geralmente necessário para determinar as características de desempenho de
estratégias de cache de benchmark.
Quando o SQL Server é usado como um armazenamento de backup de cache distribuído, usar o mesmo
banco de dados para o cache e armazenamento de dados comum do aplicativo e recuperação pode afetar
negativamente o desempenho de ambos. É recomendável usar uma instância dedicada do SQL Server para o
cache distribuído do repositório de backup.
Recursos adicionais
Redis Cache no Azure
Banco de dados SQL no Azure
Provedor de IDistributedCache para NCache nos Farms da Web do ASP.NET Core (NCache no GitHub)
Por John Luo, Rick Anderson, Steve Smith, e Luke Latham
NOTE
Cache de resposta nas páginas do Razor está disponível no ASP.NET Core 2.1 ou posterior.

O cache das respostas reduz o número de solicitações de que um cliente ou proxy faz a um servidor web. Cache
de resposta também reduz a quantidade de trabalho do servidor web executa para gerar uma resposta. Cache de
resposta é controlado por cabeçalhos que especificam como deseja cliente, o proxy e middleware para respostas
em cache.
O servidor web pode armazenar em cache as respostas quando você adiciona Middleware de cache de resposta.
Cache de resposta baseado em HTTP

O especificação de cache do HTTP 1.1 descreve como caches de Internet devem se comportar. É o cabeçalho
HTTP principal usado para armazenar em cache Cache-Control, que é usada para especificar o cache diretivas. As
diretivas de controlam o comportamento de cache conforme as solicitações cheguem de clientes para servidores
e respostas passarão de servidores de volta aos clientes. Solicitações e respostas movem através de servidores
proxy e servidores proxy devem também estar em conformidade com a especificação de cache do HTTP 1.1.
Common Cache-Control diretivas são mostradas na tabela a seguir.
DIRETIVA AÇÃO
public Um cache pode armazenar a resposta.
private A resposta não deve ser armazenada por um cache

compartilhado. Um cache privado pode armazenar e reutilizar
a resposta.
max-age O cliente não aceitará uma resposta cuja idade é maior que o
número especificado de segundos. Exemplos: max-age=60
(60 segundos), max-age=2592000 (1 mês)
no-cache Em solicitações: um cache não deve usar uma resposta

armazenada para atender à solicitação. Observação: O
servidor de origem gera novamente a resposta para o cliente
e o middleware atualiza a resposta armazenada em seu cache.
Nas respostas: A resposta não deve ser usada para uma

solicitação subsequente sem validação no servidor de origem.
no-store Em solicitações: um cache não deve armazenar a solicitação.
Nas respostas: um cache não deve armazenar qualquer

parte da resposta.
Outros cabeçalhos de cache que desempenham uma função em cache são mostrados na tabela a seguir.
CABEÇALHO FUNÇÃO
Idade Uma estimativa da quantidade de tempo em segundos desde

a resposta foi gerada ou validada com êxito no servidor de
origem.
Expira A data/hora após o qual a resposta é considerada obsoleta.
Pragma Existe para com versões anteriores a compatibilidade com o

HTTP/1.0 armazena em cache para a configuração no-cache
comportamento. Se o Cache-Control cabeçalho estiver
presente, o Pragma cabeçalho será ignorado.
Variar Especifica que uma resposta em cache não deve ser enviada,
a menos que todos os do Vary correspondem de campos
de cabeçalho na solicitação original da resposta em cache e a
nova solicitação.
As diretivas de controle de Cache de solicitação de aspectos de cache

baseada em HTTP
O especificação de cache do HTTP 1.1 para o cabeçalho Cache-Control requer um cache para honrar válido
Cache-Control cabeçalho enviado pelo cliente. Um cliente pode fazer solicitações com um no-cache força o
servidor gere uma nova resposta para cada solicitação e o valor do cabeçalho.
Respeitando sempre cliente Cache-Control cabeçalhos de solicitação faz sentido se você considerar o objetivo do
cache de HTTP. Sob a especificação oficial, cache destina-se para reduzir a sobrecarga de rede e latência de
satisfazer as solicitações em uma rede de clientes, proxies e servidores. Ele não é necessariamente uma maneira
de controlar a carga em um servidor de origem.
Não há nenhum controle atual do desenvolvedor sobre esse comportamento de cache ao usar o Middleware de
cache de resposta porque o middleware adere à especificação de cache oficial. Aperfeiçoamentos futuros para o
middleware permitirá que a configuração do middleware de para ignorar uma solicitação Cache-Control
cabeçalho ao decidir servir uma resposta em cache. Isso oferecerá uma oportunidade de controlar melhor a
carga no servidor quando você usa o middleware.
Outra tecnologia de armazenamento em cache no ASP.NET Core

Cache na memória
Cache na memória usa a memória do servidor para armazenar dados armazenados em cache. Esse tipo de cache
é adequado para um único servidor ou vários servidores usando sessões adesivas. Sessões adesivas significa que
as solicitações de um cliente sejam sempre roteadas para o mesmo servidor para processamento.
Para obter mais informações, consulte armazenar em Cache na memória.
Cache distribuído
Use um cache distribuído para armazenar dados na memória quando o aplicativo é hospedado em um farm de
servidor ou de nuvem. O cache é compartilhado entre os servidores que processam solicitações. Um cliente pode
enviar uma solicitação que é tratada por qualquer servidor no grupo se os dados armazenados em cache para o
cliente estão disponíveis. ASP.NET Core oferece o SQL Server e os caches distribuído do Redis.
Para obter mais informações, consulte O cache no ASP.NET Core distribuído.
Auxiliar de marca de cache
Você pode armazenar em cache o conteúdo de uma exibição MVC ou a página do Razor com o auxiliar de marca
de Cache. O auxiliar de marca de Cache usa o cache na memória para armazenar dados.
Para obter mais informações, consulte auxiliar de marca de Cache no ASP.NET Core MVC.
Auxiliar de Marca de Cache Distribuído
Você pode armazenar em cache o conteúdo de uma exibição MVC ou a página do Razor em nuvem distribuído
ou cenários de web farm com o auxiliar de marca de Cache distribuído. O auxiliar de marca de Cache distribuído
usa o SQL Server ou do Redis para armazenar dados.
Para obter mais informações, consulte auxiliar de marca de Cache distribuído.
Atributo ResponseCache
O ResponseCacheAttribute Especifica os parâmetros necessários para a configuração de cabeçalhos apropriados
no cache de resposta.
WARNING
Desabilite o cache para o conteúdo que contém informações para clientes autenticados. Armazenamento em cache deve ser
habilitado apenas para conteúdo que não são alteradas com base na identidade do usuário ou se um usuário está
conectado.
VaryByQueryKeys a resposta armazenada de varia de acordo com os valores de determinada lista de chaves de
consulta. Quando um valor único de * é fornecido, o middleware varia as respostas de todos os parâmetros de
cadeia de caracteres de consulta de solicitação. VaryByQueryKeys exige o ASP.NET Core 1.1 ou posterior.
O Middleware de cache de resposta deve ser habilitado para definir o VaryByQueryKeys propriedade; caso
contrário, uma exceção de tempo de execução é gerada. Não há um cabeçalho HTTP correspondente para o
VaryByQueryKeys propriedade. A propriedade é um recurso HTTP tratado pelo Middleware de cache de resposta.
Para o middleware servir uma resposta em cache, a cadeia de caracteres de consulta e o valor de cadeia de
caracteres de consulta devem corresponder com uma solicitação anterior. Por exemplo, considere a sequência de
solicitações e os resultados mostrados na tabela a seguir.
SOLICITAÇÃO RESULTADO
http://example.com?key1=value1 Retornado do servidor
http://example.com?key1=value1 Retornado de middleware
http://example.com?key1=value2 Retornado do servidor
A primeira solicitação é retornada pelo servidor e armazenados em cache no middleware. A segunda solicitação é
retornada pelo middleware, como a cadeia de caracteres de consulta corresponde a solicitação anterior. A terceira
solicitação não está no cache do middleware porque o valor de cadeia de caracteres de consulta não corresponde
a uma solicitação anterior.
O ResponseCacheAttribute é usado para configurar e criar (via IFilterFactory ) uma ResponseCacheFilter. O
ResponseCacheFilter realiza o trabalho de atualização de cabeçalhos HTTP apropriados e recursos da resposta. O
filtro:
Remove qualquer cabeçalho existente para Vary , Cache-Control , e Pragma .
Grava os cabeçalhos apropriados com base nas propriedades definidas ResponseCacheAttribute .
Atualiza a resposta de armazenamento em cache o recurso HTTP se VaryByQueryKeys está definido.
Variar
Esse cabeçalho só será gravado quando o VaryByHeader propriedade está definida. Ele é definido como o Vary
valor da propriedade. O exemplo a seguir usa o VaryByHeader propriedade:
[ResponseCache(VaryByHeader = "User-Agent", Duration = 30)]

public IActionResult About2()
{
[ResponseCache(VaryByHeader = "User-Agent", Duration = 30)]

public IActionResult About2()
{
Você pode exibir os cabeçalhos de resposta com as ferramentas de rede do seu navegador. A imagem a seguir
mostra F12 borda de saída na rede guia quando o About2 método de ação é atualizado:
NoStore e Location.None
NoStore substitui a maioria das outras propriedades. Quando essa propriedade é definida como true ,o
Cache-Control cabeçalho é definido como no-store . Se Location é definido como None :
Cache-Control é definido como no-store,no-cache .

Pragma é definido como no-cache .
Se NoStore está false e Location é None , Cache-Control e Pragma são definidos como no-cache .
Você normalmente define NoStore para true nas páginas de erro. Por exemplo:
[ResponseCache(Location = ResponseCacheLocation.None, NoStore = true)]

{
return View();
}
[ResponseCache(Location = ResponseCacheLocation.None, NoStore = true)]
{
return View();
}
Isso resulta nos seguintes cabeçalhos:
Cache-Control: no-store,no-cache
Pragma: no-cache
Local e a duração
Para habilitar o cache, Duration deve ser definida como um valor positivo e Location deve ser Any (o padrão)
ou Client . Nesse caso, o Cache-Control cabeçalho é definido como o valor do local seguido o max-age da
resposta.
NOTE
Location da opções dos Any e Client traduzir Cache-Control valores de cabeçalho da public e private ,
respectivamente. Conforme observado anteriormente, definindo Location à None define ambas Cache-Control e
Pragma cabeçalhos para no-cache .
Veja abaixo um exemplo que mostra os cabeçalhos é produzido pela configuração Duration e deixar o padrão
Location valor:
[ResponseCache(Duration = 60)]
{
return View();
}
{
return View();
}
Isso produz o seguinte cabeçalho:
Cache-Control: public,max-age=60
Perfis de cache
Em vez de duplicar ResponseCache configurações de muitos atributos de ação do controlador, perfis de cache
podem ser configuradas como opções ao configurar o MVC em de ConfigureServices método na Startup .
Valores encontrados em um perfil de cache referenciada são usados como padrões pelo ResponseCache de
atributos e são substituídas por qualquer propriedade especificada no atributo.
Como configurar um perfil de cache:
{
{
options.CacheProfiles.Add("Default",
new CacheProfile()
{
Duration = 60
});
options.CacheProfiles.Add("Never",
new CacheProfile()
{
Location = ResponseCacheLocation.None,
NoStore = true
});
}

{
{
options.CacheProfiles.Add("Default",
new CacheProfile()
{
Duration = 60
});
options.CacheProfiles.Add("Never",
new CacheProfile()
{
Location = ResponseCacheLocation.None,
NoStore = true
});
});
}
Um perfil de cache de referência:
{
[ResponseCache(CacheProfileName = "Default")]
{
return View();
}
{
[ResponseCache(CacheProfileName = "Default")]
{
return View();
}
O ResponseCache atributo pode ser aplicado a ações (métodos) e controladores (classes). Atributos de nível de
método substituem as configurações especificadas no nível de classe de atributos.
No exemplo acima, um atributo de nível de classe especifica uma duração de 30 segundos, enquanto um atributo
de nível de método faz referência a um perfil de cache com uma duração definida como 60 segundos.
O cabeçalho resultante:
Cache-Control: public,max-age=60
Recursos adicionais
Armazena as respostas em Caches
Cache-Control
Por Luke Latham e John Luo

Este artigo explica como configurar o Middleware de cache de resposta em um aplicativo ASP.NET Core. O
middleware determina quando as respostas são armazenáveis em cache, as respostas de repositórios e
respostas de serve do cache. Para obter uma introdução ao cache de HTTP e o ResponseCache atributo, consulte
cache de resposta.
Pacote
Referência a metapacote do Microsoft ou adicionar uma referência de pacote para o
Microsoft.AspNetCore.ResponseCaching pacote.
Referência a metapacote Microsoft.AspNetCore.All ou adicionar uma referência de pacote para o
Microsoft.AspNetCore.ResponseCaching pacote.
Adicionar uma referência de pacote para o Microsoft.AspNetCore.ResponseCaching pacote.
Configuração
No Startup.ConfigureServices , adicione o middleware para a coleção de serviço.

{
{
});
services.AddResponseCaching();
services.AddMvc()
}
Configurar o aplicativo para usar o middleware com o UseResponseCaching método de extensão, que adiciona o
middleware ao pipeline de processamento da solicitação. O aplicativo de exemplo adiciona uma Cache-Control
cabeçalho à resposta que armazena em cache respostas armazenáveis em cache por até 10 segundos. O
exemplo envia uma Vary cabeçalho para configurar o middleware para servir a uma resposta em cache
somente se o Accept-Encoding cabeçalho das solicitações subsequentes corresponde da solicitação original. No
exemplo de código a seguir, CacheControlHeaderValue e HeaderNames exigir uma using instrução para o
Microsoft.Net.Http.Headers namespace.
{
{
}
else
{
app.UseHsts();
}
app.UseResponseCaching();

{
// For GetTypedHeaders, add: using Microsoft.AspNetCore.Http;
context.Response.GetTypedHeaders().CacheControl =
new Microsoft.Net.Http.Headers.CacheControlHeaderValue()
{
Public = true,
MaxAge = TimeSpan.FromSeconds(10)
};
context.Response.Headers[Microsoft.Net.Http.Headers.HeaderNames.Vary] =
new string[] { "Accept-Encoding" };
await next();
});
app.UseMvc();
}
Middleware de cache de resposta só armazena em cache as respostas do servidor que resultam em um código
de status 200 (Okey). Outras respostas, incluindo páginas de erro, são ignorados pelo middleware.
WARNING
Respostas que contêm o conteúdo para clientes autenticados devem ser marcadas como não armazenável em cache para
impedir que o middleware de armazenamento e que atende a essas respostas. Ver condições para armazenar em cache
para obter detalhes sobre como o middleware determina se uma resposta é armazenável em cache.
Opções
O middleware oferece três opções para controlar o cache de resposta.
OPÇÃO DESCRIÇÃO
UseCaseSensitivePaths Determina se as respostas são armazenadas em cache em

caminhos diferencia maiusculas de minúsculas. O valor
padrão é false .
MaximumBodySize O maior tamanho armazenáveis em cache para o corpo de

resposta em bytes. O valor padrão é 64 * 1024 * 1024
(64 MB).
OPÇÃO DESCRIÇÃO
SizeLimit O limite de tamanho para o middleware de cache de

resposta em bytes. O valor padrão é 100 * 1024 * 1024
(100 MB).
O exemplo a seguir configura o middleware para:

Respostas em cache menores ou iguais a 1.024 bytes.
Store as respostas por caminhos diferencia maiusculas de minúsculas (por exemplo, /page1 e /Page1 são
armazenadas separadamente).
services.AddResponseCaching(options =>
{
options.UseCaseSensitivePaths = true;
options.MaximumBodySize = 1024;
});
VaryByQueryKeys
Ao usar controladores de API da Web do MVC ou modelos de página de páginas do Razor, o ResponseCache
atributo especifica os parâmetros necessários para definir os cabeçalhos apropriados para o cache de resposta.
O único parâmetro do ResponseCache atributo que estritamente requer o middleware é VaryByQueryKeys , que
não corresponde a um cabeçalho HTTP real. Para obter mais informações, consulte do atributo ResponseCache.
Quando não estiver usando o ResponseCache atributo, cache de resposta pode ser variado com o
VaryByQueryKeys recurso. Use o ResponseCachingFeature diretamente do IFeatureCollection da HttpContext :
var responseCachingFeature = context.HttpContext.Features.Get<IResponseCachingFeature>();

if (responseCachingFeature != null)
{
responseCachingFeature.VaryByQueryKeys = new[] { "MyKey" };
}
Usando um único valor igual a * em VaryByQueryKeys o cache de varia de acordo com todos os parâmetros de
consulta de solicitação.
Cabeçalhos HTTP usados pelo Middleware de cache de resposta

Cache de resposta pelo middleware é configurado usando cabeçalhos HTTP.
CABEÇALHO DETALHES
Autorização A resposta não é armazenado em cache se o cabeçalho

existe.
CABEÇALHO DETALHES
Cache-Control O middleware considera somente o cache de respostas

marcadas com o public diretiva de cache. Controlar o
cache com os seguintes parâmetros:
idade máxima
max-stale†
nova min
deve revalidar
sem cache
Nenhum repositório
somente se-armazenado em cache
particulares
públicos
período máximo s
proxy-revalidate‡
†Se nenhum limite é especificado para max-stale , o
middleware não toma nenhuma ação.
‡ proxy-revalidate tem o mesmo efeito que
must-revalidate .
Para obter mais informações, consulte RFC 7231: solicitação

de diretivas de Cache-Control.
Pragma Um Pragma: no-cache cabeçalho na solicitação produz o

mesmo efeito que Cache-Control: no-cache . Esse
cabeçalho é substituído por diretivas relevantes no
Cache-Control cabeçalho, se presente. Considerado para
compatibilidade com versões anteriores com HTTP 1.0.
Set-Cookie A resposta não é armazenado em cache se o cabeçalho

existe. Qualquer middleware no pipeline de processamento
de solicitação que define um ou mais cookies impede que o
Middleware de cache de resposta de cache a resposta (por
exemplo, o provedor de TempData baseado em cookie).
Variar O Vary cabeçalho é usado para variar a resposta em cache

por outro cabeçalho. Por exemplo, armazenar em cache
respostas de codificação, incluindo o
Vary: Accept-Encoding cabeçalho, que armazena em
cache respostas para solicitações com cabeçalhos
Accept-Encoding: gzip e
Accept-Encoding: text/plain separadamente. Uma
resposta com um valor de cabeçalho de * nunca é
armazenada.
Expira Uma resposta considerada obsoleta por esse cabeçalho não

é armazenada ou recuperada, a menos que substituído por
outro Cache-Control cabeçalhos.
If-None-Match A resposta completa for atendida do cache se o valor não

for * e o ETag da resposta não coincide com nenhum
dos valores fornecidos. Caso contrário, uma resposta 304
(não modificado) é atendido.
CABEÇALHO DETALHES
If-Modified-Since Se o If-None-Match cabeçalho não estiver presente, uma

resposta completa for atendida do cache se a data de
resposta em cache é mais recente do que o valor fornecido.
Caso contrário, uma resposta 304 (não modificado) é
atendido.
Date Quando atendendo do cache, o Date cabeçalho é definido

pelo middleware se ele não foi fornecido na resposta
original.
Tamanho do conteúdo Quando atendendo do cache, o Content-Length cabeçalho

é definido pelo middleware se ele não foi fornecido na
resposta original.
Idade O Age cabeçalho enviado na resposta original será

ignorado. O middleware calcula um novo valor ao oferecer
uma resposta em cache.
Armazenamento em cache respeita as diretivas de solicitação de

Cache-Control
O middleware respeita as regras do especificação de cache do HTTP 1.1. As regras exigem um cache para
honrar válido Cache-Control cabeçalho enviado pelo cliente. Sob a especificação, um cliente pode fazer
solicitações com um no-cache força o servidor gere uma nova resposta para cada solicitação e o valor do
cabeçalho. Atualmente, não há nenhum controle do desenvolvedor sobre o comportamento de cache ao usar o
middleware porque o middleware segue a especificação oficial do cache.
Para obter mais controle sobre o comportamento de cache, explore outros recursos de cache do ASP.NET
Core. Confira os seguintes tópicos:
Se o comportamento de cache não é conforme o esperado, confirme que as respostas sejam armazenável em
cache e capaz de sendo servido do cache. Examine os cabeçalhos de entrada da solicitação e cabeçalhos de
saída da resposta. Habilitar registro em log para ajudar na depuração.
Ao testar e solucionar problemas de comportamento de cache, um navegador pode definir cabeçalhos de
solicitação que afetam o cache de maneira indesejada. Por exemplo, um navegador pode definir a
Cache-Control cabeçalho no-cache ou max-age=0 durante a atualização de uma página. As ferramentas a
seguir podem definir explicitamente os cabeçalhos de solicitação e são preferenciais para testes de
armazenamento em cache:
Fiddler
Postman
Condições para armazenar em cache
A solicitação deve resultar em uma resposta do servidor com um código de status 200 (Okey).
O método de solicitação deve ser GET ou HEAD.
Middleware de terminal, como Middleware de arquivo estático, não deve processar a resposta antes do
Middleware de cache de resposta.
O Authorization cabeçalho não deverá estar presente.
Cache-Control parâmetros do cabeçalho devem ser válidos, e a resposta deve ser marcada public e não
marcada private .
O Pragma: no-cache cabeçalho não deverá estar presente se o Cache-Control cabeçalho não estiver
presente, como o Cache-Control cabeçalho substitui o Pragma cabeçalho quando presentes.
O Set-Cookie cabeçalho não deverá estar presente.
Vary parâmetros do cabeçalho devem ser válido e não é igual a * .
O Content-Length valor de cabeçalho (se definido) deve corresponder ao tamanho do corpo da resposta.
O IHttpSendFileFeature não é usado.
A resposta não deve ser obsoleta conforme especificado pelo Expires cabeçalho e o max-age e s-maxage
diretivas de cache.
Buffer de resposta deve ser bem-sucedida e o tamanho da resposta deve ser menor do que o configurado
ou padrão SizeLimit .
A resposta deve ser armazenáveis em cache de acordo com o RFC 7234 especificações. Por exemplo, o
no-store diretiva não deve existir nos campos de cabeçalho de solicitação ou resposta. Ver seção 3:
armazenar respostas em Caches dos RFC 7234 para obter detalhes.
NOTE
O sistema Antifalsificação para gerar tokens de seguras para evitar a falsificação de solicitação entre sites (CSRF) attacks
conjuntos a Cache-Control e Pragma cabeçalhos para no-cache para que as respostas não são armazenadas em
cache. Para obter informações sobre como desabilitar tokens antifalsificação para elementos de formulário HTML,
consulte configuração antifalsificação do ASP.NET Core.
Recursos adicionais
Compactação de resposta no ASP.NET Core
Por Luke Latham

Largura de banda de rede é um recurso limitado. Reduzindo o tamanho da resposta geralmente aumenta a
capacidade de resposta de um aplicativo, muitas vezes drasticamente. É uma maneira de reduzir os tamanhos do
conteúdo compactar respostas do aplicativo.
Quando usar o Middleware de compactação de resposta

Use as tecnologias de compactação de resposta com base em servidor no IIS, Apache ou Nginx. O desempenho
do middleware provavelmente não corresponderá dos módulos de servidor. Servidor HTTP. sys e Kestrel
atualmente não oferecem suporte à compactação interna.
Use o Middleware de compactação de resposta quando você estiver:
Não é possível usar as seguintes tecnologias de compactação baseada em servidor:
Módulo de compactação dinâmica do IIS
Módulo do Apache mod_deflate
Nginx compactação e descompactação
Hospedagem diretamente em:
Servidor HTTP. sys (anteriormente chamado WebListener)
Kestrel
Compactação de resposta
Geralmente, nenhuma resposta compactada nativamente não pode se beneficiar da compactação de resposta. As
respostas não nativamente compactadas normalmente incluem: CSS, JavaScript, HTML, XML e JSON. Você não
deve compactar os ativos nativamente compactados, como arquivos PNG. Se você tentar compactar ainda mais
uma resposta compactada nativamente, qualquer redução adicional pequena em tempo de tamanho e a
transmissão será provavelmente ser superada pelo tempo levado para processar a compactação. Não compacte
arquivos menores do que cerca de 150 e 1000 bytes (dependendo do conteúdo do arquivo e a eficiência da
compactação). A sobrecarga de compactação de arquivos pequenos pode produzir um arquivo compactado maior
do que o arquivo descompactado.
Quando um cliente pode processar o conteúdo compactado, o cliente deve informar o servidor de seus recursos,
enviando o Accept-Encoding cabeçalho com a solicitação. Quando um servidor envia o conteúdo compactado, ele
deve incluir informações no Content-Encoding cabeçalho em como a resposta compactada é codificada. Conteúdo
designações de codifica com suporte pelo middleware são mostradas na tabela a seguir.
ACCEPT-ENCODING VALORES DE CABEÇALHO MIDDLEWARE COM SUPORTE DESCRIÇÃO
br Sim (padrão) Formato de dados compactados Brotli
deflate Não Formato de dados compactados

DEFLATE
exi Não Intercâmbio de eficiente de XML do

W3C
gzip Sim Formato de arquivo gzip
identity Sim Identificador "Nenhuma codificação": A

resposta não deve ser codificada.
pack200-gzip Não Formato de transferência de rede para

arquivos mortos de Java
* Sim Qualquer conteúdo disponível não

codificação explicitamente solicitada
br Não Formato de dados compactados Brotli
deflate Não Formato de dados compactados

DEFLATE
exi Não Intercâmbio de eficiente de XML do

W3C
gzip Sim (padrão) Formato de arquivo gzip
identity Sim Identificador "Nenhuma codificação": A

resposta não deve ser codificada.
pack200-gzip Não Formato de transferência de rede para

arquivos mortos de Java
* Sim Qualquer conteúdo disponível não

codificação explicitamente solicitada
Para obter mais informações, consulte o IANA lista oficial de conteúdo de codificação.
O middleware permite que você adicione provedores de compactação adicional para custom Accept-Encoding
valores de cabeçalho. Para obter mais informações, consulte provedores personalizados abaixo.
O middleware é capaz de reagir a valor de qualidade (qvalue, q ) quando enviado pelo cliente para priorizar os
esquemas de compactação de ponderação. Para obter mais informações, consulte RFC 7231: codificação aceita.
Algoritmos de compactação estão sujeitos a uma compensação entre a velocidade de compactação e a eficiência
da compactação. Eficácia neste contexto refere-se ao tamanho da saída após a compactação. O menor tamanho é
obtido com a maioria ideal compactação.
Cabeçalhos envolvidas na solicitação, enviar, armazenamento em cache e receber conteúdo compactado são
descritas na tabela a seguir.
CABEÇALHO FUNÇÃO
CABEÇALHO FUNÇÃO
Accept-Encoding Enviada do cliente para o servidor para indicar a codificação

esquemas aceitáveis para o cliente de conteúdo.
Content-Encoding Enviados do servidor para o cliente para indicar a codificação

do conteúdo na carga.
Content-Length Quando ocorre a compressão, a Content-Length cabeçalho

for removido, desde que as alterações de conteúdo do corpo
quando a resposta é compactada.
Content-MD5 Quando ocorre a compressão, a Content-MD5 cabeçalho for

removido, uma vez que o conteúdo do corpo foi alterado e o
hash não é mais válido.
Content-Type Especifica o tipo MIME do conteúdo. Cada resposta deve

especificar seu Content-Type . O middleware verifica esse
valor para determinar se a resposta deve ser compactada. O
middleware Especifica um conjunto de padrão de tipos MIME
que ele pode codificar, mas você pode substituir ou adicionar
tipos MIME.
Vary Quando enviadas pelo servidor com um valor de

Accept-Encoding para clientes e proxies, o Vary cabeçalho
indica para o cliente ou um proxy que ele deve armazenar em
cache (variar) respostas com base no valor da
Accept-Encoding cabeçalho da solicitação. O resultado de
retorno de conteúdo com o Vary: Accept-Encoding
cabeçalho é que ambos compactados e descompactadas
respostas são armazenadas em cache separadamente.
Explore os recursos do Middleware de compactação de resposta com o aplicativo de exemplo. O exemplo ilustra:
A compactação de respostas do aplicativo usando o Gzip e provedores de compactação personalizado.
Como adicionar um tipo de MIME para a lista padrão de tipos MIME para compactação.
Pacote
Para incluir o middleware em um projeto, adicione uma referência para o metapacote do Microsoft, que inclui o
Microsoft.AspNetCore.ResponseCompression pacote.
Para incluir o middleware em um projeto, adicione uma referência para o metapacote Microsoft.AspNetCore.All,
que inclui o Microsoft.AspNetCore.ResponseCompression pacote.
Para incluir o middleware em um projeto, adicione uma referência para o
Microsoft.AspNetCore.ResponseCompression pacote.
Configuração
O código a seguir mostra como habilitar o Middleware de compactação de resposta para provedores de
compactação e tipos MIME padrão (Brotli e Gzip):
O código a seguir mostra como habilitar o Middleware de compactação de resposta para tipos MIME padrão e o
provedor de compactação Gzip:
{
{
services.AddResponseCompression();
}

{
app.UseResponseCompression();
}
}
NOTE
Use uma ferramenta como Fiddler, Firebug, ou Postman para definir o Accept-Encoding cabeçalho de solicitação e estudar
os cabeçalhos de resposta, o tamanho e o corpo.
Enviar uma solicitação para o aplicativo de exemplo sem o Accept-Encoding cabeçalho e observe que a resposta é
descompactada. O Content-Encoding e Vary cabeçalhos não estiverem presentes na resposta.
Enviar uma solicitação para o aplicativo de exemplo com o Accept-Encoding: br cabeçalho (a compactação Brotli)
e observe que a resposta é compactada. O Content-Encoding e Vary cabeçalhos estão presentes na resposta.
Enviar uma solicitação para o aplicativo de exemplo com o Accept-Encoding: gzip cabeçalho e observe que a
resposta é compactada. O Content-Encoding e Vary cabeçalhos estão presentes na resposta.
Provedores
Provedor de compactação Brotli
Use o BrotliCompressionProvider para compactar respostas com o formato de dados compactados Brotli.
Se nenhum provedor de compactação é adicionados explicitamente a CompressionProviderCollection:
O provedor de compactação Brotli é adicionado por padrão para a matriz de provedores de compactação
juntamente com o provedor de compactação Gzip.
Padrões de compactação para a compactação Brotli quando o formato de dados compactados Brotli é
suportado pelo cliente. Se Brotli não é suportada pelo cliente, a compactação padrão Gzip quando o cliente
oferece suporte à compactação Gzip.

{
}
O provedor de compactação Brotoli devem ser adicionado ao quaisquer provedores de compactação são
adicionados explicitamente:
{
services.AddResponseCompression(options =>
{
options.Providers.Add<BrotliCompressionProvider>();
options.Providers.Add<GzipCompressionProvider>();
options.Providers.Add<CustomCompressionProvider>();
options.MimeTypes =
ResponseCompressionDefaults.MimeTypes.Concat(
new[] { "image/svg+xml" });
});
}
Definir a compactação de nível com BrotliCompressionProviderOptions . O provedor de compactação Brotli assume

como padrão o nível de compactação mais rápido (CompressionLevel.Fastest), que não pode produzir a
compactação mais eficiente. Se a compactação mais eficiente é desejada, configure o middleware de compactação
ideal.
NÍVEL DE COMPACTAÇÃO DESCRIÇÃO
CompressionLevel.Fastest A compactação deve ser concluída assim que possível, mesmo

se a saída resultante não é compactada da maneira ideal.
CompressionLevel.NoCompression Nenhuma compactação deve ser executada.
CompressionLevel.Optimal As respostas devem ser compactadas ideal, mesmo se a

compactação leva mais tempo para concluir.

{
services.Configure<BrotliCompressionProviderOptions>(options =>
{
options.Level = CompressionLevel.Fastest;
});
}
Provedor de compactação gzip

Use o GzipCompressionProvider para compactar respostas com o formato de arquivo Gzip.
Se nenhum provedor de compactação é adicionados explicitamente a CompressionProviderCollection:
O provedor de compactação Gzip é adicionado por padrão para a matriz de provedores de compactação
juntamente com o provedor de compactação Brotli.
Padrões de compactação para a compactação Brotli quando o formato de dados compactados Brotli é
suportado pelo cliente. Se Brotli não é suportada pelo cliente, a compactação padrão Gzip quando o cliente
oferece suporte à compactação Gzip.
O provedor de compactação Gzip é adicionado por padrão para a matriz de provedores de compactação.
Padrões de compactação como Gzip, quando o cliente oferece suporte à compactação Gzip.

{
}
O provedor de compactação Gzip devem ser adicionado ao quaisquer provedores de compactação são
adicionados explicitamente:

{
{
options.MimeTypes =
});
}

{
{
options.MimeTypes =
});
}

{
{
options.MimeTypes =
});
}
Definir a compactação de nível com GzipCompressionProviderOptions. O provedor de compactação Gzip assume

como padrão o nível de compactação mais rápido (CompressionLevel.Fastest), que não pode produzir a
compactação mais eficiente. Se a compactação mais eficiente é desejada, configure o middleware de compactação
ideal.
NÍVEL DE COMPACTAÇÃO DESCRIÇÃO
CompressionLevel.Fastest A compactação deve ser concluída assim que possível, mesmo

se a saída resultante não é compactada da maneira ideal.
CompressionLevel.NoCompression Nenhuma compactação deve ser executada.
CompressionLevel.Optimal As respostas devem ser compactadas ideal, mesmo se a

compactação leva mais tempo para concluir.
{
services.Configure<GzipCompressionProviderOptions>(options =>
{
options.Level = CompressionLevel.Fastest;
});
}
Provedores personalizados
Criar implementações de compactação personalizado com ICompressionProvider. O EncodingName representa o
conteúdo de codificação que este ICompressionProvider produz. O middleware usa essas informações para
escolher o provedor de acordo com a lista especificada no Accept-Encoding cabeçalho da solicitação.
Usando o aplicativo de exemplo, o cliente envia uma solicitação com o Accept-Encoding: mycustomcompression
cabeçalho. O middleware usa a implementação de compactação personalizado e retorna a resposta com um
Content-Encoding: mycustomcompression cabeçalho. O cliente deve ser capaz de descompactar a codificação
personalizada para que uma implementação de compactação personalizado trabalhar.

{
{
options.MimeTypes =
});
}
public class CustomCompressionProvider : ICompressionProvider

{
public string EncodingName => "mycustomcompression";
public bool SupportsFlush => true;
public Stream CreateStream(Stream outputStream)

{
// Create a custom compression stream wrapper here
return outputStream;
}
}

{
{
options.MimeTypes =
});
}
{

{
}
}

{
{
options.MimeTypes =
});
}

{

{
}
}
Enviar uma solicitação para o aplicativo de exemplo com o Accept-Encoding: mycustomcompression cabeçalho e
observar os cabeçalhos de resposta. O Vary e Content-Encoding cabeçalhos estão presentes na resposta. O corpo
de resposta (não mostrado) não será compactado pelo exemplo. Não existe uma implementação da compactação
no CustomCompressionProvider classe do exemplo. No entanto, o exemplo mostra onde você poderia implementar
tal um algoritmo de compactação.
tipos MIME
O middleware Especifica um conjunto de tipos MIME para a compactação padrão:
application/javascript
application/json
application/xml
text/css
text/html
text/json
text/plain
text/xml
Substituir ou acrescentar os tipos MIME com as opções de Middleware de compactação de resposta. Observe que
curinga MIME tipos, como text/* não são suportados. O aplicativo de exemplo adiciona um tipo MIME
image/svg+xml e compacta e serve o ASP.NET Core a imagem da faixa ( banner.svg ).

{
{
options.MimeTypes =
});
}
{
{
options.MimeTypes =
});
}

{
{
options.MimeTypes =
});
}
Compactação com protocolo seguro

Respostas compactadas através de conexões seguras podem ser controladas com o EnableForHttps opção, que é
desabilitada por padrão. Usar a compactação com páginas geradas dinamicamente pode levar a problemas de
segurança, como o CRIME e violação ataques.
Adicionando o cabeçalho Vary

Quando a compactação de respostas com base no Accept-Encoding cabeçalho, há potencialmente várias versões
compactadas de resposta e uma versão não compactada. Para instruir os caches de cliente e o proxy que várias
versões existirem e devem ser armazenadas, o Vary cabeçalho é adicionado com um Accept-Encoding valor. No
ASP.NET Core 2.0 ou posterior, o middleware adiciona o Vary cabeçalho automaticamente quando a resposta é
compactada.
Quando a compactação de respostas com base no Accept-Encoding cabeçalho, há potencialmente várias versões
compactadas de resposta e uma versão não compactada. Para instruir os caches de cliente e o proxy que várias
versões existirem e devem ser armazenadas, o Vary cabeçalho é adicionado com um Accept-Encoding valor. No
ASP.NET Core 1.x, adicionando o Vary cabeçalho à resposta é realizado manualmente:
// ONLY REQUIRED FOR ASP.NET CORE 1.x APPS

private void ManageVaryHeader(HttpContext context)
{
// If the Accept-Encoding header is present, add the Vary header
var accept = context.Request.Headers[HeaderNames.AcceptEncoding];
if (!StringValues.IsNullOrEmpty(accept))
{
context.Response.Headers.Append(HeaderNames.Vary, HeaderNames.AcceptEncoding);
}
}
Problema de middleware quando atrás de um proxy reverso do Nginx

Quando uma solicitação é transmitida por proxy pelo Nginx, o Accept-Encoding cabeçalho é removido. Isso
impede que o middleware de compactação de resposta. Para obter mais informações, consulte NGINX:
compactação e descompactação. Esse problema é acompanhado pelo descobrir a compactação de passagem do
Nginx (BasicMiddleware n º 123).
Trabalhando com a compactação dinâmica do IIS

Se você tiver um Active Directory dinâmico compactação de módulo do IIS configurado no nível do servidor que
você deseja desabilitar para um aplicativo, desabilite o módulo com uma adição à Web. config arquivo. Para obter
mais informações, consulte Desabilitando módulos do IIS.
Use uma ferramenta como Fiddler, Firebug, ou Postman, que permitem que você defina o Accept-Encoding
cabeçalho de solicitação e estudar os cabeçalhos de resposta, o tamanho e o corpo. Por padrão, o Middleware de
compactação de resposta compacta as respostas que atendem às seguintes condições:
O Accept-Encoding cabeçalho está presente com um valor de br , gzip , * , ou codificação personalizada que
corresponde a um provedor de compactação personalizado estabelecida por você. O valor não deve ser
identity ou tem um valor de qualidade (qvalue, q ) configuração de 0 (zero).
O tipo MIME ( Content-Type ) deve ser definido e deve corresponder a um tipo MIME configurado no
ResponseCompressionOptions.
A solicitação não deve incluir o Content-Range cabeçalho.
A solicitação deve usar protocolo inseguro (http), a menos que o protocolo seguro (https) é configurado nas
opções de Middleware de compactação de resposta. Observe o perigo descritos acima ao habilitar a
compactação de conteúdo segura.
O Accept-Encoding cabeçalho está presente com um valor de gzip , * , ou codificação personalizada que
corresponde a um provedor de compactação personalizado estabelecida por você. O valor não deve ser
identity ou tem um valor de qualidade (qvalue, q ) configuração de 0 (zero).
O tipo MIME ( Content-Type ) deve ser definido e deve corresponder a um tipo MIME configurado no
ResponseCompressionOptions.
A solicitação não deve incluir o Content-Range cabeçalho.
A solicitação deve usar protocolo inseguro (http), a menos que o protocolo seguro (https) é configurado nas
opções de Middleware de compactação de resposta. Observe o perigo descritos acima ao habilitar a
compactação de conteúdo segura.
Recursos adicionais
Rede de desenvolvedor do Mozilla: Codificação aceita
RFC 7231 seção 3.1.2.1: Codings de conteúdo
RFC 7230 seção 4.2.3: Codificação de Gzip
Versão de especificação de formato de arquivo GZIP 4.3
Migrar do ASP.NET Core 2.0 para 2.1
Por Rick Anderson

Ver o que há de novo no ASP.NET Core 2.1 para uma visão geral dos novos recursos no ASP.NET Core 2.1.
Neste artigo:
Aborda os conceitos básicos da migração de um aplicativo ASP.NET Core 2.0 para 2.1.
Fornece uma visão geral das alterações para os modelos de aplicativos web ASP.NET Core.
É uma maneira rápida de obter uma visão geral das alterações no 2.1:
Crie um aplicativo web do ASP.NET Core 2.0 chamado WebApp1.
Confirme o WebApp1 em um sistema de controle de origem.
Excluir WebApp1 e criar um aplicativo web do ASP.NET Core 2.1 chamado WebApp1 no mesmo local.
Revise as alterações na versão 2.1.
Este artigo fornece uma visão geral sobre a migração para o ASP.NET Core 2.1. Ele não contém uma lista
completa de todas as alterações necessárias para migrar para a versão 2.1. Alguns projetos podem exigir mais
etapas dependendo das opções selecionadas quando o projeto foi criado e as modificações feitas no projeto.
Atualizar o arquivo de projeto para usar versões 2.1

Atualize o arquivo de projeto:
Alterar a estrutura de destino para o .NET Core 2.1 Atualizando o arquivo de projeto para
<TargetFramework>netcoreapp2.1</TargetFramework> .
Substitua a referência de pacote para Microsoft.AspNetCore.All com uma referência de pacote para
Microsoft.AspNetCore.App . Talvez você precise adicionar dependências que foram removidas da
Microsoft.AspNetCore.All . Para obter mais informações, consulte Metapacote Microsoft.AspNetCore.All para
ASP.NET Core 2.0 e Metapacote Microsoft.AspNetCore.App para ASP.NET Core 2.1 e posterior.
Remova o atributo "Version" na referência de pacote para Microsoft.AspNetCore.App . Projetos que usam
<Project Sdk="Microsoft.NET.Sdk.Web"> não precisa definir a versão. A versão será indicada pela estrutura de
destino e selecionada para corresponder melhor o funcionamento do ASP.NET Core 2.1. (Consulte abaixo para
obter mais informações.)
Para aplicativos destinados ao .NET Framework, atualize cada referência de pacote a 2.1.
Remover referências a <DotNetCliToolReference> elementos para os pacotes a seguir. Essas ferramentas
são agrupadas por padrão na CLI do .NET Core e não precisam ser instalado separadamente.
Microsoft.DotNet.Watcher.Tools ( dotnet watch )
Entityframeworkcore ( dotnet ef )
Microsoft.Extensions.Caching.SqlConfig.Tools ( dotnet sql-cache )
Secretmanager ( dotnet user-secrets )
Opcional: você pode remover o <DotNetCliToolReference> elemento para
Microsoft.VisualStudio.Web.CodeGeneration.Tools . Você pode substituir essa ferramenta com uma versão
instalada globalmente executando dotnet tool install -g dotnet-aspnet-codegenerator .
Para o 2.1, uma biblioteca de classes Razor é a solução recomendada para distribuir arquivos do Razor. Se seu
aplicativo usa exibições inseridas ou, caso contrário, se baseia na compilação de tempo de execução de arquivos
do Razor, adicione <CopyRefAssembliesToPublishDirectory>true</CopyRefAssembliesToPublishDirectory> ao
arquivo de projeto.
A marcação a seguir mostra o arquivo de 2.0 projeto gerado pelo modelo:
<PropertyGroup>
<UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.3" PrivateAssets="All" />
<PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.4"
</ItemGroup>
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.2" />
</ItemGroup>
</Project>
A marcação a seguir mostra o arquivo de 2.1 projeto gerado pelo modelo:
<PropertyGroup>
<UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
</Project>
Regras para projetos direcionados para a estrutura compartilhada

ASP.NET Core 2.1 inclui as seguintes estruturas compartilhadas:
Microsoft.AspNetCore.All
A versão especificada pela referência de pacote é o mínimo necessário versão. Por exemplo, um projeto
referenciando o 2.1.1 versões desses pacotes não serão executados em um computador com apenas o 2.1.0 tempo
de execução instalado.
Problemas conhecidos para projetos direcionados para a estrutura compartilhada:
O .NET Core 2.1.300 SDK (incluído pela primeira vez no Visual Studio 15.6) defina a versão implícita do
Microsoft.AspNetCore.App à 2.1.0 que causaram conflitos com o Entity Framework Core 2.1.1. A solução
recomendada é atualizar o SDK do .NET Core para 2.1.301 ou posterior. Para obter mais informações,
consulte pacotes que compartilham dependências com a Microsoft não podem fazer referência a versões de
patch.
Todos os projetos que devem usar Microsoft.AspNetCore.All ou Microsoft.AspNetCore.App deve adicionar
uma referência de pacote para o pacote no arquivo de projeto, mesmo se eles contêm uma referência de
projeto para outro projeto usando Microsoft.AspNetCore.All ou Microsoft.AspNetCore.App .
Exemplo:
MyApp tem uma referência de pacote para Microsoft.AspNetCore.App .
MyApp.Tests tem uma referência de projeto para MyApp.csproj .
Adicionar uma referência de pacote para Microsoft.AspNetCore.App para MyApp.Tests . Para obter mais
informações, consulte testes de integração é difícil de configurar e podem ser divididas em manutenção da
estrutura compartilhada.
Atualizar para as imagens do Docker 2.1

No ASP.NET Core 2.1, as imagens do Docker são migrados para o repositório do GitHub dotnet/dotnet-docker. A
tabela a seguir mostra o Docker alterações de imagem e marca:
2.0 2.1
Microsoft / Microsoft/aspnetcore:2.0 microsoft/dotnet:2.1-aspnetcore-runtime
Microsoft/aspnetcore-build: 2.0 Microsoft / dotnet:2.1-sdk
Alterar o FROM linhas no seu Dockerfile para usar as marcas e os novos nomes de imagem na coluna de 2.1 da
tabela anterior. Para obter mais informações, consulte Migrando do aspnetcore repositórios de docker para dotnet.
Alterações para aproveitar as novas expressões baseadas em código

são recomendados no ASP.NET Core 2.1
Alterações para Main
As imagens a seguir mostram as alterações feitas para o modelo gerado Program.cs arquivo.
A imagem anterior mostra a versão 2.0 com as exclusões em vermelho.

A imagem a seguir mostra o código 2.1. O código em verde substituído na versão 2.0:
O código a seguir mostra a versão 2.1 das Program.cs:
namespace WebApp1
{
{
{
}

}
}
O novo Main substitui a chamada para BuildWebHost com CreateWebHostBuilder. IWebHostBuilder foi
adicionado para dar suporte a um novo infraestrutura de teste de integração.
Alterações para a inicialização
O código a seguir mostra as alterações ao código de modelo 2.1 gerado. Todas as alterações são adicionadas
recentemente o código, exceto que UseBrowserLink foi removido:
namespace WebApp1
{
{
{
}

{
{
request.
});
services.AddMvc()
}

{
{
}
else
{
app.UseHsts();
}
// If the app uses Session or TempData based on Session:
app.UseMvc();
}
}
}
As alterações de código anteriores são detalhadas em:

Suporte de GDPR no ASP.NET Core para CookiePolicyOptions e UseCookiePolicy .
Protocolo de segurança de transporte estrito HTTP (HSTS ) para UseHsts .
Exigir HTTPS para UseHttpsRedirection .
SetCompatibilityVersion para SetCompatibilityVersion(CompatibilityVersion.Version_2_1) .
Alterações no código de autenticação
ASP.NET Core 2.1 oferece ASP.NET Core Identity como um biblioteca de classes Razor (RCL ).
O padrão 2.1 interface de identidade do usuário atualmente não fornece novos recursos significativos em relação à
versão 2.0. Substituindo a identidade com o pacote RCL é opcional. As vantagens para substituir o modelo gerado
identidade do código com a versão da RCL incluem:
Muitos arquivos são movidos para fora de sua árvore de origem.
Quaisquer correções de bug ou novos recursos de identidade estão incluídos na metapacote Microsoft. Você
obtém a identidade atualizada automaticamente quando Microsoft.AspNetCore.App é atualizado.
Se você tiver feito não triviais alterações ao modelo de código de identidade gerado:
As vantagens anteriores provavelmente fazem isso não justificar a conversão para a versão da RCL.
Você pode manter seu código de identidade do ASP.NET Core 2.0, ele é totalmente suportado.
Identidade 2.1 expõe pontos de extremidade com o Identity área. Por exemplo, a tabela a seguir mostra
exemplos de pontos de extremidade de identidade que alterar de 2.0 para 2.1:
2.0 URL 2.1 URL DE
/ Account/Login Identidade/logon/conta
/ Conta/Logout Identidade/logoff/conta
/ Conta/gerenciar / Identidade/conta/gerenciar
Identidade de interface do usuário com a necessidade de biblioteca de identidade 2.1 para levar em conta as URLs
de identidade de aplicativos que tem o código usando a identidade e substitua 2.0 têm /Identity anexado para os
URIs de segmento. É uma maneira de lidar com os novos pontos de extremidade de identidade é configurar
redirecionamentos, por exemplo da /Account/Login para /Identity/Account/Login .
Atualizar identidade para a versão 2.1
As seguintes opções estão disponíveis para atualizar a identidade para o 2.1.
Use o código de identidade da interface do usuário 2.0 sem alterações. Usando o código de identidade da
interface do usuário 2.0 tem suporte total. Isso é uma boa abordagem quando alterações significativas foram
feitas para o código de identidade gerado.
Excluir seu código 2.0 de identidade existente e identidade de Scaffold em seu projeto. Seu projeto usará o
ASP.NET Core Identity biblioteca de classes Razor. Você pode gerar o código e a interface do usuário para
qualquer parte do código de identidade da interface do usuário que você modificou. Aplica as alterações de
código para o código gerado automaticamente recém-criado de interface do usuário.
Excluir seu código 2.0 de identidade existente e identidade de Scaffold em seu projeto com a opção de
substituir todos os arquivos.
Substitua a identidade 2.0 interface do usuário com a biblioteca de classes Razor identidade 2.1
Esta seção descreve as etapas para substituir o código de identidade do ASP.NET Core 2.0 modelo gerado com o
ASP.NET Core Identity biblioteca de classes Razor. As etapas a seguir são para um projeto de páginas do Razor,
mas a abordagem para um projeto MVC é semelhante.
Verifique se o arquivo de projeto é atualizado para usar 2.1 versões
Exclua as seguintes pastas e todos os arquivos contidos neles:
Controladores
Páginas/Account /
Extensões
Compile o projeto.
Criar o scaffolding de identidade em seu projeto:
Selecione os projetos saindo _layout. cshtml arquivo.
Selecione o + ícone no lado direito dos classe de contexto de dados. Aceite o nome padrão.
Selecione adicionar para criar uma nova classe de contexto de dados. Criar um novo contexto de dados
é necessária para criar o scaffolding. Você pode remover o novo contexto de dados na próxima seção.
Atualizar após o scaffolding de identidade
Excluir o scaffolder de identidade gerado IdentityDbContext derivado da classe na áreas/identidade/Data/
pasta.
Excluir Areas/Identity/IdentityHostingStartup.cs
Atualizar o _Loginpartial arquivo:
Mover páginas /_Loginpartial à páginas/Shared/_Loginpartial
Adicionar asp-area="Identity" os links de âncora e o formulário.
Atualização de <form /> elemento
<form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new {
area = "" })" method="post" id="logoutForm" class="navbar-right">
O código a seguir mostra o atualizada _Loginpartial arquivo:
@inject SignInManager<ApplicationUser> SignInManager

@inject UserManager<ApplicationUser> UserManager
{
<form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new {
area = "" })" method="post" id="logoutForm" class="navbar-right">
<li>
<a asp-area="Identity" asp-page="/Account/Manage/Index" title="Manage">Hello
@UserManager.GetUserName(User)!</a>
</li>
<li>
<button type="submit" class="btn btn-link navbar-btn navbar-link">Log out</button>
</li>
</ul>
</form>
}
else
{
<li><a asp-area="Identity" asp-page="/Account/Register">Register</a></li>
<li><a asp-area="Identity" asp-page="/Account/Login">Log in</a></li>
</ul>
}
Atualização ConfigureServices com o código a seguir:

{
services.AddMvc();
// Register no-op EmailSender used by account confirmation and password reset

// during development
}
Altera a páginas do Razor projetos de arquivos do Razor

O arquivo de layout
Mover páginas /_layout. cshtml à páginas/Shared/_layout. cshtml
O layout. cshtml arquivo tem as seguintes alterações:
<partial name="_CookieConsentPartial" /> é adicionado. Para obter mais informações, veja Suporte
RGPD no ASP.NET Core.
alterações de jQuery do 2.2.0 para 3.3.1
_ValidationScriptsPartial.cshtml
Páginas /_ValidationScriptsPartial.cshtml move para páginas/Shared/_ValidationScriptsPartial.cshtml
jQuery.Validate/1.14.0 muda para jquery.validate/1.17.0
Novos arquivos
Os seguintes arquivos são adicionados:
Privacy.cshtml
Privacy.cshtml.cs
Ver GDPR suporte no ASP.NET Core para obter informações sobre os arquivos anteriores.
Alterações em arquivos de projetos do MVC Razor

O arquivo de layout
O layout. cshtml arquivo tem as seguintes alterações:
<partial name="_CookieConsentPartial" /> é adicionado.
alterações de jQuery do 2.2.0 para 3.3.1
_ValidationScriptsPartial.cshtml
jQuery.Validate/1.14.0 muda para jquery.validate/1.17.0
Novos arquivos e métodos de ação
O exemplo a seguir foram adicionados:
Views/Home/Privacy.cshtml
O Privacy método de ação é adicionado ao controlador Home.
Ver GDPR suporte no ASP.NET Core para obter informações sobre os arquivos anteriores.
Alterações no arquivo launchsettings. JSON
Como os aplicativos ASP.NET Core agora usam HTTPS por padrão, o Properties/launchSettings.json arquivo foi
alterado.
O JSON a seguir mostra o 2.0 anteriores modelo gerado launchsettings. JSON arquivo:
{
"iisSettings": {
"iisExpress": {
"sslPort": 0
}
},
"profiles": {
"IIS Express": {
}
},
"WebApp1": {
},
}
}
}
O JSON a seguir mostra o novo 2.1 modelo gerado launchsettings. JSON arquivo:
{
"iisSettings": {
"iisExpress": {
"applicationUrl": "http://localhost:39191",
"sslPort": 44390
}
},
"profiles": {
"IIS Express": {
}
},
"WebApp1": {
"applicationUrl": "https://localhost:5001;http://localhost:5000",
}
}
}
}
Para obter mais informações, consulte Impor HTTPS no ASP.NET Core.
Alterações adicionais
Se hospedar o aplicativo no Windows com o IIS, instalar a versão mais recente pacote de hospedagem do .NET
Core.
SetCompatibilityVersion
Configuração de transporte
Migrar do ASP.NET Core 1.x para 2.0
Por Scott Addie

Neste artigo, vamos orientá-lo pela atualização de um projeto existente ASP.NET Core 1.x para o ASP.NET Core
2.0. A migração do aplicativo para o ASP.NET Core 2.0 permite que você aproveite muitos novos recursos e
melhorias de desempenho.
Os aplicativos ASP.NET Core 1.x existentes baseiam-se em modelos de projeto específicos à versão. Conforme a
estrutura do ASP.NET Core evolui, os modelos do projeto e o código inicial contido neles também. Além de
atualizar a estrutura ASP.NET Core, você precisa atualizar o código para o aplicativo.
Pré-requisitos
Veja a Introdução ao ASP.NET Core.
Atualizar TFM (Moniker da Estrutura de Destino)

Projetos direcionados ao .NET Core devem usar o TFM de uma versão maior ou igual ao .NET Core 2.0. Pesquise
o nó <TargetFramework> no arquivo .csproj e substitua seu texto interno por netcoreapp2.0 :
Projetos direcionados ao .NET Framework devem usar o TFM de uma versão maior ou igual ao .NET Framework
4.6.1. Pesquise o nó <TargetFramework> no arquivo .csproj e substitua seu texto interno por net461 :
<TargetFramework>net461</TargetFramework>
NOTE
O .NET Core 2.0 oferece uma área de superfície muito maior do que o .NET Core 1.x. Se você estiver direcionando o .NET
Framework exclusivamente devido a APIs ausentes no .NET Core 1.x, o direcionamento do .NET Core 2.0 provavelmente
funcionará.
Atualizar a versão do SDK do .NET Core em global.json

Se a solução depender de um arquivo global.json para direcionar uma versão específica do SDK do .NET Core,
atualize sua propriedade version para que ela use a versão 2.0 instalada no computador:
{
"sdk": {
"version": "2.0.0"
}
}
Referências do pacote de atualização

O arquivo .csproj em um projeto 1.x lista cada pacote NuGet usado pelo projeto.
Em um projeto ASP.NET Core 2.0 direcionado ao .NET Core 2.0, uma única referência de metapacote no arquivo
.csproj substitui a coleção de pacotes:
<ItemGroup>
</ItemGroup>
Todos os recursos do ASP.NET Core 2.0 e do Entity Framework Core 2.0 são incluídos no metapacote.
Os projetos do ASP.NET Core 2.0 direcionados ao .NET Framework devem continuar a referenciar pacotes NuGet
individuais. Atualize o atributo Version de cada nó <PackageReference /> para 2.0.0.
Por exemplo, esta é a lista de nós <PackageReference /> usados em um projeto ASP.NET Core 2.0 típico
direcionado ao .NET Framework:
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Authentication.Cookies" Version="2.0.0" />
<PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="2.0.0" />
<PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="2.0.0" />
<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0"
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="2.0.0" PrivateAssets="All" />
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="2.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.0" PrivateAssets="All" />
<PackageReference Include="Microsoft.VisualStudio.Web.BrowserLink" Version="2.0.0" />
</ItemGroup>
Atualizar ferramentas da CLI do .NET Core

No arquivo .csproj, atualize o atributo Version de cada nó <DotNetCliToolReference /> para 2.0.0.
Por exemplo, esta é a lista de ferramentas da CLI usadas em um projeto ASP.NET Core 2.0 típico direcionado ao
.NET Core 2.0:
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.0" />
</ItemGroup>
Renomear a propriedade de Fallback de Destino do Pacote

O arquivo .csproj de um projeto 1.x usou um nó PackageTargetFallback e uma variável:
<PackageTargetFallback>$(PackageTargetFallback);portable-net45+win8+wp8+wpa81;</PackageTargetFallback>
Renomeie o nó e a variável como AssetTargetFallback :

<AssetTargetFallback>$(AssetTargetFallback);portable-net45+win8+wp8+wpa81;</AssetTargetFallback>
Atualizar o método Main em Program.cs

Em projetos 1.x, o método Main de Program.cs era parecido com este:
using System.IO;
namespace AspNetCoreDotNetCore1App
{
{
{
.UseKestrel()
.Build();
host.Run();
}
}
}
Em projetos 2.0, o método Main de Program.cs foi simplificado:
namespace AspNetCoreDotNetCore2App
{
{
{
}

.Build();
}
}
A adoção desse novo padrão do 2.0 é altamente recomendada e é necessária para que os recursos de produto
como as Migrações do Entity Framework (EF ) Core funcionem. Por exemplo, a execução de Update-Database na
janela do Console do Gerenciador de Pacotes ou de dotnet ef database update na linha de comando (em projetos
convertidos no ASP.NET Core 2.0) gera o seguinte erro:
Unable to create an object of type '<Context>'. Add an implementation of

'IDesignTimeDbContextFactory<Context>' to the project, or see https://go.microsoft.com/fwlink/?linkid=851728
for additional patterns supported at design time.
Adicionar provedores de configuração
Nos projetos 1.x, a adição de provedores de configuração em um aplicativo foi realizada por meio do construtor
Startup . As etapas incluíram a criação de uma instância de ConfigurationBuilder , o carregamento de provedores
aplicáveis (variáveis de ambiente, configurações do aplicativo, etc.) e a inicialização de um membro de
IConfigurationRoot .

{
.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);
{
}
builder.AddEnvironmentVariables();
}
O exemplo anterior carrega o membro Configuration com definições de configuração do appsettings.json, bem
como qualquer arquivo appsettings.<EnvironmentName>.json correspondente à propriedade
IHostingEnvironment.EnvironmentName . Estes arquivos estão localizados no mesmo caminho que Startup.cs.
Nos projetos 2.0, o código de configuração clichê inerente aos projetos 1.x é executado de modo oculto. Por
exemplo, as variáveis de ambiente e as configurações do aplicativo são carregadas na inicialização. O código
Startup.cs equivalente é reduzido à inicialização IConfiguration com a instância injetada:

{
}
Para remover os provedores padrão adicionados por WebHostBuilder.CreateDefaultBuilder , invoque o método

Clear na propriedade IConfigurationBuilder.Sources dentro de ConfigureAppConfiguration . Para adicionar os
provedores de volta, utilize o método ConfigureAppConfiguration em Program.cs:

{
}

.ConfigureAppConfiguration((hostContext, config) =>
{
// delete all default configuration providers
config.Sources.Clear();
config.AddJsonFile("myconfig.json", optional: true);
})
.Build();
A configuração usada pelo método CreateDefaultBuilder no snippet de código anterior pode ser vista aqui.
Para obter mais informações, consulte Configuração no ASP.NET Core.
Mover código de inicialização do banco de dados

Em projetos do 1.x usando o EF Core 1.x, um comando como dotnet ef migrations add faz o seguinte:
1. Cria uma instância Startup
2. Invoca o método ConfigureServices para registrar todos os serviços com injeção de dependência (incluindo
tipos DbContext )
3. Executa suas tarefas de requisito
Em projetos do 2.0 usando o EF Core 2.0, o Program.BuildWebHost é chamado para obter os serviços do aplicativo.
Ao contrário do 1.x, isso tem o efeito colateral adicional de chamar o Startup.Configure . Caso seu aplicativo do 1.x
tenha chamado o código de inicialização do banco de dados no seu método Configure , problemas inesperados
poderão ocorrer. Por exemplo, se o banco de dados não existir ainda, o código de propagação será executado antes
da execução do comando EF Core Migrations. Esse problema fará com que um comando
dotnet ef migrations list falhe se o banco de dados ainda não existir.
Considere o seguinte código de inicialização de propagação do 1.x no método Configure de Startup.cs:
{
routes.MapRoute(
name: "default",
});
SeedData.Initialize(app.ApplicationServices);
Em projetos do 2.0, mova a chamada SeedData.Initialize para o método Main do Program.cs:

{
try
{
}
{
}
}
host.Run();
A partir do 2.0, é uma prática inadequada realizar qualquer ação no BuildWebHost , exceto compilação e
configuração do host da Web. Tudo relacionado à execução do aplicativo deve ser tratado fora do BuildWebHost
—, normalmente no método Main do Program.cs.
Examinar a configuração de compilação do Modo de Exibição do Razor

Um tempo de inicialização mais rápido do aplicativo e pacotes publicados menores são de extrema importância
para você. Por esses motivos, a opção Compilação de exibição do Razor é habilitada por padrão no ASP.NET Core
2.0.
A configuração da propriedade MvcRazorCompileOnPublish como verdadeiro não é mais necessária. A menos que
você esteja desabilitando a compilação de exibição, a propriedade poderá ser removida do arquivo .csproj.
Ao direcionar o .NET Framework, você ainda precisa referenciar explicitamente o pacote NuGet
Microsoft.AspNetCore.Mvc.Razor.ViewCompilation no arquivo .csproj:
<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All"

/>
Depender dos recursos “Light-Up” do Application Insights

A instalação fácil da instrumentação de desempenho do aplicativo é importante. Agora, você pode contar com os
novos recursos “light-up” do Application Insights disponíveis nas ferramentas do Visual Studio 2017.
Os projetos do ASP.NET Core 1.1 criados no Visual Studio 2017 adicionaram o Application Insights por padrão.
Se não estiver usando o SDK do Application Insights diretamente, fora de Program.cs e Startup.cs, siga estas
etapas:
1. Se você estiver direcionando ao .NET Core, remova o nó <PackageReference /> seguinte do arquivo .csproj:
<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
2. Se você estiver direcionando ao .NET Core, remova a invocação do método de extensão

UseApplicationInsights de Program.cs:

{
.UseKestrel()
.Build();
host.Run();
}
3. Remova a chamada à API do lado do cliente do Application Insights de _Layout.cshtml. Ela inclui as duas
seguintes linhas de código:

Se você estiver usando o SDK do Application Insights diretamente, continue fazendo isso. O metapacote do 2.0
inclui a última versão do Application Insights. Portanto, um erro de downgrade do pacote será exibido se você
estiver referenciando uma versão mais antiga.
Adotar melhorias de autenticação/identidade

O ASP.NET Core 2.0 tem um novo modelo de autenticação e uma série de alterações significativas no ASP.NET
Core Identity. Se você criar o projeto com a opção Contas de Usuário Individuais habilitada ou se adicionar
manualmente a autenticação ou a identidade, consulte Migrar a autenticação e a identidade para o ASP.NET Core
2.0.
Recursos adicionais
Últimas alterações no ASP.NET Core 2.0
Migrar autenticação e identidade para o ASP.NET
Core 2.0
Por Scott Addie e Kung Hao

ASP.NET Core 2.0 tem um novo modelo para autenticação e identidade que simplifica a configuração por meio de
serviços. Aplicativos ASP.NET Core 1.x que usam autenticação ou a identidade podem ser atualizados para usar o
novo modelo, conforme descrito abaixo.
Middleware de autenticação e serviços

Em projetos 1.x, a autenticação é configurada por meio do middleware. Um método de middleware é invocado
para cada esquema de autenticação que você deseja dar suporte.
O exemplo a seguir 1.x configura a autenticação do Facebook com identidade no Startup.cs:

{
}
public void Configure(IApplicationBuilder app, ILoggerFactory loggerfactory)

{
app.UseIdentity();
app.UseFacebookAuthentication(new FacebookOptions {
AppId = Configuration["auth:facebook:appid"],
AppSecret = Configuration["auth:facebook:appsecret"]
});
}
Em projetos do 2.0, a autenticação é configurada por meio de serviços. Cada esquema de autenticação é
registrada na ConfigureServices método de Startup.cs. O UseIdentity o método é substituído por
UseAuthentication .
O exemplo a seguir 2.0 configura a autenticação do Facebook com identidade no Startup.cs:

{
// If you want to tweak Identity cookies, they're no longer part of IdentityOptions.

services.ConfigureApplicationCookie(options => options.LoginPath = "/Account/LogIn");
.AddFacebook(options =>
{
options.AppId = Configuration["auth:facebook:appid"];
options.AppSecret = Configuration["auth:facebook:appsecret"];
});
}
public void Configure(IApplicationBuilder app, ILoggerFactory loggerfactory) {

}
O UseAuthentication método adiciona um componente de middleware de autenticação único que é responsável

pela autenticação automática e o tratamento de solicitações de autenticação remota. Ele substitui todos os
componentes de middleware individuais com um componente de middleware simples e comum.
Veja abaixo as instruções de migração de 2.0 para cada esquema de autenticação principal.
Autenticação baseada em cookie
Selecione uma das duas opções abaixo e faça as alterações necessárias na Startup.cs:
1. Usar cookies com identidade
Substitua UseIdentity com UseAuthentication no Configure método:
Invocar o AddIdentity método no ConfigureServices método para adicionar os serviços de

autenticação de cookie.
Opcionalmente, invocar o ConfigureApplicationCookie ou ConfigureExternalCookie método no
ConfigureServices método ajustar as configurações de cookie de identidade.
services.ConfigureApplicationCookie(options => options.LoginPath = "/Account/LogIn");
2. Usar cookies sem o Identity

Substitua os UseCookieAuthentication chamada de método na Configure método com
UseAuthentication :
Invocar o AddAuthentication e AddCookie métodos no ConfigureServices método:

// If you don't want the cookie to be automatically authenticated and assigned to
HttpContext.User,
// remove the CookieAuthenticationDefaults.AuthenticationScheme parameter passed to
AddAuthentication.
{
options.LoginPath = "/Account/LogIn";
options.LogoutPath = "/Account/LogOff";
});
Autenticação do portador do JWT

Faça as seguintes alterações na Startup.cs:
Substitua os UseJwtBearerAuthentication chamada de método na Configure método com
UseAuthentication :
Invocar o AddJwtBearer método no ConfigureServices método:
services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
{
options.Audience = "http://localhost:5001/";
options.Authority = "http://localhost:5000/";
});
Este trecho de código não usa a identidade, portanto, o esquema padrão deve ser definido, passando
JwtBearerDefaults.AuthenticationScheme para o AddAuthentication método.
Autenticação OIDC (OpenID Connect)

Substitua os UseOpenIdConnectAuthentication chamada de método na Configure método com
UseAuthentication :
Invocar o AddOpenIdConnect método no ConfigureServices método:
{
options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
.AddCookie()
.AddOpenIdConnect(options =>
{
options.Authority = Configuration["auth:oidc:authority"];
options.ClientId = Configuration["auth:oidc:clientid"];
});
autenticação do Facebook
Substitua os UseFacebookAuthentication chamada de método na Configure método com
UseAuthentication :
Invocar o AddFacebook método no ConfigureServices método:
.AddFacebook(options =>
{
options.AppId = Configuration["auth:facebook:appid"];
options.AppSecret = Configuration["auth:facebook:appsecret"];
});
Substitua os UseGoogleAuthentication chamada de método na Configure método com UseAuthentication :
Invocar o AddGoogle método no ConfigureServices método:
.AddGoogle(options =>
{
options.ClientId = Configuration["auth:google:clientid"];
options.ClientSecret = Configuration["auth:google:clientsecret"];
});
Autenticação da Microsoft Account

Substitua os UseMicrosoftAccountAuthentication chamada de método na Configure método com
UseAuthentication :
Invocar o AddMicrosoftAccount método no ConfigureServices método:
.AddMicrosoftAccount(options =>
{
options.ClientId = Configuration["auth:microsoft:clientid"];
options.ClientSecret = Configuration["auth:microsoft:clientsecret"];
});
Substitua os UseTwitterAuthentication chamada de método na Configure método com UseAuthentication
:
Invocar o AddTwitter método no ConfigureServices método:
.AddTwitter(options =>
{
options.ConsumerKey = Configuration["auth:twitter:consumerkey"];
options.ConsumerSecret = Configuration["auth:twitter:consumersecret"];
});
Esquemas de autenticação padrão de configuração

No 1.x, o AutomaticAuthenticate e AutomaticChallenge propriedades da AuthenticationOptions classe base foram
deve ser definida em um esquema de autenticação. Não havia nenhuma boa maneira para impor isso.
No 2.0, essas duas propriedades foram removidas como propriedades individual AuthenticationOptions instância.
Eles podem ser configurados na AddAuthentication chamada de método dentro a ConfigureServices método de
Startup.cs:
services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme);
No trecho de código anterior, o esquema padrão é definido como

CookieAuthenticationDefaults.AuthenticationScheme ("Cookies").
Como alternativa, use uma versão sobrecarregada do AddAuthentication método para definir mais de uma
propriedade. No exemplo a seguir o método sobrecarregado, o esquema padrão é definido como
CookieAuthenticationDefaults.AuthenticationScheme . O esquema de autenticação como alternativa, pode ser
especificado dentro de seu indivíduo [Authorize] atributos ou as políticas de autorização.
{
options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
});
Defina um esquema padrão do 2.0, se uma das seguintes condições for verdadeira:
Você deseja que o usuário a ser conectado automaticamente
Você usa o [Authorize] políticas de autorização ou atributo sem especificar esquemas
Uma exceção a essa regra é o AddIdentity método. Esse método adiciona cookies para você e define o padrão
autenticar e esquemas de desafio para o cookie do aplicativo IdentityConstants.ApplicationScheme . Além disso, ele
define o esquema de entrada padrão para o cookie externo IdentityConstants.ExternalScheme .
Usar extensões de autenticação HttpContext

O IAuthenticationManager interface é o ponto de entrada principal para o sistema de autenticação de 1. x. Ele foi
substituído por um novo conjunto de HttpContext métodos de extensão no Microsoft.AspNetCore.Authentication
namespace.
Por exemplo, projetos do 1.x referência um Authentication propriedade:
// Clear the existing external cookie to ensure a clean login process
await HttpContext.Authentication.SignOutAsync(_externalCookieScheme);
Em 2.0 projetos, importe as Microsoft.AspNetCore.Authentication namespace e exclua o Authentication

referências de propriedade:

await HttpContext.SignOutAsync(IdentityConstants.ExternalScheme);
Autenticação do Windows (http. sys / IISIntegration)

Há duas variações de autenticação do Windows:
1. O host permite que somente usuários autenticados
2. O host permite que ambos anônimos e usuários autenticados
A primeira descrita acima não é afetada pelas alterações de 2.0.
A segunda descrita acima é afetada pelas alterações de 2.0. Por exemplo, você pode ser permitir que usuários
anônimos em seu aplicativo em IIS ou HTTP. sys mas autorizar usuários no nível do controlador de camada.
Nesse cenário, defina o esquema padrão IISDefaults.AuthenticationScheme no ConfigureServices método
Startup.cs:
services.AddAuthentication(IISDefaults.AuthenticationScheme);
Falha ao definir o esquema padrão adequadamente impede que a solicitação de autorização de desafio do
trabalho.
Instâncias de IdentityCookieOptions
Um efeito colateral das 2.0 alterações é o comutador que usa o chamado opções em vez de instâncias de opções
de cookie. A capacidade de personalizar os nomes de esquema do cookie de identidade é removida.
Por exemplo, 1. x projetos usam injeção de construtor para passar um IdentityCookieOptions parâmetro em
AccountController.cs. O esquema de autenticação de cookie externa é acessado da instância fornecida:
public AccountController(
UserManager<ApplicationUser> userManager,
SignInManager<ApplicationUser> signInManager,
IOptions<IdentityCookieOptions> identityCookieOptions,
IEmailSender emailSender,
ISmsSender smsSender,
{
_externalCookieScheme = identityCookieOptions.Value.ExternalCookieAuthenticationScheme;
_smsSender = smsSender;
_logger = loggerFactory.CreateLogger<AccountController>();
}
A injeção de construtor mencionados anteriormente se torna desnecessária em 2.0 projetos e o

_externalCookieScheme campo pode ser excluído:
public AccountController(
UserManager<ApplicationUser> userManager,
SignInManager<ApplicationUser> signInManager,
IEmailSender emailSender,
ISmsSender smsSender,
{
_smsSender = smsSender;
_logger = loggerFactory.CreateLogger<AccountController>();
}
O IdentityConstants.ExternalScheme constante pode ser usada diretamente:

await HttpContext.SignOutAsync(IdentityConstants.ExternalScheme);
Adicionar propriedades de navegação IdentityUser POCO

As propriedades de navegação do Entity Framework (EF ) Core da base de IdentityUser POCO (objeto Plain Old
CLR ) foram removidos. Se seu projeto 1.x usou essas propriedades, manualmente adicione ao projeto 2.0:
/// <summary>
/// Navigation property for the roles this user belongs to.
/// </summary>
public virtual ICollection<IdentityUserRole<int>> Roles { get; } = new List<IdentityUserRole<int>>();
/// <summary>
/// Navigation property for the claims this user possesses.
/// </summary>
public virtual ICollection<IdentityUserClaim<int>> Claims { get; } = new List<IdentityUserClaim<int>>();
/// <summary>
/// Navigation property for this users login accounts.
/// </summary>
public virtual ICollection<IdentityUserLogin<int>> Logins { get; } = new List<IdentityUserLogin<int>>();
Para impedir que as chaves estrangeiras duplicadas ao executar migrações do EF Core, adicione o seguinte ao seu
IdentityDbContext classe OnModelCreating método (depois que o base.OnModelCreating(); chamar ):
protected override void OnModelCreating(ModelBuilder builder)
{
base.OnModelCreating(builder);
// Customize the ASP.NET Core Identity model and override the defaults if needed.
// For example, you can rename the ASP.NET Core Identity table names and more.
// Add your customizations after calling base.OnModelCreating(builder);
builder.Entity<ApplicationUser>()
.HasMany(e => e.Claims)
.WithOne()
.HasForeignKey(e => e.UserId)
.IsRequired()
.OnDelete(DeleteBehavior.Cascade);
.HasMany(e => e.Logins)
.WithOne()
.IsRequired()
.HasMany(e => e.Roles)
.WithOne()
.IsRequired()
}
Substituir GetExternalAuthenticationSchemes
O método síncrono GetExternalAuthenticationSchemes foi removido para uma versão assíncrona. projetos do 1.x
tem o seguinte código ManageController.cs:
var otherLogins = _signInManager.GetExternalAuthenticationSchemes().Where(auth => userLogins.All(ul =>

auth.AuthenticationScheme != ul.LoginProvider)).ToList();
Este método é exibido no cshtml muito:
var loginProviders = SignInManager.GetExternalAuthenticationSchemes().ToList();

<div>
<p>
@foreach (var provider in loginProviders)
{
<button type="submit" class="btn btn-default" name="provider"
value="@provider.AuthenticationScheme" title="Log in using your @provider.DisplayName
account">@provider.AuthenticationScheme</button>
}
</p>
</div>
</form>
}
Em projetos do 2.0, use o GetExternalAuthenticationSchemesAsync método:
var schemes = await _signInManager.GetExternalAuthenticationSchemesAsync();

var otherLogins = schemes.Where(auth => userLogins.All(ul => auth.Name != ul.LoginProvider)).ToList();
Na cshtml, o AuthenticationScheme propriedade acessada no foreach loop é alterado para Name :

var loginProviders = (await SignInManager.GetExternalAuthenticationSchemesAsync()).ToList();
<div>
<p>
@foreach (var provider in loginProviders)
{
<button type="submit" class="btn btn-default" name="provider" value="@provider.Name"
title="Log in using your @provider.DisplayName account">@provider.DisplayName</button>
}
</p>
</div>
</form>
}
Alteração da propriedade ManageLoginsViewModel

Um ManageLoginsViewModel objeto é usado em de ManageLogins ação de ManageController.cs. Em projetos 1.x, o
objeto OtherLogins propriedade de tipo de retorno é IList<AuthenticationDescription> . Esse tipo de retorno
requer uma importação de Microsoft.AspNetCore.Http.Authentication :
using Microsoft.AspNetCore.Http.Authentication;
namespace AspNetCoreDotNetCore1App.Models.ManageViewModels
{
public class ManageLoginsViewModel
{
public IList<UserLoginInfo> CurrentLogins { get; set; }
public IList<AuthenticationDescription> OtherLogins { get; set; }

}
}
Em projetos do 2.0, o tipo de retorno é alterado para IList<AuthenticationScheme> . Esse novo tipo de retorno
requer substituindo o Microsoft.AspNetCore.Http.Authentication importação de um
Microsoft.AspNetCore.Authentication importar.
using Microsoft.AspNetCore.Authentication;
namespace AspNetCoreDotNetCore2App.Models.ManageViewModels
{
public class ManageLoginsViewModel
{
public IList<UserLoginInfo> CurrentLogins { get; set; }
public IList<AuthenticationScheme> OtherLogins { get; set; }

}
}
Recursos adicionais
Para obter mais detalhes e discussões, consulte o discussão do Auth 2.0 problema no GitHub.
Migrar do ASP.NET para o ASP.NET Core
Por Isaac Levin

Este artigo serve como um guia de referência para migração de aplicativos ASP.NET para o ASP.NET Core.
Pré-requisitos
Frameworks de destino
Projetos do ASP.NET Core oferecem aos desenvolvedores a flexibilidade de direcionamento para o .NET Core,
.NET Framework ou ambos. Consulte Escolhendo entre o .NET Core e .NET Framework para aplicativos de
servidor para determinar qual estrutura de destino é mais apropriada.
Ao usar o .NET Framework como destino, projetos precisam fazer referência a pacotes NuGet individuais.
Usar o .NET Core como destino permite que você elimine várias referências de pacote explícitas, graças ao
metapacote do ASP.NET Core. Instale o metapacote Microsoft.AspNetCore.All em seu projeto:
<ItemGroup>
</ItemGroup>
Quando o metapacote é usado, nenhum pacote referenciado no metapacote é implantado com o aplicativo. O
repositório de tempo de execução do .NET Core inclui esses ativos e eles são pré-compilados para melhorar o
desempenho. Consulte Metapacote do Microsoft.AspNetCore.All para ASP.NET Core 2.x para obter mais detalhes.
Diferenças de estrutura do projeto

O formato de arquivo .csproj foi simplificado no ASP.NET Core. Algumas alterações importantes incluem:
A inclusão explícita de arquivos não é necessária para que eles possam ser considerados como parte do
projeto. Isso reduz o risco de conflitos de mesclagem XML ao trabalhar em grandes equipes.
Não há referências baseadas em GUID a outros projetos, o que melhora a legibilidade do arquivo.
O arquivo pode ser editado sem descarregá-lo no Visual Studio:
Substituição do arquivo Global.asax
O ASP.NET Core introduziu um novo mecanismo para inicializar um aplicativo. O ponto de entrada para
aplicativos ASP.NET é o arquivo Global.asax. Tarefas como configuração de roteamento e registros de filtro e de
área são tratadas no arquivo Global.asax.
public class MvcApplication : System.Web.HttpApplication

{
protected void Application_Start()
{
AreaRegistration.RegisterAllAreas();
FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
RouteConfig.RegisterRoutes(RouteTable.Routes);
BundleConfig.RegisterBundles(BundleTable.Bundles);
}
}
Essa abordagem associa o aplicativo e o servidor no qual ele é implantado de uma forma que interfere na
implementação. Em um esforço para desassociar, a OWIN foi introduzida para fornecer uma maneira mais limpa
de usar várias estruturas juntas. A OWIN fornece um pipeline para adicionar somente os módulos necessários. O
ambiente de hospedagem leva uma função Startup para configurar serviços e pipeline de solicitação do aplicativo.
Startup registra um conjunto de middleware com o aplicativo. Para cada solicitação, o aplicativo chama cada um
dos componentes de middleware com o ponteiro de cabeçalho de uma lista vinculada para um conjunto existente
de manipuladores. Cada componente de middleware pode adicionar um ou mais manipuladores para a pipeline de
tratamento de solicitação. Isso é feito retornando uma referência para o manipulador que é o novo cabeçalho da
lista. Cada manipulador é responsável por se lembrar do próximo manipulador na lista e por invocá-lo. Com o
ASP.NET Core, o ponto de entrada para um aplicativo é Startup e você não tem mais uma dependência de
Global.asax. Ao usar a OWIN com o .NET Framework, use algo parecido com o seguinte como um pipeline:
using Owin;
using System.Web.Http;
namespace WebApi
{
// Note: By default all requests go through this OWIN pipeline. Alternatively you can turn this off by
adding an appSetting owin:AutomaticAppStartup with value “false”.
// With this turned off you can still have OWIN apps listening on specific routes by adding routes in
global.asax file using MapOwinPath or MapOwinRoute extensions on RouteTable.Routes
{
// Invoked once at startup to configure your application.
public void Configuration(IAppBuilder builder)
{
HttpConfiguration config = new HttpConfiguration();
config.Routes.MapHttpRoute("Default", "{controller}/{customerID}", new { controller = "Customer",
customerID = RouteParameter.Optional });
config.Formatters.XmlFormatter.UseXmlSerializer = true;
config.Formatters.Remove(config.Formatters.JsonFormatter);
// config.Formatters.JsonFormatter.UseDataContractJsonSerializer = true;
builder.UseWebApi(config);
}
}
}
Isso configura as rotas padrão e usa XmlSerialization em Json por padrão. Adicione outro Middleware para este
pipeline conforme necessário (carregamento de serviços, definições de configuração, arquivos estáticos, etc.).
O ASP.NET Core usa uma abordagem semelhante, mas não depende de OWIN para manipular a entrada. Em vez
disso, isso é feito por meio do método Main de Program.cs (semelhante a aplicativos de console) e Startup é
carregado por lá.
namespace WebApplication2
{
{
{
}

.Build();
}
}
Startup deve incluir um método Configure . Em Configure , adicione o middleware necessário ao pipeline. No
exemplo a seguir (com base no modelo de site da Web padrão), vários métodos de extensão são usados para
configurar o pipeline com suporte para:
BrowserLink
Páginas de erro
Arquivos estáticos
ASP.NET Core MVC
Identidade

{
{
}
else
{
}
app.UseIdentity();
{
routes.MapRoute(
name: "default",
});
}
O host e o aplicativo foram separados, o que fornece a flexibilidade de mover para uma plataforma diferente no
futuro.
NOTE
Para obter uma referência mais aprofundada sobre o Startup do ASP.NET Core e middleware, veja Startup no ASP.NET Core
Armazenar configurações
O ASP.NET dá suporte ao armazenamento de configurações. Essas configurações são usadas, por exemplo, para
dar suporte ao ambiente no qual os aplicativos foram implantados. Uma prática comum era armazenar todos os
pares chave-valor personalizados na seção <appSettings> do arquivo Web.config:
<appSettings>
<add key="UserName" value="User" />
<add key="Password" value="Password" />
</appSettings>
Aplicativos leem essas configurações usando a coleção ConfigurationManager.AppSettings no namespace

System.Configuration :
string userName = System.Web.Configuration.ConfigurationManager.AppSettings["UserName"];

string password = System.Web.Configuration.ConfigurationManager.AppSettings["Password"];
O ASP.NET Core pode armazenar dados de configuração para o aplicativo em qualquer arquivo e carregá-los
como parte da inicialização de middleware. O arquivo padrão usado em modelos de projeto é appsettings.json:
{
"Logging": {
"LogLevel": {
"Default": "Debug",
}
},
// Here is where you can supply custom configuration settings, Since it is is JSON, everything is represented
as key: value pairs
// Name of section is your choice
"AppConfiguration": {
"UserName": "UserName",
"Password": "Password"
}
}
Carregar esse arquivo em uma instância de IConfiguration dentro de seu aplicativo é feito em Startup.cs:

{
}
O aplicativo lê de Configuration para obter as configurações:
string userName = Configuration.GetSection("AppConfiguration")["UserName"];

string password = Configuration.GetSection("AppConfiguration")["Password"];
Existem extensões para essa abordagem para tornar o processo mais robusto, tais como o uso de DI (injeção de
dependência) para carregar um serviço com esses valores. A abordagem de DI fornece um conjunto fortemente
tipado de objetos de configuração.
// Assume AppConfiguration is a class representing a strongly-typed version of AppConfiguration section

services.Configure<AppConfiguration>(Configuration.GetSection("AppConfiguration"));
NOTE
Para uma referência mais detalhada sobre configuração do ASP.NET Core, veja Configuração no ASP.NET Core.
Injeção de dependência nativa

Uma meta importante ao criar aplicativos escalonáveis e grandes é o acoplamento flexível de componentes e
serviços. A injeção de dependência é uma técnica popular para conseguir isso e é também um componente nativo
do ASP.NET Core.
Em aplicativos ASP.NET, os desenvolvedores contam com uma biblioteca de terceiros para implementar injeção de
dependência. Um biblioteca desse tipo é a Unity, fornecida pelas Diretrizes da Microsoft.
Um exemplo de configuração da injeção de dependência com Unity é a implementação de IDependencyResolver ,
que encapsula uma UnityContainer :
using Microsoft.Practices.Unity;
using System;
using System.Web.Http.Dependencies;
public class UnityResolver : IDependencyResolver

{
protected IUnityContainer container;
public UnityResolver(IUnityContainer container)

{
if (container == null)
{
throw new ArgumentNullException("container");
}
this.container = container;
}
public object GetService(Type serviceType)

{
try
{
return container.Resolve(serviceType);
}
catch (ResolutionFailedException)
{
return null;
}
}
public IEnumerable<object> GetServices(Type serviceType)

{
try
{
return container.ResolveAll(serviceType);
}
catch (ResolutionFailedException)
{
return new List<object>();
}
}
public IDependencyScope BeginScope()

{
var child = container.CreateChildContainer();
return new UnityResolver(child);
}

{
Dispose(true);
}
protected virtual void Dispose(bool disposing)

{
container.Dispose();
}
}
Crie uma instância de sua UnityContainer , registre seu serviço e defina o resolvedor de dependência de
HttpConfiguration para a nova instância de UnityResolver para o contêiner:
public static void Register(HttpConfiguration config)
{
var container = new UnityContainer();
container.RegisterType<IProductRepository, ProductRepository>(new HierarchicalLifetimeManager());
config.DependencyResolver = new UnityResolver(container);
// Other Web API configuration not shown.

}
Injete IProductRepository quando necessário:
public class ProductsController : ApiController

{
private IProductRepository _repository;
public ProductsController(IProductRepository repository)

{
}
// Other controller methods not shown.

}
Já que a injeção de dependência é parte do ASP.NET Core, você pode adicionar o serviço no método
ConfigureServices de Startup.cs:

{
services.AddTransient<IProductRepository, ProductRepository>();
}
O repositório pode ser injetado em qualquer lugar, como ocorria com a Unity.
NOTE
Para obter mais informações sobre injeção de dependência, confira Injeção de dependência.
Fornecer arquivos estáticos

Uma parte importante do desenvolvimento da Web é a capacidade de servir ativos estáticos, do lado do cliente. Os
exemplos mais comuns de arquivos estáticos são HTML, CSS, Javascript e imagens. Esses arquivos precisam ser
salvos no local de publicação do aplicativo (ou CDN ) e referenciados para que eles possam ser carregados por uma
solicitação. Esse processo foi alterado no ASP.NET Core.
No ASP.NET, arquivos estáticos são armazenados em vários diretórios e referenciados nas exibições.
No ASP.NET Core, arquivos estáticos são armazenados na "raiz da Web" (<raiz do conteúdo>/wwwroot), a menos
que configurado de outra forma. Os arquivos são carregados no pipeline de solicitação invocando o método de
extensão UseStaticFiles de Startup.Configure :

{
}
NOTE
Se você usar o .NET Framework como destino, instale o pacote NuGet Microsoft.AspNetCore.StaticFiles .
Por exemplo, um ativo de imagem na pasta wwwroot/imagens está acessível para o navegador em um local como
http://<app>/images/<imageFileName> .
NOTE
Para obter uma referência mais aprofundada sobre como servir arquivos estáticos no ASP.NET Core, veja Arquivos estáticos.
Recursos adicionais
Fazendo a portabilidade de Bibliotecas para o .NET Core
Migrar do ASP.NET MVC para ASP.NET Core MVC
Por Rick Anderson, Daniel Roth, Steve Smith, e Scott Addie

Este artigo mostra como começar a migrar um projeto ASP.NET MVC para ASP.NET Core MVC. No processo, ele
destaca muitas das coisas que mudaram do ASP.NET MVC. Migrando do ASP.NET MVC é um processo de várias
etapas e este artigo aborda a configuração inicial, básicas controladores e modos de exibição, conteúdo estático e
as dependências do lado do cliente. Artigos adicionais abrangem a migração de configuração e o código de
identidade encontrados em muitos projetos do ASP.NET MVC.
NOTE
Os números de versão nos exemplos podem não ser atuais. Talvez você precise atualizar seus projetos de acordo.
Criar o projeto do MVC do ASP.NET starter

Para demonstrar a atualização, vamos começar criando um aplicativo ASP.NET MVC. Criá-lo com o nome
WebApp1 para o namespace coincida com o projeto do ASP.NET Core que criamos na próxima etapa.
Opcional: alterar o nome da solução do WebApp1 à Mvc5. O Visual Studio exibe o novo nome da solução (Mvc5),
que torna mais fácil de informar deste projeto no próximo projeto.
Criar o projeto do ASP.NET Core

Criar um novo vazio aplicativo de web do ASP.NET Core com o mesmo nome que o projeto anterior (WebApp1)
para que os namespaces em dois projetos sejam correspondentes. Ter o mesmo namespace torna mais fácil copiar
o código entre os dois projetos. Você precisará criar esse projeto em um diretório diferente do projeto anterior
para usar o mesmo nome.
Opcional: criar um novo aplicativo de ASP.NET Core usando o aplicativo Web modelo de projeto. Nomeie o
projeto WebApp1e selecione uma opção de autenticação do contas de usuário individuais. Renomear este
aplicativo seja FullAspNetCore. Isso poupa de projeto tempo criando a conversão. Você pode examinar o
código gerado pelo modelo para ver o resultado final ou copiar o código para o projeto de conversão. Também
é útil quando você ficar preso em uma etapa de conversão a ser comparado com o projeto de modelo gerado.
Configurar o site para usar o MVC

Ao direcionar o .NET Core, o metapacote Microsoft é referenciado por padrão. Este pacote contém pacotes de
pacotes usados pelos aplicativos MVC. Se o destino do .NET Framework, referências de pacote devem estar
listadas individualmente no arquivo de projeto.
Ao direcionar o .NET Core, o metapacote Microsoft.AspNetCore.All é referenciado por padrão. Este pacote
contém pacotes de pacotes usados pelos aplicativos MVC. Se o destino do .NET Framework, referências de
pacote devem estar listadas individualmente no arquivo de projeto.
Ao direcionar o .NET Core ou .NET Framework, pacotes de pacotes usados pelos aplicativos MVC estão
listados individualmente no arquivo de projeto.
Microsoft.AspNetCore.Mvc é a estrutura do ASP.NET Core MVC. Microsoft.AspNetCore.StaticFiles é o
manipulador de arquivo estático. O tempo de execução do ASP.NET Core é modular e você deve explicitamente
optar por fornecer arquivos estáticos (consulte arquivos estáticos).
Abra o Startup.cs de arquivo e altere o código para corresponder ao seguinte:
namespace WebApp1
{
{
// For more information on how to configure your application, visit
https://go.microsoft.com/fwlink/?LinkID=398940
{
services.AddMvc();
}
pipeline.
{
{
}
{
routes.MapRoute(
name: "default",
});
}
}
}
O UseStaticFiles método de extensão adiciona o manipulador de arquivo estático. Conforme mencionado

anteriormente, o tempo de execução do ASP.NET é modular e você deve explicitamente optar por fornecer
arquivos estáticos. O UseMvc adiciona o método de extensão roteamento. Para obter mais informações, consulte
inicialização do aplicativo e roteamento.
Adicionar um controlador e o modo de exibição

Nesta seção, você adicionará um controlador de mínimo e o modo de exibição para servir como espaços
reservados para o controlador do ASP.NET MVC e exibições que na próxima seção, você migrará.
Adicionar um controladores pasta.
Adicionar um classe Controller denominado HomeController.cs para o controladores pasta.
Adicionar um modos de exibição pasta.
Adicionar um exibições/inicial pasta.
Adicionar um modo de exibição do Razor denominado index. cshtml para o exibições/inicial pasta.
A estrutura do projeto é mostrada abaixo:

Substitua o conteúdo do Views/Home/Index.cshtml arquivo com o seguinte:
<h1>Hello world!</h1>
Ver controladores e modos de exibição para obter mais informações.

Agora que temos um projeto de núcleo do ASP.NET mínimo do trabalho, podemos começar a migrar a
funcionalidade do projeto ASP.NET MVC. É preciso mover o seguinte:
conteúdo do lado do cliente (CSS, fontes e scripts)
controladores
modos de exibição
modelos
Agrupamento
filtros
Log de entrada/saída, a identidade (Isso é feito no próximo tutorial.)
Controladores e exibições
Copie cada um dos métodos do ASP.NET MVC HomeController para o novo HomeController . Observe que,
no ASP.NET MVC, tipo de método de ação retorno controlador interno do modelo é ActionResult; no
ASP.NET Core MVC, os retorno de métodos de ação IActionResult em vez disso. ActionResult
implementa IActionResult , portanto, não é necessário alterar o tipo de retorno de métodos de ação.
Cópia de About. cshtml, Contact. cshtml, e index. cshtml arquivos de exibição do Razor do projeto ASP.NET
MVC para o projeto ASP.NET Core.
Execute o aplicativo ASP.NET Core e cada método de teste. Ainda não migramos o arquivo de layout ou
estilos ainda, portanto, os modos de exibição renderizados contêm apenas o conteúdo nos arquivos de
exibição. Você não terá os links de arquivo gerado de layout para o About e Contact modos de exibição,
portanto, você precisará invocá-los a partir do navegador (substitua 4492 com o número da porta usado
em seu projeto).
http://localhost:4492/home/about
http://localhost:4492/home/contact
Observe a falta de estilo e itens de menu. Corrigiremos isso na próxima seção.
Conteúdo estático
Nas versões anteriores do ASP.NET MVC, o conteúdo estático foi hospedado da raiz do projeto da web e foi
Intercalado com arquivos do lado do servidor. No ASP.NET Core, conteúdo estático é hospedado na wwwroot
pasta. Você desejará copiar o conteúdo estático de seu aplicativo ASP.NET MVC antigo para o wwwroot pasta em
seu projeto ASP.NET Core. Nessa conversão de exemplo:
Cópia de /favicon.ico arquivo de projeto MVC antigo para o wwwroot pasta no projeto do ASP.NET Core.
O ASP.NET MVC antigo projeto usa Bootstrap para seu estilo e armazena a inicialização de arquivos no conteúdo
e Scripts pastas. O modelo, que gerou o antigo projeto do ASP.NET MVC, faz referência a inicialização no arquivo
de layout (Views/Shared/_Layout.cshtml). Você pode copiar o bootstrap. js e Bootstrap arquivos do ASP.NET MVC
de projeto para o wwwroot pasta no novo projeto. Em vez disso, vamos adicionar suporte para o Bootstrap (e
outras bibliotecas do lado do cliente) usando as CDNs na próxima seção.
Migrar o arquivo de layout

Cópia de viewstart arquivo do antigo do projeto ASP.NET MVC exibições pasta para do projeto ASP.NET
Core modos de exibição pasta. O viewstart arquivo não foi alterado no ASP.NET Core MVC.
Criar uma Views/Shared pasta.
Opcional: cópia viewimports. cshtml da FullAspNetCore do projeto MVC exibições pasta para do projeto
ASP.NET Core Modos de exibição pasta. Remover qualquer declaração de namespace na viewimports.
cshtml arquivo. O viewimports. cshtml fornece os namespaces para todos os arquivos de exibição de
arquivo e traz auxiliares de marca. Os auxiliares de marca são usados no novo arquivo de layout. O
viewimports. cshtml arquivo é novo para o ASP.NET Core.
Cópia de layout. cshtml arquivo do antigo do projeto ASP.NET MVC Views/Shared pasta para do projeto
ASP.NET Core Views/Shared pasta.
Abra layout. cshtml de arquivo e faça as seguintes alterações (o código completo é mostrado abaixo):
Substitua @Styles.Render("~/Content/css") com um <link> elemento do qual carregar Bootstrap (veja
abaixo).
Remova @Scripts.Render("~/bundles/modernizr") .
Comente a @Html.Partial("_LoginPartial") linha (envolvem a linha com @*...*@ ). Vamos voltar a ele em
um tutorial futuro.
Substitua @Scripts.Render("~/bundles/jquery") com um <script> elemento (veja abaixo).
Substitua @Scripts.Render("~/bundles/bootstrap") com um <script> elemento (veja abaixo).
A marcação de substituição para inclusão de CSS do Bootstrap:
href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u"
crossorigin="anonymous">
A marcação de substituição para o jQuery e Bootstrap JavaScript inclusão:
<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"
integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa"
Atualizada layout. cshtml arquivo é mostrado abaixo:

<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>@ViewBag.Title - My ASP.NET Application</title>
href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u"
crossorigin="anonymous">
</head>
<body>
<div class="navbar navbar-inverse navbar-fixed-top">
collapse">
</button>
@Html.ActionLink("Application name", "Index", "Home", new { area = "" }, new { @class =
"navbar-brand" })
</div>
<li>@Html.ActionLink("Home", "Index", "Home")</li>
<li>@Html.ActionLink("About", "About", "Home")</li>
<li>@Html.ActionLink("Contact", "Contact", "Home")</li>
</ul>
@*@Html.Partial("_LoginPartial")*@
</div>
</div>
</div>
@RenderBody()
<hr />
<footer>
<p>© @DateTime.Now.Year - My ASP.NET Application</p>
</footer>
</div>
<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"
integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa"
@RenderSection("scripts", required: false)
</body>
</html>
Exiba o site no navegador. Ele agora deve carregar corretamente, com os estilos esperados em vigor.
Opcional: você talvez queira usar o novo arquivo de layout. Para este projeto, você pode copiar o arquivo de
layout do FullAspNetCore projeto. O novo arquivo de layout utiliza auxiliares de marca e tem outras melhorias.
Configurar o agrupamento e minificação

Para obter informações sobre como configurar o agrupamento e minificação, consulte agrupamento e Minificação.
Resolver erros HTTP 500

Há muitos problemas que podem causar uma mensagem de erro HTTP 500 que não contêm informações sobre a
origem do problema. Por exemplo, se o viewimports arquivo contém um namespace que não existe em seu
projeto, você obterá um erro HTTP 500. Por padrão em aplicativos ASP.NET Core, o UseDeveloperExceptionPage
extensão é adicionada para o IApplicationBuilder e executados quando a configuração é desenvolvimento. Isso é
detalhado no código a seguir:
namespace WebApp1
{
{
// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?
LinkID=398940
{
services.AddMvc();
}
{
{
}
{
routes.MapRoute(
name: "default",
});
}
}
}
ASP.NET Core converte as exceções sem tratamento em um aplicativo web em respostas de erro HTTP 500.
Normalmente, os detalhes do erro não estão incluídos nessas respostas para evitar a divulgação de informações
possivelmente confidenciais sobre o servidor. Ver usando a página de exceção do desenvolvedor na tratar
erros para obter mais informações.
Recursos adicionais
Migrar da API Web ASP.NET para ASP.NET Core
Por Scott Addie e Steve Smith

Uma API da Web do ASP.NET 4. x é um serviço HTTP que atinja uma ampla gama de clientes, incluindo
navegadores e dispositivos móveis. Unifica o ASP.NET Core MVC do ASP.NET do 4.x e modelos de aplicativo de
API da Web em um modelo de programação mais simples conhecido como o ASP.NET Core MVC. Este artigo
demonstra as etapas necessárias para migrar da API de Web do ASP.NET 4.x para ASP.NET Core MVC.
Pré-requisitos
a Web
Examine o projeto de API da Web do ASP.NET 4.x

Como ponto de partida, este artigo usa o ProductsApp projeto criado no Introdução à API Web ASP.NET 2. Nesse
projeto, um projeto de API Web simples ASP.NET 4.x está configurado da seguinte maneira.
Na Global.asax.cs, é feita uma chamada para WebApiConfig.Register :
using System;
using System.Linq;
using System.Web;
using System.Web.Routing;
namespace ProductsApp
{
public class WebApiApplication : System.Web.HttpApplication
{
protected void Application_Start()
{
GlobalConfiguration.Configure(WebApiConfig.Register);
}
}
}
WebApiConfig é definido na App_Start pasta. Ele tem apenas um estático Register método:
using System;
using System.Linq;
namespace ProductsApp
{
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
// Web API configuration and services
// Web API routes

config.MapHttpAttributeRoutes();
config.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
);
}
}
}
Essa classe configura roteamento de atributo, embora na verdade não está sendo usado no projeto. Ele também
configura a tabela de roteamento, que é usada pela API Web ASP.NET. Nesse caso, a API da Web do ASP.NET 4.x
espera que as URLs para corresponder ao formato /api/{controller}/{id} , com {id} opcionais.
O ProductsApp projeto inclui um controlador. O controlador herda de ApiController e expõe dois métodos:
using ProductsApp.Models;
using System;
using System.Linq;
using System.Net;
namespace ProductsApp.Controllers
{
public class ProductsController : ApiController
{
Product[] products = new Product[]
{
new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 },
new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M },
new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M }
};
public IEnumerable<Product> GetAllProducts()

{
return products;
}
public IHttpActionResult GetProduct(int id)

{
var product = products.FirstOrDefault((p) => p.Id == id);
{
return NotFound();
}
return Ok(product);
}
}
}
O Product modelo usado pelo ProductsController é uma classe simples:
namespace ProductsApp.Models
{
{
public string Category { get; set; }
}
}
As seções a seguir demonstram a migração do projeto API da Web para ASP.NET Core MVC.
Criar o projeto de destino

Conclua as seguintes etapas no Visual Studio:
Vá para arquivo > nova > projeto > outros tipos de projeto > Soluções do visual Studio. Selecione
solução em brancoe o nome da solução WebAPIMigration. Clique o Okey botão.
Adicionar existente ProductsApp projeto à solução.
Adicione um novo aplicativo Web ASP.NET Core projeto à solução. Selecione o .NET Core estrutura na lista
suspensa de destino e, em seguida, selecione o API modelo de projeto. Nomeie o projeto ProductsCoree clique
no Okey botão.
Agora, a solução contém dois projetos. As seções a seguir explicam a migrar os ProductsApp o conteúdo do
projeto para o ProductsCore projeto.
Migrar configuração
ASP.NET Core não usa o App_Start pasta ou o global. asax arquivo e o Web. config arquivo for adicionado no
momento da publicação. Startup.CS é o substituto do global. asax e está localizado na raiz do projeto. O Startup
classe manipula todas as tarefas de inicialização do aplicativo. Para obter mais informações, consulte Inicialização
de aplicativo no ASP.NET Core.
No ASP.NET Core MVC, o roteamento de atributo é incluído por padrão quando UseMvc é chamado no
Startup.Configure . O seguinte UseMvc chamar substitui o ProductsApp do projeto app_start arquivo:

{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
Migrar modelos e controladores

Copiar sobre a ProductApp controlador do projeto e o modelo utilizado. Siga estas etapas:
1. Cópia Controllers/ProductsController.cs do projeto original para o novo.
2. Copiar todo o modelos pasta do projeto original para o novo.
3. Alterar os namespaces dos arquivos copiados para coincidir com o novo nome do projeto (ProductsCore).
Ajustar a using ProductsApp.Models; instrução no ProductsController.cs muito.
Neste ponto, criando os resultados do aplicativo em um número de erros de compilação. Os erros ocorrem
porque os seguintes componentes não existem no ASP.NET Core:
Classe ApiController
Namespace System.Web.Http
IHttpActionResult Interface
Corrija os erros da seguinte maneira:

1. Alteração ApiControllerpara ControllerBase. Adicione using Microsoft.AspNetCore.Mvc; para resolver o
ControllerBase referência.
2. Excluir using System.Web.Http; .
3. Alterar o GetProduct tipo de retorno da ação de IHttpActionResult para ActionResult<Product> .
Configurar o roteamento
Configure o roteamento da seguinte maneira:
1. Decore o ProductsController classe com os seguintes atributos:
[ApiController]
Precedente [Route] configura o atributo padrão de roteamento de atributo do controlador. O

[ApiController] atributo faz o roteamento de um requisito para todas as ações nesse controlador de
atributo.
Roteamento de atributo oferece suporte a tokens, como [controller] e [action] . Em tempo de execução,
cada token é substituído com o nome do controlador ou ação, respectivamente, para o qual o atributo foi
aplicado. Os tokens de reduzem o número de cadeias de caracteres mágicas no projeto. Os tokens de
também garantem rotas permanecerem sincronizadas com os correspondentes controladores e ações
quando automático renomear refatorações são aplicadas.
2. Habilitar as solicitações HTTP Get para o ProductController ações:
Aplicar a [HttpGet] atributo para o GetAllProducts ação.
Aplicar a [HttpGet("{id}")] de atributo para o GetProduct ação.
Após essas alterações e a remoção do não utilizado using instruções ProductsController.cs arquivo tem esta
aparência:
using System.Linq;
using ProductsCore.Models;
namespace ProductsCore.Controllers
{
[ApiController]
{
Product[] products = new Product[]
{
new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 },
new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M },
new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M }
};
public IEnumerable<Product> GetAllProducts()

{
return products;
}
public ActionResult<Product> GetProduct(int id)

{
var product = products.FirstOrDefault((p) => p.Id == id);
{
return NotFound();
}
return Ok(product);
}
}
}
Execute o projeto migrado e navegue até /api/products . É exibida uma lista completa dos três produtos. Navegue
para /api/products/1 . O primeiro produto será exibida.
Correção de compatibilidade
O Microsoft.AspNetCore.Mvc.WebApiCompatShim biblioteca fornece um shim de compatibilidade para mover
projetos de API da Web do ASP.NET 4.x ASP.NET Core. O shim de compatibilidade se estende do ASP.NET Core
para dar suporte a uma série de convenções da API de Web do ASP.NET 4. x 2. O exemplo portado anteriormente
neste documento é bastante básico que o shim de compatibilidade era desnecessário. Para projetos maiores, usem
o shim de compatibilidade pode ser útil para temporariamente preenchendo a lacuna de API entre o ASP.NET
Core e ASP.NET 4.x Web API 2.
O shim de compatibilidade de API da Web destina-se a ser usado como uma medida temporária para dar suporte
à migração grande API da Web projetos do ASP.NET 4.x ASP.NET Core. Ao longo do tempo, os projetos devem
ser atualizados para usar os padrões do ASP.NET Core em vez de usar o shim de compatibilidade.
Recursos de compatibilidade incluídos no Microsoft.AspNetCore.Mvc.WebApiCompatShim incluem:
Adiciona um ApiController tipo de forma que os tipos de base dos controladores não precisam ser
atualizados.
Habilita a associação de modelo de estilo de API da Web. Funções de associação de maneira semelhante do
ASP.NET de modelo do ASP.NET Core MVC 4. x MVC 5, por padrão. As alterações de correção de
compatibilidade associação de modelo para ser mais semelhante a convenções de associação de modelo do
ASP.NET Web API 2 de 4. x. Por exemplo, tipos complexos são vinculados automaticamente do corpo da
solicitação.
Estende a associação de modelo para que as ações do controlador podem usar parâmetros de tipo
HttpRequestMessage .
Adiciona os formatadores de mensagem, permitindo que as ações para retornar os resultados do tipo
HttpResponseMessage .
Adiciona métodos de resposta adicionais que ações de API Web 2 podem ter usado para servir as respostas:
HttpResponseMessage geradores de:
CreateResponse<T>
CreateErrorResponse
Métodos de ação de resultados:
BadRequestErrorMessageResult
ExceptionResult
InternalServerErrorResult
InvalidModelStateResult
NegotiatedContentResult
ResponseMessageResult
Adiciona uma instância do IContentNegotiator para o aplicativo disponibiliza os tipos de conteúdo relacionado
a negociação do e do contêiner de DI (injeção) de dependência Microsoft.AspNet.WebApi.Client. Exemplos de
tais tipos DefaultContentNegotiator e MediaTypeFormatter .
Para usar o shim de compatibilidade:
1. Instalar o Microsoft.AspNetCore.Mvc.WebApiCompatShim pacote do NuGet.
2. Registrar os serviços do shim de compatibilidade com o contêiner de injeção de dependência do aplicativo
chamando services.AddMvc().AddWebApiConventions() em Startup.ConfigureServices .
3. Definir web específicos de API roteia usando MapWebApiRoute sobre o IRouteBuilder no aplicativo do
IApplicationBuilder.UseMvc chamar.
Recursos adicionais
Tipos de retorno de ação do controlador na API Web ASP.NET Core
Migrar a configuração para o ASP.NET Core

No artigo anterior, começamos migrar um projeto ASP.NET MVC para ASP.NET Core MVC. Neste artigo, vamos
migrar a configuração.
Configuração da instalação
O ASP.NET Core não usa o global. asax e Web. config arquivos utilizadas de versões anteriores do ASP.NET. Em
versões anteriores do ASP.NET, a lógica de inicialização do aplicativo foi colocada em uma Application_StartUp
método dentro global. asax. Posteriormente, no ASP.NET MVC, uma Startup.cs arquivo foi incluído na raiz do
projeto; e ele foi chamado quando o aplicativo foi iniciado. ASP.NET Core tem adotado essa abordagem
completamente colocando toda lógica de inicialização na Startup.cs arquivo.
O Web. config arquivo também foi substituído no ASP.NET Core. Configuração em si agora pode ser configurada
como parte do procedimento de inicialização de aplicativo descrito em Startup.cs. Configuração ainda pode utilizar
arquivos XML, mas normalmente projetos do ASP.NET Core serão coloca valores de configuração em um arquivo
formatado em JSON, como appSettings. JSON. Sistema de configuração do ASP.NET Core também poderá
acessar facilmente as variáveis de ambiente, que podem fornecer um mais local seguro e robusto para valores
específicos do ambiente. Isso é especialmente verdadeiro para segredos, como cadeias de caracteres de conexão e
as chaves de API que não devem ser verificadas no controle de origem. Ver configuração para saber mais sobre a
configuração no ASP.NET Core.
Neste artigo, estamos começando com o projeto ASP.NET Core migrado parcialmente desde o artigo anterior. A
configuração da instalação, adicione o seguinte construtor e propriedade como o Startup.cs arquivo localizado na
raiz do projeto:

{
}
Observe que neste ponto, o Startup.cs arquivo não será compilado, pois precisamos adicionar o seguinte using
instrução:
Adicionar um appSettings. JSON arquivo na raiz do projeto usando o modelo de item apropriado:
Migrar definições da configuração da Web. config
Nosso projeto ASP.NET MVC incluído a cadeia de caracteres de conexão de banco de dados necessários no Web.
config, no <connectionStrings> elemento. Em nosso projeto do ASP.NET Core, vamos armazenar essas
informações na appSettings. JSON arquivo. Abra appSettings. JSONe observe que ele já inclui o seguinte:
{
"Data": {
"DefaultConnection": {
"ConnectionString": "Server=(localdb)\\MSSQLLocalDB;Database=_CHANGE_ME;Trusted_Connection=True;"
}
}
}
Na linha realçada descrita acima, altere o nome do banco de dados _CHANGE_ME para o nome do seu banco de
dados.
Resumo
ASP.NET Core coloca toda lógica de inicialização para o aplicativo em um único arquivo, em que os serviços
necessários e dependências podem ser definidas e configuradas. Ele substitui o Web. config arquivo com um
recurso de configuração flexíveis que pode aproveitar uma variedade de formatos de arquivo, como JSON, bem
como as variáveis de ambiente.
Migrar autenticação e identidade para o ASP.NET
Core
Por Steve Smith

No artigo anterior, podemos migrados de configuração de um projeto ASP.NET MVC para ASP.NET Core MVC.
Neste artigo, vamos migrar os recursos de gerenciamento de registro, logon e usuário.
Configurar identidade e associação

No ASP.NET MVC, os recursos de autenticação e identidade são configurados usando o ASP.NET Identity no
Startup.Auth.cs e IdentityConfig.cs, localizado na App_Start pasta. No ASP.NET Core MVC, esses recursos são
configurados na Startup.cs.
Instalar o Microsoft.AspNetCore.Identity.EntityFrameworkCore e Microsoft.AspNetCore.Authentication.Cookies
pacotes do NuGet.
Em seguida, abra Startup.cs e atualize o Startup.ConfigureServices método para usar os serviços de identidade e
o Entity Framework:

{
// Add EF services to the services container.
services.AddMvc();
}
Neste ponto, há dois tipos referenciados no código acima que nós ainda não tiver migrado do projeto ASP.NET
MVC: ApplicationDbContext e ApplicationUser . Criar um novo modelos pasta no ASP.NET Core de projeto e
adicionar duas classes a ele correspondente a esses tipos. Você encontrará o ASP.NET MVC versões dessas
classes em /Models/IdentityModels.cs, mas usaremos um arquivo por classe no projeto migrado, já que é mais
clara.
ApplicationUser.cs:
namespace NewMvcProject.Models
{
{
}
}
ApplicationDbContext.cs:
using Microsoft.AspNetCore.Identity.EntityFramework;
using Microsoft.Data.Entity;
namespace NewMvcProject.Models
{
{
: base(options)
{
}
protected override void OnModelCreating(ModelBuilder builder)

{
base.OnModelCreating(builder);
// Customize the ASP.NET Core Identity model and override the defaults if needed.
// For example, you can rename the ASP.NET Core Identity table names and more.
// Add your customizations after calling base.OnModelCreating(builder);
}
}
}
O projeto Web do ASP.NET Core MVC Starter não inclui muita personalização de usuários, ou o
ApplicationDbContext . Ao migrar um aplicativo real, você também precisará migrar todas as propriedades
personalizadas e métodos de usuário do seu aplicativo e DbContext classes, bem como outras classes de modelo
utiliza o seu aplicativo. Por exemplo, se sua DbContext tem uma DbSet<Album> , você precisa para migrar o Album
classe.
Com esses arquivos em vigor, o Startup.cs arquivo pode ser feito para compilar atualizando seu using instruções:
Nosso aplicativo agora está pronto para dar suporte a serviços de autenticação e identidade. Ele precisa apenas
ter esses recursos expostos aos usuários.
Migrar a lógica de registro e login

Com os serviços de identidade configurados para o aplicativo e o acesso a dados configurado usando o Entity
Framework e o SQL Server, estamos prontos para adicionar suporte para registro e logon para o aplicativo.
Lembre-se de que anterior no processo de migração estamos comentado uma referência a loginpartial na layout.
cshtml. Agora é hora de retornar a esse código, remova os comentários e adicione os controladores de necessárias
e os modos de exibição para dar suporte à funcionalidade de logon.
Remova os @Html.Partial de linha no layout. cshtml:
<li>@Html.ActionLink("Contact", "Contact", "Home")</li>

</ul>
@*@Html.Partial("_LoginPartial")*@
</div>
</div>
Agora, adicione uma nova exibição do Razor chamada loginpartial para o Views/Shared pasta:
Atualização loginpartial com o código a seguir (substitua todo seu conteúdo):
@inject SignInManager<ApplicationUser> SignInManager
@inject UserManager<ApplicationUser> UserManager
{
<form asp-area="" asp-controller="Account" asp-action="Logout" method="post" id="logoutForm"
class="navbar-right">
<li>
<a asp-area="" asp-controller="Manage" asp-action="Index" title="Manage">Hello
@UserManager.GetUserName(User)!</a>
</li>
<li>
<button type="submit" class="btn btn-link navbar-btn navbar-link">Log out</button>
</li>
</ul>
</form>
}
else
{
<li><a asp-area="" asp-controller="Account" asp-action="Register">Register</a></li>
<li><a asp-area="" asp-controller="Account" asp-action="Login">Log in</a></li>
</ul>
}
Neste ponto, você deve ser capaz de atualizar o site no seu navegador.
Resumo
ASP.NET Core apresenta alterações aos recursos de identidade do ASP.NET. Neste artigo, você viu como migrar
os recursos de gerenciamento de usuário e autenticação de identidade do ASP.NET para ASP.NET Core.
Migrar de ClaimsPrincipal. Current
Em projetos do ASP.NET 4.x, era comum usar ClaimsPrincipal. Current recuperar atual autenticado a identidade do
usuário e as declarações. No ASP.NET Core, essa propriedade não está definida. Código dependia ele precisa ser
atualizado para obter a identidade do usuário autenticado atual por meio de um modo diferente.
Dados específicos ao contexto em vez de dados estáticos

Ao usar o ASP.NET Core, os valores de ambos ClaimsPrincipal.Current e Thread.CurrentPrincipal não estão
definidas. Essas propriedades representam o estado estático, que normalmente evita o ASP.NET Core. Em vez
disso, arquitetura do ASP.NET Core é recuperar dependências (como a atual identidade do usuário) de coleções de
contexto específico de serviço (usando seu injeção de dependência modelo (DI)). Além disso,
Thread.CurrentPrincipal é o thread estático, portanto, ele não pode persistir as alterações em alguns cenários
assíncronos (e ClaimsPrincipal.Current apenas chama Thread.CurrentPrincipal por padrão).
Para entender as classificações do thread de problemas de membros estáticos podem levar a cenários assíncronos,
considere o seguinte trecho de código:
// Create a ClaimsPrincipal and set Thread.CurrentPrincipal

var identity = new ClaimsIdentity();
identity.AddClaim(new Claim(ClaimTypes.Name, "User1"));
Thread.CurrentPrincipal = new ClaimsPrincipal(identity);
// Check the current user

Console.WriteLine($"Current user: {Thread.CurrentPrincipal?.Identity.Name}");
// For the method to complete asynchronously

await Task.Yield();
// Check the current user after

Console.WriteLine($"Current user: {Thread.CurrentPrincipal?.Identity.Name}");
O código do exemplo anterior define Thread.CurrentPrincipal e verifica seu valor antes e depois de aguardar uma
chamada assíncrona. Thread.CurrentPrincipal é específico para o thread no qual ele é definido e o método
provavelmente retomar a execução em um thread diferente após o await. Consequentemente,
Thread.CurrentPrincipal está presente quando ele é verificado pela primeira vez, mas é nulo após a chamada para
await Task.Yield() .
Obtendo a atual identidade do usuário da coleção de serviço de injeção de dependência do aplicativo é mais
testável, também, desde que as identidades de teste podem ser injetadas com facilidade.
Recuperar o usuário atual em um aplicativo ASP.NET Core

Há várias opções para recuperar o atual usuário autenticado ClaimsPrincipal no ASP.NET Core no lugar de
ClaimsPrincipal.Current :
ControllerBase.User. Controladores do MVC podem acessar o usuário atual autenticado com suas usuário
propriedade.
HttpContext. Componentes com acesso ao atual HttpContext (por exemplo, middleware) pode obter o
usuário atual ClaimsPrincipal partir HttpContext.
Passada pelo chamador. Bibliotecas sem acesso ao atual HttpContext muitas vezes são chamados de
controladores ou componentes de middleware e pode ter a atual identidade do usuário passada como um
argumento.
IHttpContextAccessor. O projeto que está sendo migrado para o ASP.NET Core pode ser muito grande
para passar facilmente a atual identidade do usuário para todos os locais necessários. Nesses casos,
IHttpContextAccessor pode ser usado como uma solução alternativa. IHttpContextAccessor é capaz de
acessar atual HttpContext (se houver). Uma solução de curto prazo para obter a identidade do usuário atual
no código que ainda não foi atualizado para trabalhar com a arquitetura de orientado a DI do ASP.NET
Core seria:
Tornar IHttpContextAccessor disponíveis no contêiner de injeção de dependência chamando
AddHttpContextAccessor em Startup.ConfigureServices .
Obtenha uma instância de IHttpContextAccessor durante a inicialização e armazená-lo em uma variável
estática. A instância é disponibilizada para o código que anteriormente estava recuperando o usuário
atual de uma propriedade estática.
Recuperar o usuário atual ClaimsPrincipal usando HttpContextAccessor.HttpContext?.User . Se esse
código é usado fora do contexto de uma solicitação HTTP, o HttpContext é nulo.
O final de opção, usando IHttpContextAccessor , infringir os princípios do ASP.NET Core (preferindo dependências
injetadas dependências estáticas). Planeje, eventualmente, remova a dependência estático IHttpContextAccessor
auxiliar. Pode ser uma ponte útil, no entanto, quando a migração de grandes aplicativos ASP.NET existentes que
estavam usando previamente ClaimsPrincipal.Current .
Migrar de autenticação de associação do ASP.NET
para a identidade do ASP.NET Core 2.0
Por Isaac Levin

Este artigo demonstra como migrar o esquema de banco de dados para aplicativos do ASP.NET usando a
autenticação de associação para a identidade do ASP.NET Core 2.0.
NOTE
Este documento fornece as etapas necessárias para migrar o esquema de banco de dados para aplicativos baseados em
associação do ASP.NET para o esquema de banco de dados usado para a identidade do ASP.NET Core. Para obter mais
informações sobre como migrar da autenticação baseada em associação do ASP.NET para ASP.NET Identity, consulte migrar
um aplicativo existente da associação do SQL para o ASP.NET Identity. Para obter mais informações sobre a identidade do
ASP.NET Core, consulte Introdução à identidade no ASP.NET Core.
Revisão do esquema de associação

Antes do ASP.NET 2.0, os desenvolvedores eram encarregados de criar todo o processo de autenticação e
autorização para seus aplicativos. Com o ASP.NET 2.0, associação foi introduzida, fornecendo uma solução de
texto clichê para lidar com segurança em aplicativos ASP.NET. Os desenvolvedores tiveram acesso agora inicializar
um esquema em um banco de dados do SQL Server com o aspnet_regsql.exe comando. Depois de executar esse
comando, as tabelas a seguir foram criadas no banco de dados.
Para migrar aplicativos existentes para a identidade do ASP.NET Core 2.0, os dados nessas tabelas precisam ser
migrados para as tabelas usadas pelo novo esquema de identidade.
Esquema do ASP.NET Core 2.0 de identidade

O ASP.NET Core 2.0 segue o identidade princípio introduzido no ASP.NET 4.5. Embora o princípio é
compartilhado, a implementação entre as estruturas é diferente, até mesmo entre as versões do ASP.NET Core
(consulte migrar autenticação e identidade para o ASP.NET Core 2.0).
É a maneira mais rápida para exibir o esquema para a identidade do ASP.NET Core 2.0 criar um novo aplicativo
ASP.NET Core 2.0. Siga estas etapas no Visual Studio 2017:
Selecione Arquivo > Novo > Projeto.
Criar um novo aplicativo Web ASP.NET Core e nomeie o projeto CoreIdentitySample.
Selecione ASP.NET Core 2.0 na lista suspensa e selecione aplicativo Web. Esse modelo produz um páginas
do Razor aplicativo. Antes de clicar em Okey, clique em alterar autenticação.
Escolher contas de usuário individuais para os modelos de identidade. Por fim, clique em Okey, em seguida,
Okey. Visual Studio cria um projeto usando o modelo de identidade do ASP.NET Core.
O ASP.NET Core 2.0 usa de identidade Entity Framework Core para interagir com o banco de dados armazenar os
dados de autenticação. Em ordem para o aplicativo recém-criado trabalhar, preciso haver um banco de dados para
armazenar esses dados. Depois de criar um novo aplicativo, a maneira mais rápida para inspecionar o esquema em
um ambiente de banco de dados é criar o banco de dados usando as migrações do Entity Framework. Esse
processo cria um banco de dados, localmente ou em outro lugar, que imita o esquema. Examine a documentação
anterior para obter mais informações.
Para criar um banco de dados com o esquema de identidade do ASP.NET Core, execute as Update-Database
comando no Visual Studio Package Manager Console janela (PMC )—ele está localizado no ferramentas >
Gerenciador de pacotes NuGet > Package Manager Console. PMC dá suporte à execução de comandos de
Entity Framework.
Comandos do Entity Framework usam a cadeia de caracteres de conexão para o banco de dados especificado na
appSettings. JSON. A cadeia de conexão a seguir tem como alvo um banco de dados no localhost denominado
asp -net-core-identity. Nessa configuração, o Entity Framework está configurado para usar o DefaultConnection
cadeia de caracteres de conexão.
{
"DefaultConnection": "Server=localhost;Database=aspnet-core-
identity;Trusted_Connection=True;MultipleActiveResultSets=true"
}
}
Este comando cria o banco de dados especificado com o esquema e os dados necessários para a inicialização do
aplicativo. A imagem a seguir ilustra a estrutura da tabela que é criada com as etapas anteriores.
Migrar o esquema
Há diferenças sutis nos campos de associação e o ASP.NET Core Identity e estruturas de tabela. O padrão foi
alterado significativamente para a autenticação/autorização com aplicativos ASP.NET e ASP.NET Core. Os objetos
principais que ainda são utilizados com identidade são os usuários e funções. Aqui estão as tabelas de mapeamento
para os usuários, funções, e UserRoles.
Usuários
MEMBERSHIP(ASPNET_USERS/A
IDENTITY(ASPNETUSERS) SPNET_MEMBERSHIP)
Nome do campo Tipo Nome do campo Tipo
Id cadeia de caracteres aspnet_Users.UserId cadeia de caracteres
UserName cadeia de caracteres aspnet_Users.UserName cadeia de caracteres
Email cadeia de caracteres aspnet_Membership.Email cadeia de caracteres
NormalizedUserName cadeia de caracteres aspnet_Users.LoweredUserName cadeia de caracteres
NormalizedEmail cadeia de caracteres cadeia de caracteres

aspnet_Membership.LoweredEmail
PhoneNumber cadeia de caracteres aspnet_Users.MobileAlias cadeia de caracteres
LockoutEnabled bit aspnet_Membership.IsLockedOutbit
NOTE
Nem todos os mapeamentos de campo se parecer com relações um para um dos membros no ASP.NET Core Identity. A
tabela anterior usa o esquema de usuário da associação padrão e mapeia-os para o esquema de identidade do ASP.NET Core.
Todos os outros campos personalizados que foram usados para associação precisam ser mapeados manualmente. Em que
esse mapeamento, não há nenhum mapa para senhas, como critérios de senha e a senha salts não migram entre os dois. É
recomendável deixar a senha como null e pedir que os usuários redefinam suas senhas. No ASP.NET Core Identity,
LockoutEnd deverá ser definida para alguma data no futuro, se o usuário está bloqueado. Isso é mostrado no script de
migração.
Funções
IDENTITY(ASPNETROLES) MEMBERSHIP(ASPNET_ROLES)
Id cadeia de caracteres RoleId cadeia de caracteres
Name cadeia de caracteres RoleName cadeia de caracteres
NormalizedName cadeia de caracteres LoweredRoleName cadeia de caracteres
Funções de usuário
MEMBERSHIP(ASPNET_USERSIN
IDENTITY(ASPNETUSERROLES) ROLES)
RoleId cadeia de caracteres RoleId cadeia de caracteres
UserId cadeia de caracteres UserId cadeia de caracteres

Fazer referência as tabelas de mapeamento anterior durante a criação de um script de migração para os usuários e
funções. O exemplo a seguir pressupõe que você tenha dois bancos de dados em um servidor de banco de dados.
Um banco de dados contém o esquema de associação do ASP.NET existente e os dados. Outro banco de dados foi
criado usando as etapas descritas anteriormente. Os comentários são incluídas embutidas para obter mais
detalhes.
-- THIS SCRIPT NEEDS TO RUN FROM THE CONTEXT OF THE MEMBERSHIP DB

BEGIN TRANSACTION MigrateUsersAndRoles
use aspnetdb
-- INSERT USERS
INSERT INTO coreidentity.dbo.aspnetusers
(id,
username,
normalizedusername,
passwordhash,
securitystamp,
emailconfirmed,
phonenumber,
phonenumberconfirmed,
twofactorenabled,
lockoutend,
lockoutenabled,
accessfailedcount,
email,
normalizedemail)
SELECT aspnet_users.userid,
aspnet_users.username,
aspnet_users.loweredusername,
--Creates an empty password since passwords don't map between the two schemas
'',
--Security Stamp is a token used to verify the state of an account and is subject to change at any time.
It should be initialized as a new ID.
NewID(),
--EmailConfirmed is set when a new user is created and confirmed via email. Users must have this set
during migration to ensure they're able to reset passwords.
1,
aspnet_users.mobilealias,
CASE
WHEN aspnet_Users.MobileAlias is null THEN 0
ELSE 1
END,
--2-factor Auth likely wasn't setup in Membership for users, so setting as false.
0,
CASE
--Setting lockout date to time in the future (1000 years)
WHEN aspnet_membership.islockedout = 1 THEN Dateadd(year, 1000,
Sysutcdatetime())
ELSE NULL
END,
aspnet_membership.islockedout,
--AccessFailedAccount is used to track failed logins. This is stored in membership in multiple columns.
Setting to 0 arbitrarily.
0,
aspnet_membership.email,
aspnet_membership.loweredemail
FROM aspnet_users
LEFT OUTER JOIN aspnet_membership
ON aspnet_membership.applicationid =
aspnet_users.applicationid
AND aspnet_users.userid = aspnet_membership.userid
LEFT OUTER JOIN coreidentity.dbo.aspnetusers
ON aspnet_membership.userid = aspnetusers.id
WHERE aspnetusers.id IS NULL
-- INSERT ROLES
INSERT INTO coreIdentity.dbo.aspnetroles(id,name)
INSERT INTO coreIdentity.dbo.aspnetroles(id,name)
SELECT roleId,rolename
FROM aspnet_roles;
-- INSERT USER ROLES

INSERT INTO coreidentity.dbo.aspnetuserroles(userid,roleid)
SELECT userid,roleid
FROM aspnet_usersinroles;
IF @@ERROR <> 0
BEGIN
ROLLBACK TRANSACTION MigrateUsersAndRoles
RETURN
END
COMMIT TRANSACTION MigrateUsersAndRoles
Após a conclusão do script, o aplicativo ASP.NET Core Identity criado anteriormente é preenchido com os usuários
de associação. Os usuários precisam alterar suas senhas antes de fazer logon.
NOTE
Se o sistema de associação tivesse os usuários com nomes de usuário que não correspondiam a seu endereço de email, as
alterações são necessárias para o aplicativo criado anteriormente para acomodar isso. O modelo padrão espera UserName e
Email sejam iguais. Para situações em que eles são diferentes, o processo de logon deve ser modificado para usar
UserName em vez de Email .
No PageModel da página de logon, localizado em Pages\Account\Login.cshtml.cs, remova o [EmailAddress] de

atributos dos Email propriedade. Renomeie-o para nome de usuário. Isso exige uma alteração sempre que
EmailAddress mencionada, além de exibição e PageModel. O resultado é semelhante ao seguinte:
Próximas etapas
Neste tutorial, você aprendeu a porta que os usuários da associação do SQL para a identidade do ASP.NET Core
2.0. Para obter mais informações sobre a identidade do ASP.NET Core, consulte Introdução à identidade.
Migrar módulos e manipuladores HTTP para
middleware do ASP.NET Core
Por Matt Perdeck

Este artigo mostra como migrar do ASP.NET existentes módulos HTTP e manipuladores de System. webServer
para o ASP.NET Core middleware.
Módulos e manipuladores revistos

Antes de prosseguir para o middleware do ASP.NET Core, vamos primeiro recapitular como funcionam os
manipuladores e módulos HTTP:
Os manipuladores são:
As classes que implementam IHttpHandler
Usado para manipular solicitações com um determinado nome de arquivo ou a extensão, como .report
Configurado em Web. config
Módulos são:
As classes que implementam IHttpModule
Chamado para cada solicitação
Capazes de curto-circuito (interromper o processamento adicional de uma solicitação)
Capaz de adicionar à resposta HTTP, ou criar seus próprios
Configurado em Web. config
A ordem na qual os módulos de processam solicitações de entrada é determinada por:
1. O ciclo de vida do aplicativo, que é disparado pelo ASP.NET um eventos da série: BeginRequest,
AuthenticateRequest, etc. Cada módulo pode criar um manipulador para um ou mais eventos.
2. Para o mesmo evento, a ordem na qual eles foram configurados na Web. config.
Além de módulos, você pode adicionar manipuladores para os eventos de ciclo de vida para seus Global.asax.cs
arquivo. Esses manipuladores executar após os manipuladores nos módulos configurados.
De manipuladores e módulos para middleware

Middleware são mais simples do que os manipuladores e módulos HTTP:
Módulos, manipuladores Global.asax.cs, Web. config (exceto para a configuração do IIS ) e o ciclo de vida
do aplicativo serão excluídos
As funções dos módulos e manipuladores foram tomadas a tecla TAB middleware
Middleware são configurados usando o código em vez de em Web. config
Ramificação do pipeline permite que você envia solicitações para o middleware específico, com base em
não apenas a URL, mas também em cabeçalhos de solicitação, cadeias de caracteres de consulta, etc.
Middleware são muito semelhantes aos módulos:
Invocado em princípio, para cada solicitação
Capazes de curto-circuito a uma solicitação por não passar a solicitação para o próximo middleware
Capaz de criar sua própria resposta HTTP
Middleware e módulos são processados em uma ordem diferente:
Pedido de middleware é baseado na ordem em que eles são ser inseridos no pipeline de solicitação,
enquanto a ordem dos módulos se baseia principalmente na ciclo de vida do aplicativo eventos
Ordem de middleware para respostas é o inverso do que para solicitações, enquanto a ordem dos módulos
é o mesmo para solicitações e respostas
Consulte criar um pipeline de middleware com o IApplicationBuilder
Observe como na imagem acima, o middleware de autenticação sofrido curto-circuito a solicitação.
Migrando o código de módulo para middleware

Um módulo HTTP existente será semelhante a este:
// ASP.NET 4 module
using System;
using System.Web;
namespace MyApp.Modules
{
public class MyModule : IHttpModule
{
{
}
public void Init(HttpApplication application)

{
application.BeginRequest += (new EventHandler(this.Application_BeginRequest));
application.EndRequest += (new EventHandler(this.Application_EndRequest));
}
private void Application_BeginRequest(Object source, EventArgs e)

{
HttpContext context = ((HttpApplication)source).Context;
// Do something with context near the beginning of request processing.

}
private void Application_EndRequest(Object source, EventArgs e)

{
// Do something with context near the end of request processing.

}
}
}
Conforme mostrado na Middleware página, um middleware do ASP.NET Core é uma classe que expõe um
Invoke levando método um HttpContext e retornando um Task . Seu novo middleware terá esta aparência:
// ASP.NET Core middleware
namespace MyApp.Middleware
{
public class MyMiddleware
{
public MyMiddleware(RequestDelegate next)

{
_next = next;
}

{
// Clean up.
}
}
public static class MyMiddlewareExtensions

{
public static IApplicationBuilder UseMyMiddleware(this IApplicationBuilder builder)
{
return builder.UseMiddleware<MyMiddleware>();
}
}
}
O modelo de middleware anterior foi obtido da seção em escrever middleware.

O MyMiddlewareExtensions classe auxiliar torna mais fácil de configurar seu middleware em seu Startup classe.
O UseMyMiddleware método adiciona sua classe de middleware ao pipeline de solicitação. Serviços necessários
para o middleware são injetados no construtor do middleware.
O módulo pode encerrar uma solicitação, por exemplo, se o usuário não autorizado:
// ASP.NET 4 module that may terminate the request
private void Application_BeginRequest(Object source, EventArgs e)

{
if (TerminateRequest())
{
context.Response.End();
return;
}
}
Um middleware lida com isso, não chamando Invoke no próximo middleware no pipeline. Tenha em mente que
isso não encerra completamente a solicitação, porque o middleware anterior ainda será chamado quando a
resposta faz seu caminho através do pipeline.
// ASP.NET Core middleware that may terminate the request

{
if (!TerminateRequest())
// Clean up.
}
Ao migrar a funcionalidade do módulo para seu novo middleware, você pode achar que seu código não era
compilado porque o HttpContext classe foi alterado significativamente no ASP.NET Core. Mais tarde, você verá
como migrar para ASP.NET Core HttpContext novo.
Migrando inserção de módulo no pipeline de solicitação

Módulos HTTP normalmente são adicionados ao pipeline de solicitação usando Web. config:


<configuration>
<system.webServer>
<modules>
<add name="MyModule" type="MyApp.Modules.MyModule"/>
</modules>
</system.webServer>
</configuration>
Converter isso por adicionando seu novo middleware ao pipeline de solicitação no seu Startup classe:
{
{
}
else
{
}
app.UseMyMiddleware();
app.UseMyMiddlewareWithParams();
var myMiddlewareOptions = Configuration.GetSection("MyMiddlewareOptionsSection").Get<MyMiddlewareOptions>

();
var myMiddlewareOptions2 =
Configuration.GetSection("MyMiddlewareOptionsSection2").Get<MyMiddlewareOptions>();
app.UseMyMiddlewareWithParams(myMiddlewareOptions);
app.UseMyMiddlewareWithParams(myMiddlewareOptions2);
app.UseMyTerminatingMiddleware();
// Create branch to the MyHandlerMiddleware.

// All requests ending in .report will follow this branch.
app.MapWhen(
context => context.Request.Path.ToString().EndsWith(".report"),
appBranch => {
// ... optionally add more middleware to this branch
appBranch.UseMyHandler();
});
app.MapWhen(
context => context.Request.Path.ToString().EndsWith(".context"),
appBranch => {
appBranch.UseHttpContextDemoMiddleware();
});
{
routes.MapRoute(
name: "default",
});
}
O ponto exato no pipeline de onde você insere seu middleware novo depende do evento que ele tratado como um
módulo ( BeginRequest , EndRequest , etc.) e sua ordem na sua lista de módulos Web. config.
Conforme anteriormente não mencionado, há mais nenhum ciclo de vida do aplicativo no ASP.NET Core e a
ordem na qual as respostas são processadas pelo middleware é diferente da ordem usada pelos módulos. Isso
pode tornar sua decisão de ordenação mais desafiador.
Se a ordenação se torna um problema, você pode dividir seu módulo em vários componentes de middleware que
podem ser ordenados de forma independente.
Migrando o código de manipulador para middleware

Um manipulador HTTP é semelhante a:
// ASP.NET 4 handler
using System.Web;
namespace MyApp.HttpHandlers
{
public class MyHandler : IHttpHandler
{
public bool IsReusable { get { return true; } }
public void ProcessRequest(HttpContext context)

{
string response = GenerateResponse(context);
context.Response.ContentType = GetContentType();
context.Response.Output.Write(response);
}
// ...
private string GenerateResponse(HttpContext context)

{
string title = context.Request.QueryString["title"];
return string.Format("Title of the report: {0}", title);
}
private string GetContentType()

{
return "text/plain";
}
}
}
Em seu projeto ASP.NET Core, isso pode ser traduzido para um middleware semelhante a esta:
// ASP.NET Core middleware migrated from a handler
namespace MyApp.Middleware
{
public class MyHandlerMiddleware
{
// Must have constructor with this signature, otherwise exception at run time
public MyHandlerMiddleware(RequestDelegate next)
{
// This is an HTTP Handler, so no need to store next
}

{
string response = GenerateResponse(context);
context.Response.ContentType = GetContentType();
await context.Response.WriteAsync(response);
}
// ...
private string GenerateResponse(HttpContext context)

{
string title = context.Request.Query["title"];
return string.Format("Title of the report: {0}", title);
}
private string GetContentType()

{
return "text/plain";
}
}
public static class MyHandlerExtensions

{
public static IApplicationBuilder UseMyHandler(this IApplicationBuilder builder)
{
return builder.UseMiddleware<MyHandlerMiddleware>();
}
}
}
Este middleware é muito semelhante ao middleware correspondente aos módulos. A única diferença é que não há
aqui nenhuma chamada para _next.Invoke(context) . Isso faz sentido, porque o manipulador não é no final do
pipeline de solicitação, portanto, não haverá nenhum próximo middleware para invocar.
Migrando inserção manipulador no pipeline de solicitação

Configurar um manipulador HTTP é feito na Web. config e pode ter esta aparência:

<configuration>
<system.webServer>
<handlers>
<add name="MyHandler" verb="*" path="*.report" type="MyApp.HttpHandlers.MyHandler"
resourceType="Unspecified" preCondition="integratedMode"/>
</handlers>
</system.webServer>
</configuration>
Você pode converter isso adicionando seu novo middleware de manipulador para o pipeline de solicitação no seu
Startup classe, semelhante ao middleware convertido de módulos. O problema com essa abordagem é que ele
seria enviar todas as solicitações para seu novo middleware de manipulador. No entanto, você precisará apenas
solicitações com uma determinada extensão para alcançar seu middleware. Essa seria a mesma funcionalidade
que tinha com seu manipulador HTTP.
Uma solução é ramificar o pipeline para solicitações com uma determinada extensão, usando o MapWhen método
de extensão. Você pode fazer isso no mesmo Configure método onde você pode adicionar o outro middleware:
{
{
}
else
{
}
var myMiddlewareOptions = Configuration.GetSection("MyMiddlewareOptionsSection").Get<MyMiddlewareOptions>

();

app.MapWhen(
appBranch => {
});
app.MapWhen(
appBranch => {
});
{
routes.MapRoute(
name: "default",
});
}
MapWhen usa esses parâmetros:

1. Um lambda que usa o HttpContext e retorna true se a solicitação deve ir para baixo a ramificação. Isso
significa que você pode ramificar solicitações não apenas com base em sua extensão, mas também em
cabeçalhos de solicitação, parâmetros de cadeia de caracteres de consulta, etc.
2. Um lambda que usa um IApplicationBuilder e adiciona o middleware para a ramificação. Isso significa
que você pode adicionar outro middleware para a ramificação na frente do seu manipulador middleware.
Middleware adicionado ao pipeline antes da ramificação será invocada em todas as solicitações; a ramificação não
terá impacto sobre eles.
Opções de middleware usando o padrão de opções de carregamento
Alguns manipuladores e módulos têm opções de configuração que são armazenadas em Web. config. No entanto,
no ASP.NET Core um novo modelo de configuração é usado no lugar de Web. config.
O novo sistema de configuração fornece essas opções para resolver isso:
Injetar diretamente as opções para o middleware, como mostra a próxima seção.
Use o padrão de opções:
1. Crie uma classe para manter suas opções de middleware, por exemplo:
public class MyMiddlewareOptions

{
public string Param1 { get; set; }
public string Param2 { get; set; }
}
2. Store os valores de opção

O sistema de configuração permite que você armazene valores de opção em qualquer local desejado. No
entanto, a maioria dos locais use appSettings. JSON, portanto, vamos dar essa abordagem:
{
"MyMiddlewareOptionsSection": {
"Param1": "Param1Value",
"Param2": "Param2Value"
}
}
MyMiddlewareOptionsSection aqui é um nome de seção. Ele não precisa ser igual ao nome da sua classe
de opções.
3. Associar os valores de opção com a classe de opções
O padrão de opções usa a estrutura de injeção de dependência do ASP.NET Core para associar o tipo de
opções (como MyMiddlewareOptions ) com um MyMiddlewareOptions objeto que tem as opções reais.
Atualização de seu Startup classe:
a. Se você estiver usando appSettings. JSON, adicione-o ao construtor de configuração no Startup
construtor:

{
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
}
b. Configure o serviço de opções:

{
// Setup options service
// Load options from section "MyMiddlewareOptionsSection"

services.Configure<MyMiddlewareOptions>(
Configuration.GetSection("MyMiddlewareOptionsSection"));

services.AddMvc();
}
c. Associe suas opções de sua classe de opções:

{
// Setup options service
// Load options from section "MyMiddlewareOptionsSection"

services.Configure<MyMiddlewareOptions>(
Configuration.GetSection("MyMiddlewareOptionsSection"));

services.AddMvc();
}
4. Injete as opções para o construtor de middleware. Isso é semelhante a injeção de opções em um

controlador.
public class MyMiddlewareWithParams

{
private readonly MyMiddlewareOptions _myMiddlewareOptions;
public MyMiddlewareWithParams(RequestDelegate next,

IOptions<MyMiddlewareOptions> optionsAccessor)
{
_next = next;
_myMiddlewareOptions = optionsAccessor.Value;
}

{
// Do something with context near the beginning of request processing
// using configuration in _myMiddlewareOptions
// Do something with context near the end of request processing

// using configuration in _myMiddlewareOptions
}
}
O UseMiddleware método de extensão que adiciona o middleware para o IApplicationBuilder se

encarrega de injeção de dependência.
Isso não é limitado a IOptions objetos. Qualquer outro objeto requer que seu middleware pode ser
injetado dessa maneira.
Opções de middleware por meio de injeção direta de carregamento
O padrão de opções tem a vantagem que ele cria o acoplamento solto entre valores de opções e seus
consumidores. Depois que você associou a uma classe de opções com os valores de opções propriamente dito,
qualquer outra classe pode obter acesso às opções por meio da estrutura de injeção de dependência. Não é
necessário para passar ao redor de valores de opções.
Isso divide entanto se você quiser usar o mesmo middleware duas vezes, com opções diferentes. Por exemplo um
middleware de autorização usado em ramificações diferentes, permitindo que diferentes funções. É possível
associar dois objetos diferentes opções com a classe de opções de um.
A solução é obter os objetos de opções com os valores de opções propriamente dito no seu Startup de classe e
passá-las diretamente para cada instância do seu middleware.
1. Adicionar uma segunda chave a ser appSettings. JSON
Para adicionar um segundo conjunto de opções para o appSettings. JSON de arquivo, use uma nova chave
de para identificá-lo exclusivamente:
{
"MyMiddlewareOptionsSection2": {
"Param1": "Param1Value2",
"Param2": "Param2Value2"
},
"MyMiddlewareOptionsSection": {
"Param1": "Param1Value",
"Param2": "Param2Value"
}
}
2. Recuperar valores de opções e passá-los para o middleware. O Use... método de extensão (o que
adiciona seu middleware ao pipeline) é um lugar lógico para transmitir os valores de opção:
{
{
}
else
{
}
var myMiddlewareOptions =
Configuration.GetSection("MyMiddlewareOptionsSection").Get<MyMiddlewareOptions>();

app.MapWhen(
appBranch => {
});
app.MapWhen(
appBranch => {
});
{
routes.MapRoute(
name: "default",
});
}
3. Habilite o middleware para utilize um parâmetro de opções. Forneça uma sobrecarga da Use... método
de extensão (que usa o parâmetro options e passa-o para UseMiddleware ). Quando UseMiddleware é
chamado com parâmetros, ele passa os parâmetros para o construtor de middleware quando ele instancia
o objeto de middleware.
public static class MyMiddlewareWithParamsExtensions
{
public static IApplicationBuilder UseMyMiddlewareWithParams(
{
return builder.UseMiddleware<MyMiddlewareWithParams>();
}
public static IApplicationBuilder UseMyMiddlewareWithParams(

this IApplicationBuilder builder, MyMiddlewareOptions myMiddlewareOptions)
{
return builder.UseMiddleware<MyMiddlewareWithParams>(
new OptionsWrapper<MyMiddlewareOptions>(myMiddlewareOptions));
}
}
Observe como isso encapsula o objeto de opções em um OptionsWrapper objeto. Isso implementa
IOptions , conforme o esperado pelo construtor de middleware.
Migrando para o novo HttpContext

Você viu antes que o Invoke método no seu middleware usa um parâmetro de tipo HttpContext :
HttpContext foi alterado significativamente no ASP.NET Core. Esta seção mostra como converter as
propriedades mais usadas da System.Web.HttpContext para o novo Microsoft.AspNetCore.Http.HttpContext .
HttpContext
HttpContext. Items se traduz em:
IDictionary<object, object> items = httpContext.Items;
ID de solicitação exclusiva (nenhum equivalente System.Web.HttpContext)

Fornece uma id exclusiva para cada solicitação. Muito útil para incluir em seus logs.
string requestId = httpContext.TraceIdentifier;
HttpContext.Request
HttpContext.Request.HttpMethod se traduz em:
string httpMethod = httpContext.Request.Method;
HttpContext.Request.QueryString se traduz em:

IQueryCollection queryParameters = httpContext.Request.Query;
// If no query parameter "key" used, values will have 0 items

// If single value used for a key (...?key=v1), values will have 1 item ("v1")
// If key has multiple values (...?key=v1&key=v2), values will have 2 items ("v1" and "v2")
IList<string> values = queryParameters["key"];
// If no query parameter "key" used, value will be ""

// If single value used for a key (...?key=v1), value will be "v1"
// If key has multiple values (...?key=v1&key=v2), value will be "v1,v2"
string value = queryParameters["key"].ToString();
HttpContext.Request.Url e HttpContext.Request.RawUrl traduzir para:
// using Microsoft.AspNetCore.Http.Extensions;
var url = httpContext.Request.GetDisplayUrl();
HttpContext.Request.IsSecureConnection se traduz em:
var isSecureConnection = httpContext.Request.IsHttps;
HttpContext.Request.UserHostAddress se traduz em:
var userHostAddress = httpContext.Connection.RemoteIpAddress?.ToString();
HttpContext.Request.Cookies se traduz em:
IRequestCookieCollection cookies = httpContext.Request.Cookies;

string unknownCookieValue = cookies["unknownCookie"]; // will be null (no exception)
string knownCookieValue = cookies["cookie1name"]; // will be actual value
HttpContext.Request.RequestContext.RouteData se traduz em:
var routeValue = httpContext.GetRouteValue("key");
HttpContext.Request.Headers se traduz em:
// using Microsoft.AspNetCore.Http.Headers;
// using Microsoft.Net.Http.Headers;
IHeaderDictionary headersDictionary = httpContext.Request.Headers;
// GetTypedHeaders extension method provides strongly typed access to many headers

var requestHeaders = httpContext.Request.GetTypedHeaders();
CacheControlHeaderValue cacheControlHeaderValue = requestHeaders.CacheControl;
// For unknown header, unknownheaderValues has zero items and unknownheaderValue is ""
IList<string> unknownheaderValues = headersDictionary["unknownheader"];
string unknownheaderValue = headersDictionary["unknownheader"].ToString();
// For known header, knownheaderValues has 1 item and knownheaderValue is the value
IList<string> knownheaderValues = headersDictionary[HeaderNames.AcceptLanguage];
string knownheaderValue = headersDictionary[HeaderNames.AcceptLanguage].ToString();
HttpContext.Request.UserAgent se traduz em:

string userAgent = headersDictionary[HeaderNames.UserAgent].ToString();
HttpContext.Request.UrlReferrer se traduz em:
string urlReferrer = headersDictionary[HeaderNames.Referer].ToString();
HttpContext.Request.ContentType se traduz em:
MediaTypeHeaderValue mediaHeaderValue = requestHeaders.ContentType;

string contentType = mediaHeaderValue?.MediaType.ToString(); // ex. application/x-www-form-urlencoded
string contentMainType = mediaHeaderValue?.Type.ToString(); // ex. application
string contentSubType = mediaHeaderValue?.SubType.ToString(); // ex. x-www-form-urlencoded
System.Text.Encoding requestEncoding = mediaHeaderValue?.Encoding;
HttpContext.Request.Form se traduz em:
if (httpContext.Request.HasFormContentType)
{
IFormCollection form;
form = httpContext.Request.Form; // sync

// Or
form = await httpContext.Request.ReadFormAsync(); // async
string firstName = form["firstname"];

string lastName = form["lastname"];
}
WARNING
Ler os valores de formulário apenas se for o tipo de conteúdo sub x-www-form-urlencoded ou dados de formulário.
HttpContext.Request.InputStream se traduz em:
string inputBody;
using (var reader = new System.IO.StreamReader(
httpContext.Request.Body, System.Text.Encoding.UTF8))
{
inputBody = reader.ReadToEnd();
}
WARNING
Use esse código somente em um middleware de tipo de manipulador, no final de um pipeline.
Você pode ler o corpo bruto, conforme mostrado acima apenas uma vez por solicitação. Middleware de tentativa de ler o
corpo após a primeira leitura lê um corpo vazio.
Isso não se aplica à leitura de um formulário, conforme mostrado anteriormente, porque isso é feito de um buffer.
HttpContext.Response
HttpContext.Response.Status e HttpContext.Response.StatusDescription traduzir para:
httpContext.Response.StatusCode = StatusCodes.Status200OK;
HttpContext.Response.ContentEncoding e HttpContext.Response.ContentType traduzir para:
var mediaType = new MediaTypeHeaderValue("application/json");
mediaType.Encoding = System.Text.Encoding.UTF8;
httpContext.Response.ContentType = mediaType.ToString();
HttpContext.Response.ContentType em seu próprio também se traduz em:
httpContext.Response.ContentType = "text/html";
HttpContext.Response.Output se traduz em:
string responseContent = GetResponseContent();

await httpContext.Response.WriteAsync(responseContent);
HttpContext.Response.TransmitFile
Atendendo a um arquivo é discutida aqui.
HttpContext.Response.Headers
Enviar cabeçalhos de resposta é complicado pelo fato de que se você defini-las depois que nada foi escrito para o
corpo da resposta, eles não funcionará.
A solução é definir um método de retorno de chamada que será chamado direita antes de gravar do início da
resposta. Isso é feito melhor no início do Invoke método em seu middleware. É esse método de retorno de
chamada que define os cabeçalhos de resposta.
O código a seguir define um método de retorno de chamada chamado SetHeaders :

{
// ...
httpContext.Response.OnStarting(SetHeaders, state: httpContext);
O SetHeaders método de retorno de chamada teria esta aparência:

// using Microsoft.AspNet.Http.Headers;
private Task SetHeaders(object context)

{
var httpContext = (HttpContext)context;
// Set header with single value

httpContext.Response.Headers["ResponseHeaderName"] = "headerValue";
// Set header with multiple values

string[] responseHeaderValues = new string[] { "headerValue1", "headerValue1" };
httpContext.Response.Headers["ResponseHeaderName"] = responseHeaderValues;
// Translating ASP.NET 4's HttpContext.Response.RedirectLocation

httpContext.Response.Headers[HeaderNames.Location] = "http://www.example.com";
// Or
httpContext.Response.Redirect("http://www.example.com");
// GetTypedHeaders extension method provides strongly typed access to many headers

var responseHeaders = httpContext.Response.GetTypedHeaders();
// Translating ASP.NET 4's HttpContext.Response.CacheControl

responseHeaders.CacheControl = new CacheControlHeaderValue
{
MaxAge = new System.TimeSpan(365, 0, 0, 0)
// Many more properties available
};
// If you use .Net 4.6+, Task.CompletedTask will be a bit faster

}
HttpContext.Response.Cookies
Cookies de viagem para o navegador em um Set-Cookie cabeçalho de resposta. Como resultado, o envio de
cookies requer mesmo retorno de chamada usado para enviar cabeçalhos de resposta:

{
// ...
httpContext.Response.OnStarting(SetCookies, state: httpContext);
httpContext.Response.OnStarting(SetHeaders, state: httpContext);
O SetCookies método de retorno de chamada deve ser semelhante ao seguinte:
private Task SetCookies(object context)

{
var httpContext = (HttpContext)context;
IResponseCookies responseCookies = httpContext.Response.Cookies;
responseCookies.Append("cookie1name", "cookie1value");
responseCookies.Append("cookie2name", "cookie2value",
new CookieOptions { Expires = System.DateTime.Now.AddDays(5), HttpOnly = true });
// If you use .Net 4.6+, Task.CompletedTask will be a bit faster

}
Recursos adicionais
Visão geral de módulos HTTP e de manipuladores HTTP
Configuração
Inicialização de aplicativos
Middleware
Novidades do ASP.NET Core 2.1
Este artigo destaca as alterações mais significativas no ASP.NET Core 2.1, com links para a documentação
relevante.
SignalR
O SignalR foi reescrito para ASP.NET Core 2.1. O SignalR do ASP.NET Core inclui uma série de melhorias:
Um modelo de expansão simplificado.
Um novo cliente JavaScript sem dependência jQuery.
Um novo protocolo binário compacto com base em MessagePack.
Suporte para protocolos personalizados.
Um novo modelo de resposta de transmissão.
Suporte para clientes com base em WebSockets básicos.
Para obter mais informações, veja ASP.NET Core SignalR.
Biblioteca de classes Razor

O ASP.NET Core 2.1 torna mais fácil criar e incluir interface do usuário baseada em Razor em uma biblioteca e
compartilhá-la em vários projetos. O novo SDK do Razor habilita o build de arquivos do Razor em um projeto de
biblioteca de classes que podem ser empacotados em um pacote do NuGet. Exibições e páginas em bibliotecas
são descobertas automaticamente e podem ser substituídas pelo aplicativo. Ao integrar a compilação do Razor ao
build:
O tempo de inicialização do aplicativo é significativamente mais rápido.
Atualizações rápidas a modos de exibição e páginas Razor em tempo de execução ainda estão disponíveis
como parte de um fluxo de trabalho de desenvolvimento iterativo.
Para obter mais informações, veja Criar interface do usuário reutilizável usando o projeto de Biblioteca de Classes
do Razor.
Scaffolding e biblioteca de interface do usuário de Identidade

O ASP.NET Core 2.1 fornece a Identidade do ASP.NET Core como uma Biblioteca de Classes do Razor.
Aplicativos que incluem Identidade podem aplicar o novo scaffolder de Identidade para adicionar seletivamente o
código-fonte contido na RCL (Biblioteca de Classes do Razor) de Identidade. Talvez você queira gerar o código-
fonte para que você possa modificar o código e alterar o comportamento. Por exemplo, você pode instruir o
scaffolder a gerar o código usado no registro. Código gerado tem precedência sobre o mesmo código na RCL de
Identidade.
Aplicativos que não incluem autenticação podem aplicar o scaffolder de Identidade para adicionar o pacote de
Identidade RCL. Você tem a opção de selecionar o código de Identidade a ser gerado.
Para obter mais informações, veja Identidade scaffold em projetos ASP.NET Core.
HTTPS
Com o foco cada vez maior em segurança e privacidade, é importante habilitar HTTPS para aplicativos Web. A
imposição de HTTPS está se tornando cada vez mais rígida na Web. Sites que não usam HTTPS são considerados
inseguros. Navegadores (Chrome, Mozilla) estão começando a impor o uso de recursos Web em um contexto de
seguro. O RGPD requer o uso de HTTPS para proteger a privacidade do usuário. Quando usar HTTPS em
produção for fundamental, usar HTTPS no desenvolvimento pode ajudar a evitar problemas de implantação (por
exemplo, links inseguros). O ASP.NET Core 2.1 inclui uma série de melhorias que tornam mais fácil usar HTTPS
em desenvolvimento e configurar HTTPS em produção. Para obter mais informações, veja Impor HTTPS.
Ativo por padrão
Para facilitar o desenvolvimento de site seguro, HTTPS está habilitado por padrão. Da versão 2.1 em diante, o
Kestrel escuta em https://localhost:5001 quando um certificado de desenvolvimento local está presente. Um
certificado de desenvolvimento é criado:
Como parte da experiência de primeira execução do SDK do .NET Core, quando você usa o SDK pela primeira
vez.
Manualmente usando a nova ferramenta dev-certs .
Execute dotnet dev-certs https --trust para confiar no certificado.
Redirecionamento e imposição de HTTPS
Aplicativos Web geralmente precisam escutar em HTTP e HTTPS, mas, então redirecionam todo o tráfego HTTP
para HTTPS. Na versão 2.1, foi introduzido o middleware de redirecionamento de HTTPS especializado que
redireciona de modo inteligente com base na presença de portas do servidor associado ou de configuração.
O uso de HTTPS pode ser imposto ainda mais empregando HSTS (Protocolo de Segurança do Transporte Estrita
HTTP ). HSTS instrui navegadores a sempre acessarem o site por meio de HTTPS. O ASP.NET Core 2.1 adiciona
middleware HSTS compatível com opções para idade máxima, subdomínios e a lista de pré-carregamento de
HSTS.
Configuração para produção
Em produção, HTTPS precisa ser configurado explicitamente. Na versão 2.1, foi adicionado o esquema de
configuração padrão para configurar HTTPS para Kestrel. Os aplicativos podem ser configurados para usar:
Vários pontos de extremidade incluindo as URLs. Para obter mais informações, veja Implementação do
servidor Web Kestrel: configuração de ponto de extremidade.
O certificado a ser usado para HTTPS de um arquivo no disco ou de um repositório de certificados.
RGPD
O ASP.NET Core fornece APIs e modelos para ajudar a atender alguns dos requisitos do RGPD (Regulamento de
Proteção de Dados Geral) da UE. Para obter mais informações, veja Suporte RGPD no ASP.NET Core. Um
aplicativo de exemplo mostra como usar e permite que você teste a maioria dos pontos de extensão RGPD e APIs
adicionados aos modelos do ASP.NET Core 2.1.
É introduzido um novo pacote que simplifica a criação e a execução do teste. O pacote
Microsoft.AspNetCore.Mvc.Testing lida com as seguintes tarefas:
Copia o arquivo de dependência (*.deps) do aplicativo testado para a pasta bin do projeto de teste.
Define a raiz de conteúdo para a raiz do projeto do aplicativo testado para que arquivos estáticos e
páginas/exibições sejam encontrados quando os testes forem executados.
Fornece a classe WebApplicationFactory para simplificar a inicialização do aplicativo testado com TestServer.
O teste a seguir usa xUnit para verificar se a página de índice é carregada com um código de status de êxito e o
cabeçalho Content-Type correto:
public class BasicTests
: IClassFixture<WebApplicationFactory<RazorPagesProject.Startup>>
{
private readonly HttpClient _client;
public BasicTests(WebApplicationFactory<RazorPagesProject.Startup> factory)

{
_client = factory.CreateClient();
}
[Fact]
public async Task GetHomePage()
{
// Act
var response = await _client.GetAsync("/");
// Assert
response.EnsureSuccessStatusCode(); // Status Code 200-299
Assert.Equal("text/html; charset=utf-8",
response.Content.Headers.ContentType.ToString());
}
}
Para obter mais informações, veja o tópico Testes de integração.
[ApiController], ActionResult<T>
O ASP.NET Core 2.1 adiciona novas convenções de programação que facilitam o build de APIs Web limpas e
descritivas. ActionResult<T> é um novo tipo adicionado para permitir que um aplicativo retorne um tipo de
resposta ou qualquer outro resultado da ação (semelhante a IActionResult), enquanto ainda indica o tipo de
resposta. O atributo [ApiController] também foi adicionado como a maneira de aceitar convenções e
comportamentos específicos da API Web.
Para obter mais informações, veja Criar APIs Web com ASP.NET Core.
IHttpClientFactory
O ASP.NET Core 2.1 inclui um novo serviço IHttpClientFactory que torna mais fácil configurar e consumir
instâncias de HttpClient em aplicativos. O HttpClient já tem o conceito de delegar manipuladores que podem
ser vinculados uns aos outros para solicitações HTTP de saída. O alocador:
Torna o registro de instâncias de HttpClient por cliente nomeado mais intuitivo.
Implementa um manipulador Polly que permite que políticas Polly sejam usadas para Retry, CircuitBreakers
etc.
Para obter mais informações, veja Iniciar solicitações de HTTP.
Configuração de transporte do Kestrel

Com a liberação do ASP.NET Core 2.1, o transporte padrão do Kestrel deixa de ser baseado no Libuv, baseando-
se agora em soquetes gerenciados. Para obter mais informações, veja Implementação do servidor Web Kestrel:
configuração de transporte.
Construtor de host genérico

O Construtor de Host Genérico ( HostBuilder ) foi introduzido. Este construtor pode ser usado para aplicativos que
não processam solicitações HTTP (mensagens, tarefas em segundo plano etc.).
Para obter mais informações, veja Host Genérico do .NET.
Modelos do SPA atualizados

Os modelos de Aplicativo de Página Única para Angular, React e React com Redux são atualizados para usar
estruturas de projeto padrão e criar sistemas para cada estrutura.
O modelo Angular se baseia na CLI Angular e os modelos React baseiam-se em create-react-app. Para obter mais
informações, veja Usar os modelos de aplicativo de página única com ASP.NET Core.
Pesquisa de Razor Pages para ativos Razor

Na versão 2.1, as Razor Pages pesquisam ativos do Razor (como layouts e parciais) nos seguintes diretórios na
ordem listada:
1. Pasta de Páginas atual.
2. /Pages/Shared/
3. /Views/Shared/
Razor Pages em uma área

Razor Pages agora são compatíveis com áreas. Para ver um exemplo de áreas, crie um novo aplicativo Web Razor
Pages com contas de usuário individuais. Um aplicativo Web Razor Pages com contas de usuário individuais inclui
/Areas/Identity/Pages.
Versão de compatibilidade do MVC

O método SetCompatibilityVersion permite que um aplicativo aceite ou recuse as possíveis alterações da falha de
comportamento introduzidas no ASP.NET Core MVC 2.1 ou posteriores.
Migrar de 2.0 para 2.1

Veja Migrar do ASP.NET Core 2.0 para 2.1.
Para obter uma lista de alterações, vejas as Notas de versão do ASP.NET Core 2.1.
Este artigo destaca as alterações mais significativas no ASP.NET Core 2.0, com links para a documentação
relevante.
Páginas do Razor
Páginas do Razor é um novo recurso do ASP.NET Core MVC que torna a codificação de cenários focados em
página mais fácil e produtiva.
Para obter mais informações, consulte a introdução e o tutorial:
Metapacote do ASP.NET Core

Um novo metapacote do ASP.NET Core inclui todos os pacotes feitos e com suporte pelas equipes do ASP.NET
Core e do Entity Framework Core, juntamente com as respectivas dependências internas e de terceiros. Você não
precisa mais escolher recursos individuais do ASP.NET Core por pacote. Todos os recursos estão incluídos no
pacote Microsoft.AspNetCore.All. Os modelos padrão usam este pacote.
Para obter mais informações, consulte Metapacote do Microsoft.AspNetCore.All para ASP.NET Core 2.0.
Repositório de tempo de execução

Aplicativos que usam o metapacote Microsoft.AspNetCore.All aproveitam automaticamente o novo repositório de
tempo de execução do .NET Core. O repositório contém todos os ativos de tempo de execução necessários para
executar aplicativos ASP.NET Core 2.0. Quando você usa o metapacote Microsoft.AspNetCore.All , nenhum ativo
dos pacotes NuGet do ASP.NET Core referenciados são implantados com o aplicativo porque eles já estão no
sistema de destino. Os ativos no repositório de tempo de execução também são pré-compilados para melhorar o
tempo de inicialização do aplicativo.
Para obter mais informações, consulte Repositório de tempo de execução
.NET Standard 2.0

Os pacotes do ASP.NET Core 2.0 são direcionados ao .NET Standard 2.0. Os pacotes podem ser referenciados por
outras bibliotecas do .NET Standard 2.0 e podem ser executados em implementações em conformidade com o
.NET Standard 2.0, incluindo o .NET Core 2.0 e o .NET Framework 4.6.1.
O metapacote Microsoft.AspNetCore.All aborda apenas o .Net Core 2.0 porque ele foi projetado para ser utilizado
com o repositório de tempo de execução do .Net Core 2.0.
Atualização da configuração
Uma instância de IConfiguration é adicionada ao contêiner de serviços por padrão no ASP.NET Core 2.0.
IConfiguration no contêiner de serviços torna mais fácil para aplicativos recuperarem valores de configuração do
contêiner.
Para obter informações sobre o status da documentação planejada, consulte o problema do GitHub.
Atualização de registro em log
No ASP.NET Core 2.0, o log será incorporado no sistema de DI (injeção de dependência) por padrão. Você
adiciona provedores e configura a filtragem no arquivo Program.cs em vez de usar o arquivo Startup.cs. E o
ILoggerFactory padrão dá suporte à filtragem de forma que lhe permite usar uma abordagem flexível para
filtragem entre provedores e filtragem específica do provedor.
Para obter mais informações, consulte Introdução ao registro em log.
Atualização de autenticação
Um novo modelo de autenticação torna mais fácil configurar a autenticação para um aplicativo usando a DI.
Novos modelos estão disponíveis para configurar a autenticação para aplicativos Web e APIs Web usando o
[Azure AD B2C ] (https://azure.microsoft.com/services/active-directory-b2c/).
Atualização de identidade
Tornamos mais fácil criar APIs Web seguras usando a identidade do ASP.NET Core 2.0. Você pode adquirir tokens
de acesso para acessar suas APIs Web usando a MSAL (Biblioteca de Autenticação da Microsoft).
Para obter mais informações sobre alterações de autenticação no 2.0, consulte os seguintes recursos:
Habilitar a geração de código QR para aplicativos de autenticador no ASP.NET Core
Migrar a autenticação e a identidade para o ASP.NET Core 2.0
Modelos do SPA
Modelos de projeto de SPA (aplicativo de página único) para Angular, Aurelia, Knockout.js, React.js e React.js com
Redux estão disponíveis. O modelo Angular foi atualizado para Angular 4. Os modelos Angular e React estão
disponíveis por padrão. Para saber como obter os outros modelos, confira Criar um novo projeto de SPA. Para
obter informações de como criar um SPA no ASP.NET Core, confira Usar JavaScriptServices para criar aplicativos
de página única.
Melhorias do Kestrel
O servidor Web Kestrel tem novos recursos que o tornam mais adequado como um servidor voltado para a
Internet. Uma série de opções de configuração de restrição de servidor serão adicionadas na nova propriedade
Limits da classe KestrelServerOptions . Adicione limites para o seguinte:

Para obter mais informações, consulte Implementação do servidor Web Kestrel no ASP.NET Core.
WebListener renomeado para HTTP.sys

Os pacotes Microsoft.AspNetCore.Server.WebListener e Microsoft.Net.Http.Server foram mesclados em um novo
pacote Microsoft.AspNetCore.Server.HttpSys . Os namespaces foram atualizados para corresponderem.
Para obter mais informações, consulte Implementação do servidor Web HTTP.sys no ASP.NET Core.
Suporte aprimorado a cabeçalho HTTP
Ao usar o MVC para transmitir um FileStreamResult ou um FileContentResult , agora você tem a opção de
definir uma ETag ou uma data LastModified no conteúdo que você transmitir. Você pode definir esses valores no
conteúdo retornado com código semelhante ao seguinte:
var data = Encoding.UTF8.GetBytes("This is a sample text from a binary array");

var entityTag = new EntityTagHeaderValue("\"MyCalculatedEtagValue\"");
return File(data, "text/plain", "downloadName.txt", lastModified: DateTime.UtcNow.AddSeconds(-5), entityTag:
entityTag);
O arquivo retornado para os visitantes será decorado com os cabeçalhos HTTP apropriados para os valores ETag
e LastModified .
Se um visitante do aplicativo solicitar o conteúdo com um cabeçalho de solicitação de intervalo, o ASP.NET Core
reconhecerá a solicitação e lidará com o cabeçalho. Se parte do conteúdo solicitado puder ser entregue, o
ASP.NET Core ignorará a parte em questão e retornará apenas o conjunto de bytes solicitado. Você não precisa
gravar nenhum manipulador especial em seus métodos para adaptar ou manipular esse recurso; ele é manipulado
automaticamente para você.
Inicialização de hospedagem e o Application Insights

Ambientes de hospedagem podem injetar dependências de pacote extras e executar código durante a inicialização
do aplicativo, sem que o aplicativo precise tomar uma dependência explicitamente ou chamar algum método. Esse
recurso pode ser usado para habilitar determinados ambientes para recursos de "esclarecimento" exclusivos para
esse ambiente sem que o aplicativo precise saber antecipadamente.
No ASP.NET Core 2.0, esse recurso é usado para habilitar o diagnóstico do Application Insights automaticamente
durante a depuração no Visual Studio e (depois de optar por isto) quando em execução nos Serviços de
Aplicativos do Azure. Como resultado, os modelos de projeto não adicionam mais código e pacotes do Application
Insights por padrão.
Uso automático de tokens antifalsificação

O ASP.NET Core sempre ajudou a fazer a codificação HTML de seu conteúdo por padrão, mas com a nova versão,
estamos dando um passo adicional para ajudar a impedir ataques de XSRF (falsificação de solicitação entre sites).
O ASP.NET Core agora emitirá tokens antifalsificação por padrão e os validará em ações de POST do formulário e
em páginas sem configuração adicional.
Para obter mais informações, confira Impedir ataques de XSRF/CSRF (solicitação intersite forjada).
Pré-compilação automática
A pré-compilação da exibição do Razor é habilitada durante a publicação por padrão, reduzindo o tamanho da
saída de publicação e o tempo de inicialização do aplicativo.
Para obter mais informações, confira Compilação e pré-compilação de exibição Razor no ASP.NET Core.
Suporte ao Razor para C# 7.1

O mecanismo de exibição Razor foi atualizado para funcionar com o novo compilador Roslyn. Isso inclui suporte
para recursos do C# 7.1 como expressões padrão, nomes de tupla inferidos e correspondência de padrões com
genéricos. Para usar o C# 7.1 em seu projeto, adicione a seguinte propriedade no arquivo de projeto e, em
seguida, recarregue a solução:
<LangVersion>latest</LangVersion>
Para obter informações sobre o status dos recursos do C# 7.1, consulte o repositório GitHub do Roslyn.
Outras atualizações de documentação para 2.0

Perfis de publicação do Visual Studio para a implantação do aplicativo ASP.NET Core
Configurar a autenticação do Facebook
Configurar a autenticação do Twitter
Configurar a autenticação do Google
Configurar a autenticação da conta da Microsoft
Diretrizes de migração
Para obter diretrizes sobre como migrar aplicativos ASP.NET Core 1.x para o ASP.NET Core 2.0, consulte os
seguintes recursos:
Migrar do ASP.NET Core 1.x para o ASP.NET Core 2.0
Migrar a autenticação e a identidade para o ASP.NET Core 2.0
Para obter uma lista de alterações, consulte as Notas de versão do ASP.NET Core 2.0.
Para se conectar ao progresso e aos planos da equipe de desenvolvimento do ASP.NET Core, fique ligado no
ASP.NET Community Standup.
O ASP.NET Core 1.1 inclui os seguintes novos recursos:

Middleware de regravação de URL
Middleware de Cache de Resposta
Componentes de exibição como auxiliares de marcação
Middleware como filtros MVC
Provedor de TempData baseado em cookie
Provedor de logs do Serviço de Aplicativo do Azure
Repositórios de chaves da Proteção de Dados de armazenamento do Azure e do Redis
Servidor WebListener para Windows
Suporte a WebSockets
Escolhendo entre as versões 1.0 e 1.1 do ASP.NET Core

O ASP.NET Core 1.1 tem mais recursos do que o 1.0. Em geral, recomendamos o uso da última versão.
Notas de versão do ASP.NET Core 1.1.0
Para se conectar ao progresso e aos planos da equipe de desenvolvimento do ASP.NET Core, fique ligado no
ASP.NET Community Standup.

API Web Com o ASP - Net Core

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

API Web Com o ASP - Net Core

Enviado por

Direitos autorais:

Formatos disponíveis

Contents

Por Daniel Roth, Rick Anderson e Shaun Luttin

Por que usar o ASP.NET Core?

Compilar APIs Web e uma interface do usuário da Web usando o

Desenvolvimento do lado do cliente

ASP.NET Core direcionado para o .NET Framework

Como baixar uma amostra

ASP.NET CORE ASP.NET 4.X

Build para Windows, macOS ou Linux Build para Windows

Várias versões por computador Uma versão por computador

Desempenho superior ao do ASP.NET 4.x Bom desempenho

Cenários do ASP.NET Core

Cenários do ASP.NET 4.x

Criar um projeto de aplicativo Web

dotnet new webapp -o aspnetcoreapp

dotnet dev-certs https --trust

O comando anterior exibe a caixa de diálogo a seguir:

Selecione Sim se você concordar com confiar no certificado de desenvolvimento.

Editar uma página do Razor

<p>Hello, world! The time on the server is @DateTime.Now</p>

Esse é um trabalho em andamento.

Esse é um trabalho em andamento.

Por Rick Anderson e Mike Wasson

API DESCRIÇÃO CORPO DA SOLICITAÇÃO CORPO DA RESPOSTA

GET /api/todo Obter todos os itens de Nenhum Matriz de itens de tarefas

GET /api/todo/{id} Obter um item por ID Nenhum Item de tarefas pendentes

PUT /api/todo/{id} Atualizar um item existente Item de tarefas pendentes Nenhum

DELETE /api/todo/{id} Excluir um item Nenhum Nenhum

O diagrama a seguir mostra o design básico do aplicativo.

Se usar o Internet Explorer, você deverá salvar um arquivo values.json.

O banco de dados gera o Id quando um TodoItem é criado.

public DbSet<TodoItem> TodoItems { get; set; }

Registrar o contexto de banco de dados

public void Configure(IApplicationBuilder app)

public void Configure(IApplicationBuilder app)

public TodoController(TodoContext context)

public TodoController(TodoContext context)

Obter itens pendentes

[HttpGet("{id}", Name = "GetTodo")]

[HttpGet("{id}", Name = "GetTodo")]

Esses métodos de implementam os dois métodos GET:

Aqui está um exemplo de resposta HTTP para o método GetAll :

[HttpGet("{id}", Name = "GetTodo")]

[HttpGet("{id}", Name = "GetTodo")]

Name = "GetTodo" cria uma rota nomeada. Rotas nomeadas:

Implementar as outras operações CRUD

return CreatedAtRoute("GetTodo", new { id = item.Id }, item);

return CreatedAtRoute("GetTodo", new { id = item.Id }, item);

[HttpGet("{id}", Name = "GetTodo")]

[HttpGet("{id}", Name = "GetTodo")]

Usar o Postman para enviar uma solicitação Create

Clique no botão Enviar.

Clique na guia Cabeçalhos no painel Resposta e copie o valor do cabeçalho Local:

var todo = _context.TodoItems.Find(id);

A resposta Delete é 204 (Sem conteúdo).

Chamar a API Web com o jQuery

const uri = 'api/todo';

$('<tr><td><input disabled="true" type="checkbox" ' + checked + '></td>' +

$('<tr><td><input disabled="true" type="checkbox" ' + checked + '></td>' +

Adicionar um item pendente

Atualizar um item pendente

Excluir um item pendente

Por Rick Anderson e Mike Wasson