TOC

This article is currently in the process of being translated into Portuguese (~99% done).

HttpContext:

Cookies

O HTTTP, protocolo que toma conta da comunicação entre um servidor e um cliente na web, diz-se um protocolo stateless (sem estado). Por exemplo, se um utilizador faz dois pedidos de páginas web a um servidor, nenhuma informação é automaticamente partilhada entre esses dois pedidos. Para isso, os programadores terão de utilizar algo chamado cookies (ou sessões - mais sobre isso posteriormente) para partilhar informação entre pedidos. Isto é extremamente útil em inúmeras situações, p.e. para manter um utilizador autenticado quando navega para novas páginas, etc.

Praticamente todas as tecnologias de servidor têm suporte nativo para trabalhar com cookies e obviamente a framework ASP.NET MVC também. De facto, trabalhar com cookies é bastante fácil, graças às funcionalidades encontradas na classe HttpContext. Neste artigo, irás aprender como criar uma cookie e como a ler após a sua criação, de maneira a nos permitir partilhar informação acerca de um visitante específico entre os seus pedidos.

O que é uma cookie?

Uma cookie é basicamente um ficheiro físico em texto simples, guardado pelo cliente (habitualmente um browser), associado a um website específico. O cliente vai então permitir a esse website específico que em pedidos subsequentes obtenha informação guardada nesse ficheiro, basicamente permitindo ao servidor (ou mesmo o próprio cliente) guardar informação para utilizar mais tarde.

Criar e ler cookies

Criar uma cookie, para mais tarde a ler, com ASP.NET MVC é muito, muito simples. Aqui está como podes enviar uma cookie a um cliente, na sua forma mais básica:

HttpContext.Response.Cookies.Append("user_id", "1");

Note-se como a propriedade Response da classe HttpContext foi utilizada, onde podemos aceder à propriedade Cookies. Ao utilizar o método Append(), adicionamos uma Cookie ao output, fornecendo-lhe um nome e um valor. O nome (user_id) é utilizado posteriormente para obter de volta o seu valor (1). E obter o valor de volta é igualmente fácil:

var userId = HttpContext.Request.Cookies["user_id"];

Note-se como agora utilizamos a propriedade Request em vez de Response quando lemos o valor de volta - a razão para isso é que ao criar a cookie é adicionada informação à resposta enviada ao cliente, enquanto que para a ler é puxada informação do pedido feito pelo cliente (um browser normal vai enviar automaticamente todos os cookies relevantes com cada pedido).

Então, agora que sabemos ler e escrever informação em cookies, vamos juntar isso num pequeno exemplo, onde adicionamos um pedaço de informação como uma cookie se ainda não estiver presente - isto é uma ótima maneira de sabermos se um utilizador já visitou previamente a página ou não:

public class CookiesController : Controller
{
    public IActionResult Index()
    {
if(!HttpContext.Request.Cookies.ContainsKey("first_request"))
{
    HttpContext.Response.Cookies.Append("first_request", DateTime.Now.ToString());
    return Content("Welcome, new visitor!");
}
else
{
    DateTime firstRequest = DateTime.Parse(HttpContext.Request.Cookies["first_request"]);
    return Content("Welcome back, user! You first visited us on: " + firstRequest.ToString());
}
    }
}

A ação do nosso Controlador agora produz uma resposta com base no visitante ter ou não previamente visitado a página, verificando sempre se existe uma cookie com o nome "first_request" - se esta cookie não está presente, adicionamos-a, colocando o valor como a data e hora atuais. Se a cookie está presente, assumimos que o visitante já visitou a página anteriormente e podemos dizer ao visitante quando ocorreu a sua primeira visita.

Este foi um pequeno resumo acerca de cookies e agora já sabemos como as escrever e ler. Mas ainda há mais um pouco que precisamos saber, se queremos tirar partido das cookies.

CookieOptions

Como terceiro parâmetro opcional do método acima utilizado Append(), podemos passar uma instância da classe CookieOptions. Isto permite-nos ajustar vários aspetos importantes da nossa cookie, p.e. durante quanto tempo se deve manter válida e outras coisas como domínio e caminho (path). Antes de avançarmos através das propriedades mais importantes, certifiquem-se que o namespace Microsoft.AspNetCore.Http esteja incluído, onde a classe CookieOptions reside:

using Microsoft.AspNetCore.Http;

Criamos agora uma instância da classe CookieOptions, que utiliza definições por defeito, e de seguida passamos-a ao método Append():

CookieOptions cookieOptions = new CookieOptions();            
HttpContext.Response.Cookies.Append("first_request", DateTime.Now.ToString(), cookieOptions);

Antes de a passarmos (ou seja, entre as duas linhas de código), provavelmente queremos alterar algumas opções. Aqui estão as mais relevantes:

CookieOptions.Expires

Por defeito, a cookie é uma cookie de sessão, significando que só está presente enquanto o browser permanecer aberto - quando o browser é fechado, a cookie é apagada pelo browser. No entanto, este comportamento pode ser alterado utilizando a propriedade Expires. Esta propriedade é uma instância DateTimeOffset (desfasamento), o que facilita configurar um tempo de expiração, assim:

cookieOptions.Expires = new DateTimeOffset(DateTime.Now.AddDays(7));

Isto faz com que a cookie expire em 7 dias. Obviamente que podemos ajustar isto utilizando métodos como AddDays(), AddHours() e por aí em diante.

CookieOptions.Domain

Por defeito, uma cookie é criada para o domínio onde o pedido foi feito. Assim, se uma página é acedida através do domínio mywebsite.com, a cookie é criada para mywebsite.com. Se a página for acedida utilizando um subdomínio, este subdomínio vai ser utilizado, e isto é importante, porque "www" pode ser um subdomínio. Ou seja, se a página é acedida através do link www.mywebsite.com, a cookie vai, por defeito, ser apenas acessível através de www.mywebsite.com e NÃO de mywebsite.com. Assim sendo, pode ser boa ideia colocar a propriedade Domain como o domínio base do website, precedido com um ponto, da seguinte forma:

cookieOptions.Domain = ".mywebsite.com";

Agora a cookie vai estar acessível a partir de mywebsite.com assim como de todos os subdomínios possíveis. Por outro lado, se não tivermos controlo total do domínio, podemos querer limitar o domínio da cookie aos (sub)domínios em nosso controle.

CookieOptions.Path

Por defeito, o caminho (Path) da cookie +e colocado como "/", o que na prática significa que a cookie vai ser válida para todas as páginas do website. No entanto, nalgumas situações, podemos necessitar que a cookie seja apenas válida para uma página ou pasta específicas. Isto é facilmente cumprido com a propriedade Path:

cookieOptions.Path = "/users/";

Com esta medida, a cookie vai agora apenas ser visível e legível para páginas na pasta "users", assim como as suas sub-pastas.

Mais propriedades de CookieOptions

Existem muitas outras propriedades interessantes encontradas em CookieOptions, como IsEssential, HttpOnly e Secure. Se pretenderes saber mais acerca delas, sugiro que dèes uma vista de olhos na documentação para CookieOptions.

Sumário

Graças às cookies, podemos guardar informação acerca do visitante e obtê-la novamente em pedidos seguintes. Esta é uma técnica muito importante, utilizada num leque alargado de situações, como manter utilizadores autenticados, rastrear a sua utilização do nosso website e muito mais.

This article has been fully translated into the following languages: Is your preferred language not on the list? Click here to help us translate this article into your language!