C# Projetos (dotnet new console)

Até aqui, a Ana escreveu um arquivo ola.cs e rodou com dotnet run ola.cs. Para programas pequenos, isso basta. Mas quase todo programa de verdade em C# é um projeto: uma pasta com um arquivo de configuração (o .csproj) e um ou mais arquivos de código. É assim que funcionam os tutoriais, os livros, o Visual Studio e o trabalho em equipe. Nesta aula você cria o seu primeiro projeto com dotnet new console, conhece cada arquivo que ele gera, roda com dotnet run, compila com dotnet build e descobre o que fica guardado nas pastas bin e obj.

Todos os comandos desta aula foram executados na máquina fictícia da Ana (usuária ana, computador notebook), com o .NET 10 SDK do Ubuntu 26.04 (dotnet --version = 10.0.112). Os projetos ficam em ~/projetos. As saídas foram copiadas da tela, em português, como aparecem num Ubuntu em pt-BR.

A ideia: o bilhete e o fichário

Um arquivo ola.cs solto é como um bilhete: uma folha só, que você escreve e entrega. Rápido e prático.

Um projeto é como um fichário de escola. Ele tem uma capa com as informações do dono (o nome, a turma, as regras da matéria) e, dentro, quantas folhas você quiser. No C#:

O .csproj diz ao dotnet que tipo de programa é aquele, qual versão do .NET usar e quais recursos ligar. Os arquivos de código são todos os .cs da pasta: o dotnet pega todos sozinho, sem você precisar listá-los.

1. Criar o projeto: dotnet new console

A Ana entra na pasta ~/projetos (criando-a, se ainda não existe) e pede um projeto novo:

$ mkdir -p projetos && cd projetos
$ dotnet new console -o Ola
O modelo "Aplicativo do Console" foi criado com êxito.

Processando ações pós-criação...
Restaurando /home/ana/projetos/Ola/Ola.csproj:
  Determinando os projetos a serem restaurados...
  /home/ana/projetos/Ola/Ola.csproj restaurado (em 106 ms).
A restauração foi bem-sucedida.

dotnet

A ferramenta do .NET, a mesma que você já usou com dotnet run ola.cs (aula Rodar com dotnet run).

new

"Novo": crie algo novo a partir de um modelo (em inglês, template), uma espécie de forma de bolo com os arquivos já prontos.

console

O nome do modelo: um aplicativo de console, ou seja, um programa que roda no terminal, escrevendo e lendo texto. É o tipo de programa de todo o Nível 1.

-o Ola

output = "saída": crie tudo numa pasta nova chamada Ola. Sem o -o, os arquivos cairiam na pasta atual (seção 6).

E a saída, linha por linha:

2. O que foi criado

Dentro da pasta nova:

$ cd Ola
$ ls -la
total 20
drwxrwxr-x 3 ana ana 4096 out 17 12:37 .
drwxrwxr-x 3 ana ana 4096 out 17 12:37 ..
drwxrwxr-x 2 ana ana 4096 out 17 12:37 obj
-rw-rw-r-- 1 ana ana  243 out 17 12:37 Ola.csproj
-rw-rw-r-- 1 ana ana  103 out 17 12:37 Program.cs

São só três coisas: o arquivo de projeto Ola.csproj (243 bytes), o código Program.cs (103 bytes) e uma pasta obj, criada pela restauração. Repare que o .csproj ganhou o nome da pasta: Ola.

O arquivo de projeto: Ola.csproj

$ cat Ola.csproj
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

</Project>

Ele é escrito em XML, um formato de texto com etiquetas entre < >. Cada informação fica entre uma etiqueta que abre (<OutputType>) e uma que fecha, com barra (</OutputType>). Você não precisa saber XML: basta ler.

<Project Sdk="Microsoft.NET.Sdk">

"Projeto que usa o SDK do .NET". O SDK (aula .NET: SDK, Runtime e CLR) traz as regras de como compilar um projeto C#. Por isso o arquivo é tão curto: o resto vem pronto do SDK.

<PropertyGroup>

"Grupo de propriedades": as configurações do projeto ficam aqui dentro.

<OutputType>Exe</OutputType>

"Tipo de saída: executável". O resultado é um programa que se pode rodar. (Uma biblioteca, que só serve para outros programas usarem, não teria essa linha. Aula Bibliotecas de Classes.)

<TargetFramework>net10.0</TargetFramework>

"Plataforma de destino: .NET 10". O programa vai rodar no .NET 10, e a versão da linguagem é a que vem com ele: C# 14 (aula Versões do C# e do .NET).

<ImplicitUsings>enable</ImplicitUsings>

"using implícitos: ligado". É por causa dessa linha que você escreve Console.WriteLine sem pôr using System; no topo do arquivo. O using tem aula própria: Namespaces e using.

<Nullable>enable</Nullable>

"Anuláveis: ligado". Liga os avisos que protegem você de um dos erros mais comuns da programação, o valor null onde não devia (aula Referências Anuláveis). Deixe sempre ligado.

O código: Program.cs

$ cat Program.cs
// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

// See https://aka.ms/…

Um comentário: tudo depois de // é ignorado pelo compilador. Diz "veja este endereço para mais informações" (sobre o modelo). Pode apagar. Aula Comentários.

Console.WriteLine("Hello, World!");

A única instrução do programa: escreve Hello, World! ("Olá, mundo!") no terminal. É o mesmo programa da aula Olá, Mundo, em inglês.

O nome Program.cs é só um costume: o dotnet não exige esse nome. Repare também que não há class Program nem static void Main, que você vai ver em muitos livros e tutoriais. Esse jeito curto se chama instruções de nível superior, e a próxima aula, Program.cs e o Main, mostra as duas formas lado a lado.

3. Rodar: dotnet run

Dentro da pasta do projeto, basta dotnet run, sem nome de arquivo:

$ dotnet run
Hello, World!

O dotnet run procura um .csproj na pasta atual, compila todos os .cs do projeto e, se não houver erro, roda o programa. Agora a Ana troca o conteúdo do Program.cs pela lista de compras dela. (Aqui ela usa o cat > do terminal, que grava tudo o que vem até a linha FIM; você pode usar qualquer editor de texto, como mostra a aula Editores e IDEs.)

$ cat > Program.cs <<'FIM'
> Console.WriteLine("Lista de compras da Ana");
> Console.WriteLine("- arroz");
> Console.WriteLine("- café");
> FIM
$ dotnet run
Lista de compras da Ana
- arroz
- café
$ ls
bin                      « pasta nova, criada pelo dotnet run
obj
Ola.csproj
Program.cs

Duas coisas para reparar:

• O dotnet run percebeu que o código mudou e compilou de novo antes de rodar. Você nunca precisa compilar "na mão" antes do dotnet run.
• Apareceu uma pasta bin. É lá que fica o programa compilado (seção 4).

No editor do guia, o botão Rodar faz o papel do dotnet run. Numa caixa com um arquivo só, como a de baixo, ele roda como o dotnet run Program.cs de um arquivo solto; com duas ou mais abas .cs, a caixa vira um projeto, e o terminal dela mostra dotnet run numa pasta de projeto (aula O Editor do Guia).

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Console.WriteLine("Lista de compras da Ana");
Console.WriteLine("- feijão");

4. Compilar sem rodar: dotnet build e a pasta bin

Compilar é traduzir o seu código C# para uma forma que o .NET sabe executar. O dotnet run compila e roda; o dotnet build ("construir") só compila, e mostra um relatório:

$ dotnet build
  Determinando os projetos a serem restaurados...
  Todos os projetos estão atualizados para restauração.
  Ola -> /home/ana/projetos/Ola/bin/Debug/net10.0/Ola.dll

Compilação com êxito.
    0 Aviso(s)
    0 Erro(s)

Tempo Decorrido 00:00:01.26

O que tem em bin/Debug/net10.0

O caminho conta uma história: bin (de binary, "binário", o programa já traduzido), Debug (a configuração usada, explicada logo abaixo) e net10.0 (a plataforma do .csproj).

$ ls bin/Debug/net10.0
Ola
Ola.deps.json
Ola.dll
Ola.pdb
Ola.runtimeconfig.json

Dá para rodar o programa compilado de dois jeitos, sem compilar de novo:

$ ./bin/Debug/net10.0/Ola
Lista de compras da Ana
- arroz
- café
$ dotnet bin/Debug/net10.0/Ola.dll
Lista de compras da Ana
- arroz
- café
$ echo $?
0                        « código de saída 0: deu tudo certo

O primeiro usa o executável; o segundo entrega o .dll direto para o dotnet. No dia a dia, porém, use dotnet run: ele confere se o código mudou e recompila quando precisa. Rodar o arquivo da pasta bin depois de mudar o código mostra a versão antiga, até você rodar dotnet build de novo.

A pasta obj

obj (de object, "objeto") guarda os arquivos intermediários: o resultado da restauração e as peças que o compilador usa para não recompilar tudo do zero a cada vez.

$ ls obj
Debug
Ola.csproj.nuget.dgspec.json
Ola.csproj.nuget.g.props
Ola.csproj.nuget.g.targets
project.assets.json
project.nuget.cache

Você nunca precisa abrir nem editar nada em bin e obj. As duas pastas podem ser apagadas a qualquer momento: o próximo dotnet build cria tudo de novo. Por isso elas também não vão para o controle de versão (o Git), nem para o pendrive quando você leva o projeto para outro computador: leve só o .csproj e os .cs.

Debug e Release, e o dotnet clean

Debug ("depuração") é a configuração padrão, feita para quem está programando: compila rápido e guarda tudo o que ajuda a achar erros. Release ("lançamento") é a versão otimizada, para entregar aos usuários. Para escolher, use -c (configuration):

$ dotnet build -c Release
  Determinando os projetos a serem restaurados...
  Todos os projetos estão atualizados para restauração.
  Ola -> /home/ana/projetos/Ola/bin/Release/net10.0/Ola.dll

Compilação com êxito.
    0 Aviso(s)
    0 Erro(s)

Tempo Decorrido 00:00:01.22
$ ls bin
Debug
Release                  « uma pasta para cada configuração

E o dotnet clean ("limpar") apaga o que o build gerou na configuração Debug (a pasta bin/Debug/net10.0 fica vazia; a Release continua lá). A saída dele é mais falante, no estilo do MSBuild, a ferramenta que o dotnet usa por baixo para compilar, mas termina do mesmo jeito: Compilação com êxito.. Durante o Nível 1, você vai usar sempre o Debug, sem precisar pensar nisso. Publicar um programa para outras pessoas é assunto da aula Publicar.

5. Rodar de fora da pasta: --project

O dotnet run procura o projeto na pasta atual. Para rodar um projeto que está em outra pasta, diga onde ele está com --project:

$ dotnet run --project Ola
Lista de compras da Ana
- arroz
- café

Esquecer de entrar na pasta é o erro número 1 com projetos (veja em Quando dá errado).

6. Escolher o nome: -o, -n e a pasta atual

O -o escolhe a pasta. O -n (name) escolhe o nome do projeto, que vira o nome do .csproj e do programa. Sem o -n, o nome é o da pasta. A Ana quer uma pasta Lojinha com um programa chamado Caixa:

$ dotnet new console -o Lojinha -n Caixa
O modelo "Aplicativo do Console" foi criado com êxito.

Processando ações pós-criação...
Restaurando /home/ana/projetos/Lojinha/Caixa.csproj:
  Determinando os projetos a serem restaurados...
  /home/ana/projetos/Lojinha/Caixa.csproj restaurado (em 107 ms).
A restauração foi bem-sucedida.
$ ls Lojinha
Caixa.csproj
obj
Program.cs

Sem -o, o projeto é criado na pasta em que você está, e ganha o nome dela. Útil quando a pasta já existe:

$ mkdir Agenda && cd Agenda
$ dotnet new console
O modelo "Aplicativo do Console" foi criado com êxito.

Processando ações pós-criação...
Restaurando /home/ana/projetos/Agenda/Agenda.csproj:
  Determinando os projetos a serem restaurados...
  /home/ana/projetos/Agenda/Agenda.csproj restaurado (em 106 ms).
A restauração foi bem-sucedida.
$ ls
Agenda.csproj
obj
Program.cs

Todas as opções: --help

O próprio dotnet explica as opções de cada modelo. Um pedaço:

$ dotnet new console --help
Aplicativo do Console (C#)
Autor: Microsoft
Descrição: Um projeto para criar um aplicativo de linha de comando que pode ser executado no .NET no Windows, Linux e macOS

Uso:
  dotnet new console [options] [opções de modelo]

Opções:
  -n, --name <name>       O nome da saída que está sendo criada. Se nenhum nome
                          for especificado, o nome do diretório de saída será
                          usado.
  -o, --output <output>   Local para colocar a saída gerada.
  --dry-run               Exibe um resumo do que aconteceria se a linha de
                          comando especificada fosse executada se resultar em
                          uma criação de modelo. [default: False]
  --force                 Força o conteúdo a ser gerado mesmo que ele altere
                          arquivos existentes. [default: False]
…
Opções do modelo:
…
  --use-program-main           Se deve gerar uma classe de Programa explícita e
                               um método principal em vez de instruções de
                               nível superior.

A última opção, --use-program-main, gera o Program.cs no estilo antigo, com class Program e static void Main. Ela aparece na próxima aula.

Arquivo solto ou projeto: qual usar

No guia, as aulas dos Níveis 1 e 2 usam o arquivo solto, que é mais rápido. Quando um programa precisar de vários arquivos ou de pacotes, a aula cria um projeto. E um arquivo solto que cresceu pode virar projeto: o comando dotnet project convert ola.cs cria uma pasta ola com o .cs e um ola.csproj (com algumas configurações a mais, que você pode apagar).

Quando dá errado

$ dotnet run
Não foi possível localizar um projeto para executar. Verifique se existe um projeto em /home/ana ou passe o caminho para o projeto usando --project.

$ dotnet new console -o Ola
A criação deste modelo fará alterações nos arquivos existentes:
  Sobrescrever   Ola/Ola.csproj
  Sobrescrever   Ola/Program.cs

Para criar o modelo mesmo assim, execute o comando com a opção “--force”:
   dotnet new console -o Ola --force


Para obter detalhes sobre o código de saída, consulte https://aka.ms/templating-exit-codes#73
$ echo $?
73

$ dotnet run; echo "código de saída: $?"
/home/ana/projetos/Ola/Program.cs(1,45): error CS1002: ; esperado [/home/ana/projetos/Ola/Ola.csproj]

Ocorreu uma falha no build. Corrija os erros de build e execute novamente.
código de saída: 1

Lista de compras da Ana
- arroz
- café

Console.WriteLine("Lista de compras da Ana")
Console.WriteLine("- arroz");
Console.WriteLine("- café");

Console.WriteLine("Lista de compras da Ana");
Console.WriteLine("- arroz");
Console.WriteLine("- café");

Referência rápida

Exercícios

Missão final: o projeto da agenda

Agenda da Ana
Segunda: dentista
Quarta: feira

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Console.WriteLine("Agenda da Ana");
Console.WriteLine("Segunda: dentista");
Console.WriteLine("Quarta: feira");

No computador, depois de escrever esse código no Program.cs, a Ana rodaria dotnet run dentro de ~/projetos/Agenda e veria as mesmas três linhas.

Resumo

• Um projeto é uma pasta com um arquivo .csproj (a configuração) e arquivos .cs (o código). Crie com dotnet new console -o Nome.
• O .csproj do modelo diz: programa executável (Exe), .NET 10 (net10.0), using implícitos e anuláveis ligados.
• O Program.cs do modelo é um Console.WriteLine("Hello, World!"); com instruções de nível superior, sem Main.
• dotnet run, dentro da pasta, compila quando precisa e roda. Fora dela, use --project.
• dotnet build só compila. O programa vai para bin/Debug/net10.0 (Nome.dll, o executável Nome, o .pdb e dois .json); obj guarda os intermediários. As duas pastas podem ser apagadas.
• -o escolhe a pasta, -n escolhe o nome. O dotnet new não sobrescreve um projeto existente sem --force.
• Num projeto, as mensagens de erro terminam com [caminho/Nome.csproj], e só um arquivo pode ter instruções de nível superior.
• Próximo passo: Program.cs e o Main, o mesmo programa na forma curta e na forma clássica.