Criando projetos .NET via console
O comando dotnet new cria projetos .NET a partir de templates, direto do terminal, e se torna indispensável para quem não desenvolve no Windows ou prefere fugir das telas do Visual Studio. Neste artigo, você vai entender os principais usos desse comando para facilitar o dia a dia no desenvolvimento.
As possibilidades de configuração na criação de um projeto são enormes. Por isso, o foco aqui fica na estrutura base e nos usos mais comuns, enquanto as configurações avançadas merecem um estudo à parte.
O que é o dotnet new
O dotnet new é o comando da CLI do .NET que gera projetos, arquivos de configuração e soluções com base em um template. Em vez de criar pastas e arquivos à mão, você escolhe um modelo e deixa o SDK montar a estrutura inicial.
Por trás dos panos, o comando chama o template engine do .NET, que escreve os artefatos em disco conforme o modelo e as opções informadas. Além disso, ele executa o restore dos pacotes de forma implícita, então o projeto já nasce pronto para compilar.
Segundo a documentação oficial do dotnet new, o mesmo comando atende desde um simples console até aplicações web completas. Na prática, isso garante o mesmo fluxo de trabalho no Windows, no Linux e no macOS.
Verificando a instalação do .NET
Antes de começar, você precisa saber quais versões do .NET estão disponíveis na máquina. Vale lembrar que várias versões convivem lado a lado sem nenhum problema.
Como este artigo usa um projeto do tipo Blazor Server App, o .NET 6 precisa estar instalado. Afinal, os templates disponíveis dependem da versão do SDK que o terminal vai usar.
Listando os SDKs instalados
Para verificar todas as versões do SDK instaladas, use o comando abaixo.
dotnet --list-sdks
Se quiser saber apenas qual versão o terminal vai usar por padrão, rode este outro comando.
dotnet --version
As saídas devem ficar parecidas com a imagem a seguir.
Além desses dois comandos, o dotnet --info mostra um resumo completo do ambiente. Ele inclui o sistema operacional, os SDKs, os runtimes e o caminho de instalação.
Quando a versão necessária não aparece
Caso a versão necessária não esteja na lista, instale o SDK antes de seguir. O artigo .NET: instalação, configuração e primeiros passos mostra esse processo em detalhes.
Com a versão correta confirmada, você já pode explorar os templates disponíveis. Então, vamos ao próximo passo.
Templates do dotnet new
Os templates são modelos pré-configurados que acompanham o próprio .NET. Além deles, você também pode instalar modelos personalizados criados pela comunidade ou pela sua equipe.
Listando os templates disponíveis
Para ver quais modelos estão disponíveis, execute dotnet new no terminal sem nenhum outro parâmetro. A saída fica parecida com esta.
The 'dotnet new' command creates a .NET project based on a template.
Common templates are:
Template Name Short Name Language Tags
-------------------- ------------ ---------- -------------------
ASP.NET Core Web App razor,webapp [C#] Web/MVC/Razor Pages
Blazor Server App blazorserver [C#] Web/Blazor
Class Library classlib [C#],F#,VB Common/Library
Console App console [C#],F#,VB Common/Console
Windows Forms App winforms [C#],VB Common/WinForms
WPF Application wpf [C#],VB Common/WPF
An example would be:
dotnet new console
Display template options with:
dotnet new console -h
Display all installed templates with:
dotnet new --list
Display templates available on NuGet.org with:
dotnet new web --search
Essa saída já dá uma visão rápida de como criar projetos. Basta usar o dotnet new seguido do Short Name do modelo desejado.
dotnet new <TEMPLATE>
A própria mensagem também indica o próximo passo. Por exemplo, dotnet new --list mostra todos os templates instalados, e não apenas os mais comuns.
A versão do SDK define os templates
Ao usar o comando dessa forma, o terminal adota a versão mais recente do .NET instalada. Por isso, os modelos só aparecem se estiverem disponíveis nessa versão.
Por exemplo, quem tem apenas o .NET Core 3.1 instalado não vê o template de Blazor Server do .NET 6. Nesse caso, a solução é instalar o SDK mais novo ou fixar uma versão com um arquivo global.json.
O próprio dotnet new gera esse arquivo. O comando abaixo fixa o SDK em uma versão específica para a pasta atual e suas subpastas.
dotnet new globaljson --sdk-version 6.0.100
Consultando as opções de um template
Cada template tem opções próprias, além das opções gerais do comando. Para descobrir quais são, adicione -h depois do nome curto do modelo.
dotnet new blazorserver -h
No caso do Blazor Server, por exemplo, a opção --auth define o tipo de autenticação, e --no-https desliga o HTTPS. Assim, você ajusta o projeto já na criação, sem editar arquivos depois.
Principais opções do dotnet new
Algumas opções aparecem com frequência no uso diário do dotnet new. Vale conhecer cada uma antes de criar o primeiro projeto.
| Opção | O que faz |
|---|---|
-o ou --output |
Define a pasta onde o projeto será criado |
-n ou --name |
Define o nome do projeto gerado |
-f ou --framework |
Escolhe o framework de destino, como net6.0 |
-lang ou --language |
Escolhe a linguagem, como C#, F# ou VB |
--dry-run |
Mostra o que seria criado, sem gravar nada |
--force |
Gera o conteúdo mesmo que altere arquivos existentes |
A opção --dry-run ajuda bastante quando você ainda não conhece um template. Com ela, o dotnet new exibe um resumo dos arquivos que criaria, sem tocar no disco.
Já a opção -lang exige atenção em alguns shells, porque eles tratam o caractere # de forma especial. Nesse caso, coloque o valor entre aspas, como em dotnet new console -lang "F#".
Instalando um template personalizado
Os templates personalizados ampliam o que você consegue gerar pelo terminal. Neste exemplo, o modelo vem do MudBlazor, uma biblioteca de componentes para Blazor relativamente recente na época.
Para instalar o pacote de templates do NuGet, use o comando abaixo.
dotnet new --install MudBlazor.Templates
A saída correta deve ficar parecida com esta.
The following template packages will be installed:
MudBlazor.Templates
MudBlazor.Templates is already installed, version: 0.6.1, it will be replaced with version .
MudBlazor.Templates::0.6.1 was successfully uninstalled.
Success: MudBlazor.Templates::0.6.1 installed the following templates:
Template Name Short Name Language Tags
------------------- ---------- -------- --------------------------------------
MudBlazor Templates mudblazor [C#] Blazor/Desktop/macOS/Windows/Cloud/Web
Repare que a última linha informa o Short Name que você vai usar para criar o projeto. Nesse caso, o nome curto é mudblazor.
Buscando e removendo templates
Antes de instalar, você pode procurar pacotes de templates no NuGet.org direto pelo terminal. Para isso, use a opção --search com parte do nome desejado.
dotnet new mudblazor --search
Da mesma forma, a opção --uninstall remove um pacote instalado. Sem argumentos, ela lista os pacotes atuais e o comando exato para remover cada um.
dotnet new --uninstall MudBlazor.Templates
Vale um cuidado importante aqui. Templates podem executar tarefas do MSBuild e código arbitrário durante a criação do projeto, então instale apenas pacotes de fontes confiáveis.
Criando o projeto com dotnet new
Para criar o projeto, use o dotnet new apresentado no início, seguido do Short Name do template. O comando fica assim.
dotnet new mudblazor -o MyProject
Opa, acabamos de usar algo diferente! O parâmetro -o seguido de um texto define a pasta de saída e, consequentemente, o nome do projeto criado.
Como o parâmetro -o funciona
O parâmetro -o cria um diretório com o nome informado e coloca os arquivos do projeto dentro dele. Como você não passou -n, o dotnet new usa o nome dessa pasta como nome do projeto.
Sem o -o, o comando grava os arquivos diretamente no diretório em que o terminal está no momento. Nesse caso, o projeto recebe o nome da pasta atual.
Se quiser separar as duas coisas, combine as opções. Por exemplo, o comando abaixo cria a pasta src com um projeto chamado MyProject.
dotnet new mudblazor -n MyProject -o src
Executando o projeto criado
Depois da criação, entre na pasta do projeto e execute a aplicação. O comando dotnet run compila e inicia o projeto em seguida.
cd MyProject
dotnet run
Durante o desenvolvimento, o dotnet watch também ajuda bastante. Ele observa os arquivos e recompila a aplicação sempre que você salva uma alteração.
Escolhendo o framework de destino no dotnet new
Quando a máquina tem mais de um SDK, o framework de destino merece atenção. Por padrão, o dotnet new usa o framework correspondente ao SDK em execução.
Para mudar esse comportamento, use a opção -f com o identificador do framework, chamado de TFM. O valor escolhido vai direto para o arquivo .csproj do projeto.
# Cria um console com destino explícito ao .NET 6
dotnet new console -f net6.0 -o MyConsole
# Cria uma biblioteca compatível com .NET Standard 2.0
dotnet new classlib -f netstandard2.0 -o MyLibrary
O segundo exemplo mostra um caso comum. Uma biblioteca voltada ao .NET Standard 2.0 pode ser consumida por projetos de várias versões do .NET.
Outra opção útil chegou no SDK 6.0.300. Com --use-program-main, os templates geram uma classe Program com o método Main explícito, em vez das top-level statements.
dotnet new console --use-program-main -o MyClassicConsole
Essa escolha é apenas de estilo, porque as duas formas compilam para o mesmo resultado. Ainda assim, ela ajuda quem está acostumado com o formato tradicional do C#.
Entendendo a estrutura gerada
Depois da criação, vale abrir a pasta e entender o que o template gerou. No caso do blazorserver do .NET 6, a estrutura inclui alguns arquivos e pastas principais.
| Arquivo ou pasta | Função |
|---|---|
Program.cs |
Configura os serviços e o pipeline da aplicação |
Pages |
Contém as páginas, como Index.razor e Counter.razor |
Shared |
Guarda componentes compartilhados, como MainLayout.razor e NavMenu.razor |
Data |
Traz o serviço de exemplo WeatherForecastService |
wwwroot |
Armazena arquivos estáticos, como CSS e imagens |
appsettings.json |
Reúne as configurações da aplicação |
Properties/launchSettings.json |
Define portas e perfis de execução local |
No .NET 6, o template de Blazor Server também passou a usar o arquivo Pages/_Layout.cshtml. Ele recebeu o conteúdo de layout que antes ficava em _Host.cshtml.
Templates de terceiros, como o do MudBlazor, seguem uma lógica parecida. No entanto, eles costumam acrescentar referências e componentes próprios, então vale explorar os arquivos antes de começar a codificar.
Organizando soluções com dotnet new
Projetos reais quase sempre têm mais de um projeto, como a aplicação, uma biblioteca e os testes. Para agrupar tudo, o dotnet new também cria arquivos de solução.
# Cria a solução e os projetos
dotnet new sln -n MyApp
dotnet new classlib -o MyApp.Core
dotnet new xunit -o MyApp.Tests
# Adiciona os projetos à solução
dotnet sln add MyApp.Core
dotnet sln add MyApp.Tests
Com a solução montada, um único dotnet build na raiz compila todos os projetos. Além disso, editores como o Visual Studio e o Rider abrem a solução inteira de uma vez.
Essa organização pelo terminal também facilita a automação. Um script com esses comandos recria a mesma estrutura em qualquer máquina, o que ajuda novos membros da equipe e pipelines de CI.
Problemas comuns ao usar o dotnet new
Alguns erros aparecem com frequência para quem está começando. A boa notícia é que quase todos têm uma causa simples.
O primeiro é o template não encontrado. Em geral, isso acontece porque o nome curto está errado, o pacote não foi instalado ou o SDK em uso não traz aquele modelo.
Nesse caso, confira a lista com dotnet new --list e a versão com dotnet --version. Depois, instale o pacote ou o SDK que estiver faltando.
O segundo é a tentativa de criar um projeto sobre arquivos existentes. Quando o template sobrescreveria algum arquivo, o dotnet new interrompe a operação para proteger o seu trabalho.
Se a substituição for mesmo intencional, repita o comando com --force. Caso contrário, escolha outra pasta com -o e mantenha os arquivos originais intactos.
O terceiro envolve o caractere # na opção de linguagem. Como alguns shells interpretam esse símbolo, o valor F# sem aspas pode quebrar o comando, então use sempre "F#".
Mudanças no dotnet new a partir do .NET 7
Este artigo usa a sintaxe do SDK do .NET 6. No entanto, vale saber que o SDK do .NET 7 transformou algumas opções do dotnet new em subcomandos.
Assim, --list, --search, --install e --uninstall passaram a ser list, search, install e uninstall. Por exemplo, a instalação do MudBlazor ficaria dotnet new install MudBlazor.Templates.
As demais opções continuam funcionando com seus respectivos subcomandos. Além disso, o SDK 7.0.100 trouxe o autocompletar com Tab para nomes de templates e suas opções.
Boas práticas no uso do dotnet new
Alguns hábitos simples deixam o uso do comando mais previsível. Primeiro, confira a versão do SDK antes de criar qualquer projeto, principalmente em máquinas com várias versões.
Em seguida, prefira sempre passar -o ou -n. Dessa forma, você evita espalhar arquivos na pasta errada e controla o nome do projeto.
Também vale testar templates novos com --dry-run antes da criação real. Assim, você entende a estrutura gerada sem precisar apagar nada depois.
Por fim, use o -h sempre que tiver dúvida sobre as opções de um modelo. A ajuda do próprio dotnet new costuma ser mais atualizada do que qualquer tutorial.
Conclusão
O dotnet new simplifica a criação de projetos .NET em qualquer sistema operacional. Com poucos comandos, você lista templates, instala modelos personalizados e gera aplicações completas sem sair do terminal.
Neste artigo, você viu como verificar os SDKs instalados, consultar templates, usar opções como -o e -n e instalar o template do MudBlazor. Além disso, conheceu as mudanças de sintaxe que chegaram com o .NET 7.
Para continuar estudando, leia sobre números no C# e .NET e sobre DateTime no C# e .NET. Se preferir um caminho guiado, confira os cursos Gratuito Fundamentos do C# e Fundamentos do ASP.NET 6.
FAQ
Como vejo todos os templates instalados?
No SDK do .NET 6, use dotnet new --list. A partir do .NET 7, o comando equivalente é dotnet new list.
Qual a diferença entre -o e -n?
O -o define a pasta de saída, enquanto o -n define o nome do projeto. Sem -n, o nome vem da pasta de saída ou da pasta atual.
Por que um template não aparece na lista?
Os templates dependem da versão do SDK em uso. Confira a versão com dotnet --version e instale o SDK necessário ou fixe a versão com global.json.
Como removo um template personalizado?
Use dotnet new --uninstall seguido do identificador do pacote. Sem argumentos, o comando lista os pacotes instalados e como remover cada um.
Preciso rodar dotnet restore depois de criar o projeto?
Não, porque o dotnet new executa o restore de forma implícita. Se quiser evitar esse passo, use a opção --no-restore.