Exercício – Criar um projeto de API Web

8 minutos

Este módulo usa o SDK do .NET 8.0. Verifique se você tem o .NET 8.0 instalado executando o seguinte comando em seu terminal de comando preferencial:

dotnet --list-sdks

Uma saída semelhante ao seguinte exemplo aparece:

6.0.317 [C:\Program Files\dotnet\sdk]
7.0.401 [C:\Program Files\dotnet\sdk]
8.0.100 [C:\Program Files\dotnet\sdk]

Verifique se uma versão que começa com 8 está listada. Se nenhum estiver listado ou o comando não for encontrado, instale o SDK do .NET 8.0 mais recente.

Criar e explorar um projeto de API Web

Para configurar o projeto do .NET a fim de trabalhar com a API Web, usaremos o Visual Studio Code. O Visual Studio Code inclui um terminal integrado, o que facilita a criação de projetos. Se você não quiser usar um editor de código, poderá executar os comandos deste módulo em um terminal.

No Visual Studio Code, escolha Arquivo>Abrir Pasta.
Crie uma pasta chamada ContosoPizza no local de sua escolha e clique em Selecionar Pasta.
No Visual Studio Code, abra o terminal integrado selecionando Exibir>Terminal no menu principal.
Na janela do terminal, copie e cole o seguinte comando:
```
dotnet new webapi -controllers -f net8.0
```
Esse comando cria os arquivos de um projeto básico de API Web que usa controladores, juntamente com um arquivo de projeto em C# chamado ContosoPizza.csproj que retornará uma lista de previsões meteorológicas. Caso obtenha um erro, verifique se o SDK do .NET 8 está instalado.

Importante

Os projetos de API Web são protegidos com https por padrão. Se você tiver problemas, configure o certificado de desenvolvimento HTTPS do ASP.NET Core.

Você poderá receber um prompt do Visual Studio Code para adicionar ativos para depurar o projeto. Selecione Sim na caixa de diálogo.

O comando usa um modelo de projeto ASP.NET Core, com o alias webapi, para gerar o scaffolding de um projeto de API Web baseado em C#. Um diretório ContosoPizza é criado. Esse diretório contém um projeto ASP.NET Core em execução no .NET. O nome do projeto corresponde ao nome do diretório ContosoPizza.

Agora você deve ter acesso a esses arquivos e diretórios:
```
-| Controllers
-| obj
-| Properties
-| appsettings.Development.json
-| appsettings.json
-| ContosoPizza.csproj
-| ContosoPizza.http
-| Program.cs
-| WeatherForecast.cs
```

Examine os seguintes arquivos e diretórios:

Nome	Descrição
Controllers/	Contém classes com métodos públicos expostos como pontos de extremidade HTTP.
Program.cs	Configura serviços e o pipeline de solicitação HTTP do aplicativo e contém o ponto de entrada gerenciado do aplicativo.
ContosoPizza.csproj	Contém metadados de configuração para o projeto.
ContosoPizza.http	Isso contém a configuração para testar as APIs REST diretamente do Visual Studio Code.

Compilar e testar a API Web

Execute o seguinte comando da CLI do .NET Core no shell de comando:
```
dotnet run
```
O comando anterior:
- Localiza o arquivo de projeto no diretório atual.
- Recupera e instala as dependências de projeto necessárias para este projeto.
- Compila o código do projeto.
- Hospeda a API Web com o servidor Web Kestrel do ASP.NET Core em um ponto de extremidade HTTP e HTTPS.
Quando o projeto for criado, uma porta de 5000 a 5300 será selecionada para HTTP e de 7000 a 7300 para HTTPS. Você pode facilmente alterar as portas que você usou durante o desenvolvimento com a edição do arquivo launchSettings.json do projeto. Esse módulo usa a URL segura localhost que começa com https .

Você deve obter uma saída semelhante à seguinte, indicando que seu aplicativo está em execução:
```
Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7294
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5118 
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development        
```
Se você estiver executando esse aplicativo no computador, será possível direcionar um navegador para o link HTTPS exibido na saída (no caso anterior, https://localhost:7294) para exibir a página resultante. Lembre-se dessa porta, pois você a usará em todo o módulo em que {PORT} for usado.

Importante

Verifique a saída do terminal se você encontrar algum comportamento inesperado. Se o build falhar ou se ocorrerem outros erros, as informações do arquivo de log ajudarão a solucionar os problemas. Ao fazer alterações no código, você precisará interromper a API Web selecionando Ctrl+C no teclado e executando o comando dotnet run novamente.

Abra um navegador da Web e acesse:

https://localhost:{PORT}/weatherforecast

Você deverá ver uma saída semelhante a esse exemplo:

[
    {
    "date": "2021-11-09T20:36:01.4678814+00:00",
    "temperatureC": 33,
    "temperatureF": 91,
    "summary": "Scorching"
    },
    {
    "date": "2021-11-09T20:36:01.4682337+00:00",
    "temperatureC": -8,
    "temperatureF": 18,
    "summary": "Cool"
    },
    // ...
]

Opcional: Explorar com arquivos `.http`

O ContosoPizza.http está incluído no projeto e esse arquivo é usado para testar pontos de extremidade de API por meio de um formato padrão. Há suporte para arquivos .http em vários IDEs (ambientes de desenvolvimento integrado), incluindo o Visual Studio e dentro do Visual Studio Code com a extensão REST de cliente instalada.

Abra o arquivo ContosoPizza.http.

Em alguns IDEs esse arquivo é pré-configurado com as variáveis de @ContosoPizza_HostAddress e um comando GET chamando /weatherforecast/ que aceita application/json.

Se ele estiver presente em seu arquivo, selecione o comando Sent Request acima de GET, que envia uma solicitação para o serviço em execução.

Chamar esse comando exibe uma janela de resposta com saída semelhante à vista no navegador:

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json; charset=utf-8
Date: Wed, 17 Jan 2024 16:46:40 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
    {
        "date": "2024-01-18",
        "temperatureC": -2,
        "temperatureF": 29,
        "summary": "Warm"
    },
    {
        "date": "2024-01-19",
        "temperatureC": 24,
        "temperatureF": 75,
        "summary": "Chilly"
    },
    // ..
]

Opcional: Explorar APIs com o REPL HTTP da linha de comando

Abra um novo terminal integrado do Visual Studio Code selecionando Terminal>Novo Terminal no menu principal e execute o seguinte comando:
```
dotnet tool install -g Microsoft.dotnet-httprepl
```
O comando anterior instala a ferramenta de linha de comando .NET HTTP Read-Eval-Print Loop (REPL) que você usa para fazer solicitações HTTP para a API da Web.
Conecte-se à API Web executando o seguinte comando:
```
httprepl https://localhost:{PORT}
```
Outra opção é executar o seguinte comando a qualquer momento enquanto HttpRepl estiver em execução:
```
connect https://localhost:{PORT}
```
Dica

Se a HttpRepl ferramenta avisar Não é possível encontrar uma descrição OpenAPI, a causa mais provável é um certificado de desenvolvimento não confiável. HttpRepl requer uma conexão confiável. Antes de continuar, você precisa configurar seu sistema para confiar no certificado de desenvolvimento com dotnet dev-certs https --trust
Explore os pontos de extremidade disponíveis executando o seguinte comando:
```
ls
```
O comando anterior detecta todas as APIs disponíveis no ponto de extremidade conectado e as lista, como na seguinte saída:
```
https://localhost:{PORT}/> ls
.                 []
WeatherForecast   [GET] 
```
Vá até o ponto de extremidade WeatherForecast executando o seguinte comando:
```
cd WeatherForecast
```
O comando anterior mostra uma saída das APIs disponíveis para o ponto de extremidade WeatherForecast:
```
https://localhost:{PORT}/> cd WeatherForecast
/WeatherForecast    [GET]
```

Faça uma solicitação GET no HttpRepl usando o seguinte comando:

get

O comando anterior faz uma solicitação GET semelhante a ir para o ponto de extremidade no navegador:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 02 Apr 2021 17:31:43 GMT
Server: Kestrel
Transfer-Encoding: chunked
[
    {
    "date": 4/3/2021 10:31:44 AM,
    "temperatureC": 13,
    "temperatureF": 55,
    "summary": "Sweltering"
    },
    {
    "date": 4/4/2021 10:31:44 AM,
    "temperatureC": -13,
    "temperatureF": 9,
    "summary": "Warm"
    },
    // ..
]

Saia da sessão HttpRepl atual usando o seguinte comando:
```
exit
```
Retorne ao terminal dotnet na lista suspensa no Visual Studio Code. Desligue a API Web selecionando Ctrl+C no teclado.

Agora que você criou a API Web, é possível modifica-la para atender às necessidades da API Web de pizza.

Continuar

Exercício – Criar um projeto de API Web

Criar e explorar um projeto de API Web

Compilar e testar a API Web

Opcional: Explorar com arquivos .http

Opcional: Explorar APIs com o REPL HTTP da linha de comando

Comentários

Opcional: Explorar com arquivos `.http`