execução dotnet

Esso artigo se aplica a: ✔️ .NET 6 SDK e versões posteriores

Nome

dotnet run – Executa o código-fonte sem qualquer comando de compilação ou inicialização explícito.

Sinopse

dotnet run [<applicationArguments>]
  [-a|--arch <ARCHITECTURE>] [--artifacts-path <ARTIFACTS_DIR>]
  [-c|--configuration <CONFIGURATION>] [--disable-build-servers]
  [-e|--environment <KEY=VALUE>] [--file <FILE_PATH>]
  [-f|--framework <FRAMEWORK>] [--force] [--interactive]
  [-lp|--launch-profile <NAME>] [--no-build] [--no-cache]
  [--no-dependencies] [--no-launch-profile] [--no-restore] [--os <OS>]
  [-p|--property:<PROPERTYNAME>=<VALUE>]
  [--project <PATH>] [-r|--runtime <RUNTIME_IDENTIFIER>]
  [--sc|--self-contained] [--tl:[auto|on|off]] [-v|--verbosity <LEVEL>]
  [[--] [application arguments]]

dotnet run -h|--help

Descrição

O comando dotnet run fornece uma opção conveniente para executar o aplicativo do código-fonte com um comando. Ele é útil para o desenvolvimento iterativo rápido a partir da linha de comando. O comando depende do comando dotnet build para compilar o código. Quaisquer requisitos para a construção também se aplicam dotnet run .

Os arquivos de saída são gravados no local padrão, que é bin/<configuration>/<target>. Por exemplo, se você tiver um aplicativo netcoreapp2.1 e executar dotnet run, a saída será colocada em bin/Debug/netcoreapp2.1. Os arquivos são substituídos conforme necessário. Os arquivos temporários são colocados no diretório obj.

Se o projeto especificar várias estruturas, a execução de dotnet run resultará em um erro, a menos que a opção -f|--framework <FRAMEWORK> seja usada para especificar a estrutura.

O comando dotnet run é usado no contexto de projetos, não assemblies compilados. Se, em vez disso, você estiver tentando executar uma DLL de aplicativo dependente da estrutura, use dotnet sem um comando. Por exemplo, para executar myapp.dll, use:

dotnet myapp.dll

Para obter mais informações sobre o driver dotnet, consulte .NET visão geral da CLI.

Para executar o aplicativo, o comando dotnet run resolve as dependências do aplicativo que estão fora do runtime compartilhado por meio do cache NuGet. Como ele usa as dependências em cache, não recomendamos usar dotnet run para executar aplicativos em produção. Em vez disso, crie uma implantação usando o comando dotnet publish e implante a saída publicada.

Restauração implícita

Não é necessário executar dotnet restore, pois ele é executado implicitamente por todos os comandos que exigem uma restauração, como dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish e dotnet pack. Para desabilitar a restauração implícita, use a opção --no-restore.

O comando dotnet restore ainda é útil em determinados cenários em que a restauração explícita faz sentido, como compilações de integração continuosas nos Serviços Azure DevOps ou em sistemas de build que precisam controlar explicitamente quando a restauração ocorre.

Para obter informações sobre como gerenciar feeds do NuGet, consulte a documentação de dotnet restore.

Este comando é compatível com as opções dotnet restore quando passado no formato longo (por exemplo, --source). Opções de formato curto, como -s, não são compatíveis.

Downloads de manifesto de carga de trabalho

Quando você executa esse comando, ele inicia um download assíncrono em segundo plano de manifestos de publicidade para cargas de trabalho. Se o download ainda estiver em execução quando esse comando for concluído, o download será interrompido. Para saber mais, confira Manifestos de publicidade.

Perfis de inicialização

Os perfis de inicialização configuram como dotnet run inicia um aplicativo durante o desenvolvimento. Para um projeto no estilo SDK, coloque as configurações em Properties/launchSettings.json. Visual Basic projetos usam My Project/launchSettings.json em vez disso.

Aplicativos baseados em arquivo podem usar um [ApplicationName].run.json arquivo ao lado do arquivo de origem. Para obter a ordem de pesquisa de arquivo e exemplos, consulte Perfis de inicialização para aplicativos baseados em arquivo.

O arquivo de configurações de inicialização contém um objeto de nível profiles superior. Cada propriedade em profiles define um perfil nomeado:

{
  "profiles": {
    "Local": {
      "commandName": "Project",
      "commandLineArgs": "--input sample.txt",
      "dotnetRunMessages": true,
      "environmentVariables": {
        "APP_MODE": "local"
      }
    }
  }
}

O analisador de configurações de inicialização do SDK .NET aceita comentários JSON e vírgulas à direita.

Selecionar um perfil

Use --launch-profile <NAME> para selecionar um perfil nomeado. A correspondência de nome não diferencia maiúsculas de minúsculas. Os nomes de perfil que diferem apenas por caso são ambíguos e produzem um erro.

Se você não especificar um nome, dotnet run selecione o primeiro perfil na ordem de arquivo cujo commandName suporte seja. Use --no-launch-profile para ignorar o arquivo de configurações de inicialização.

Quando dotnet run aplica um perfil, ele define DOTNET_LAUNCH_PROFILE o nome do perfil selecionado no processo iniciado. Uma fonte de variável de ambiente posterior pode substituir o valor.

Tipos de perfil com suporte

O SDK do .NET dá suporte a esses commandName valores para dotnet run. Os valores diferenciam maiúsculas de minúsculas.

commandName Behavior
Project Cria o projeto e inicia o comando produzido pelo projeto.
Executable Inicia o comando especificado por executablePath. A menos que você especifique --no-build, dotnet run ainda criará o projeto primeiro.

Propriedades comuns

dotnet run reconhece essas propriedades para ambos os tipos de perfil com suporte:

dotnet run expande referências %NAME% de variável de ambiente em valores de cadeia de caracteres com suporte. No .NET 11 e versões posteriores, ele também expande as referências de propriedade do MSBuild em valores que usa para iniciar o processo, usando a mesma substituição de token que Visual Studio. Ele não expande referências no estilo $NAME shell.

Property Behavior
commandLineArgs Especifica argumentos para o processo iniciado. Argumentos de aplicativo explícitos na linha de comando têm precedência. Para um Project perfil, os argumentos fornecidos pelo project também têm precedência.
environmentVariables Especifica variáveis de ambiente para o processo iniciado. Os valores de perfil substituem variáveis de ambiente herdadas e geradas pelo SDK e -e\|--environment os valores substituem valores de perfil.
dotnetRunMessages Quando true, imprime Building... antes dotnet run de compilar o projeto. O padrão é false. Essa propriedade não controla a mensagem que identifica o arquivo de configurações de inicialização.

Use environmentVariables para aplicar as configurações de tempo de execução em tempo de desenvolvimento que têm um formulário de variável de ambiente. Por exemplo, um perfil pode definir configurações de GC, como DOTNET_gcServer. Para obter as configurações disponíveis, nomes de variáveis de ambiente e regras de precedência, consulte .NET configurações de runtime e opções de configuração de runtime para coleta de lixo.

Nem todas as configurações de runtime têm um formulário de variável de ambiente. Para configurar um aplicativo independentemente de seu perfil de inicialização, use uma propriedade ou RuntimeHostConfigurationOption item do MSBuild no projeto ou use um runtimeconfig.template.json arquivo. Algumas configurações também podem ser alteradas no código com AppContext.SetSwitch. Esses mecanismos produzem ou modificam a configuração de runtime do aplicativo; não são propriedades adicionais launchSettings.json .

Project propriedades

dotnet runreconhece essas propriedades adicionais quandocommandName:Project

Property Behavior
applicationUrl Define ASPNETCORE_URLS o processo iniciado. Um ASPNETCORE_URLS valor dentro environmentVariables ou de dentro tem -e\|--environment precedência.
launchBrowser Informa às ferramentas de inicialização se deseja abrir um navegador. dotnet run mantém essa propriedade no perfil analisado, mas não abre um navegador.
launchUrl Informa às ferramentas de inicialização qual URL será aberta. dotnet run mantém essa propriedade no perfil analisado, mas não abre um navegador ou usa a URL.

O applicationUrl comportamento dá suporte a ASP.NET Core, mas perfis de inicialização e outras propriedades comuns se aplicam a qualquer projeto de .NET no estilo SDK executável.

Executable propriedades

dotnet runreconhece essas propriedades adicionais quandocommandName:Executable

Property Behavior
executablePath Required. Especifica o processo a ser iniciado. O SDK expande referências de variáveis com suporte, mas não resolve um valor relativo em relação ao arquivo de configurações de inicialização. Use um caminho absoluto ou um comando que o sistema operacional possa localizar.
workingDirectory Optional. Especifica o diretório de trabalho para o processo iniciado. O SDK expande as referências de variável com suporte e resolve um caminho relativo em relação ao diretório que contém o arquivo de configurações de inicialização. Se você omitir a propriedade, o diretório de trabalho usará como padrão o diretório que contém o projeto ou o aplicativo baseado em arquivo.

extensões de Visual Studio e depurador

launchSettings.json é um formato de entrada compartilhado, mas cada consumidor decide quais valores dar suporte e como interpretá-los. Visual Studio, depuradores e outras ferramentas podem reconhecer mais commandName valores e propriedades do que dotnet run.

A tabela a seguir compara o dotnet run contrato com o comportamento comum .NET projeto-sistema em Visual Studio:

Configuração ou comportamento dotnet run Visual Studio
Tipos de perfil com suporte Oferece suporte para Project e Executable. ProjectDá suporte, Executablee um vaziocommandName. As extensões instaladas do sistema de projeto podem adicionar outros tipos de perfil.
Expansão de variável Expande referências %NAME% de variável de ambiente. No .NET 11 e versões posteriores, também expande as referências de propriedade do MSBuild em valores usados para iniciar o processo. Expande as variáveis de ambiente e as propriedades do MSBuild emexecutablePath, , commandLineArgs, workingDirectorylaunchUrlvalores de variável de ambiente e configurações de extensão com valor de cadeia de caracteres.
commandLineArgs para Project Usa o valor do perfil somente quando o projeto não fornece argumentos de execução e você não passa argumentos de aplicativo na linha de comando. Acrescenta o valor do perfil aos argumentos de execução do projeto.
workingDirectory para Project Ignora a propriedade. Dá suporte à propriedade. Um caminho relativo é relativo ao diretório do projeto.
workingDirectory para Executable Um caminho relativo é relativo ao diretório que contém o arquivo de configurações de inicialização. Se omitido, o caminho será o padrão para o diretório do projeto ou do aplicativo baseado em arquivo. Um caminho relativo é relativo ao diretório do projeto. Se omitido, o caminho será padrão para o diretório de saída quando esse diretório existir ou para o diretório do projeto de outra forma.
Relativo executablePath Passa o valor para o sistema operacional sem reenvasá-lo. Resolve um valor com componentes de caminho do diretório de trabalho do perfil. Para um nome executável nu, Visual Studio verifica seu próprio diretório atual e, em seguidaPATH, .
launchBrowser e launchUrl Retém os valores no perfil analisado, mas não abre um navegador. Disponibiliza os valores para um provedor de inicialização. Por exemplo, ASP.NET Core ferramentas pode abrir um navegador.
applicationUrl Define ASPNETCORE_URLS. Disponibiliza o valor para provedores de inicialização instalados, como ferramentas de ASP.NET Core.
dotnetRunMessages Controla a Building... mensagem. Não usa a propriedade para controlar Visual Studio saída.
Propriedades do depurador Ignora propriedades específicas do depurador. Usa propriedades comonativeDebugging, , sqlDebugging, jsWebView2Debugginge remoteDebugEnabledhotReloadEnabled quando o projeto e o depurador dão suporte ao recurso.

No .NET 11 e versões posteriores, ambos os consumidores se expandem"$(ProjectDir)". Em versões anteriores, nenhum valor único workingDirectory identifica o diretório do projeto para ambos os consumidores. Visual Studio se expande"$(ProjectDir)", enquanto dotnet run o trata como texto literal e resolve caminhos relativos do diretório que contém o arquivo de configurações de inicialização. Portanto, use ".." com dotnet run um arquivo ou convencional.My Project/launchSettings.jsonProperties/launchSettings.json Visual Studio resolve o mesmo valor para o pai do diretório do projeto.

Windows Forms e WPF aplicativos não adicionam outro dotnet run tipo de perfil. Use um Project perfil com configurações comuns, como commandLineArgs e environmentVariables. Em Visual Studio, esses tipos de projeto de área de trabalho também podem usar propriedades de depurador aplicáveis, como nativeDebugging para depuração gerenciada e nativa mista ou jsWebView2Debugging para WebView2. As propriedades do navegador e da URL só têm efeito quando um provedor de inicialização ou o aplicativo as consome.

Outros tipos de projeto e cargas de trabalho Visual Studio podem instalar provedores de inicialização que adicionam tipos de perfil ou interpretam propriedades extras. Essas extensões não adicionam suporte a dotnet run: a CLI ignora tipos de perfil sem suporte durante a seleção padrão e relata um erro quando você seleciona um explicitamente.

Para obter as configurações do depurador com suporte do Visual Studio e project interface do usuário, consulte Project configurações para uma configuração de depuração do .NET C#.

Arguments

<applicationArguments>

Argumentos passados para o aplicativo que está sendo executado.

Todos os argumentos que não são reconhecidos são dotnet run passados para o aplicativo. Para separar argumentos de dotnet run argumentos para o aplicativo, use a opção -- .

Encaminhar argumentos para o aplicativo

dotnet run encaminha qualquer token que ele não reconhece para o aplicativo. Os tokens encaminhados mantêm sua ordem original, mas dotnet run primeiro remove as opções que ele entende. Quando uma opção reconhecida aparece entre um nome de opção não reconhecido e seu valor, remover a opção reconhecida pode alterar o significado dos tokens restantes.

Por exemplo, o comando a seguir intercala a opção --project reconhecida entre tokens que o aplicativo deve receber:

dotnet run --app-flag --app-name --project ConsoleApp.csproj A.txt

Depois dotnet run de --project ConsoleApp.csprojconsumir, o aplicativo recebe --app-flag --app-name A.txt. Em seguida, o aplicativo trata A.txt como o valor de , que não corresponde à linha de --app-namecomando original.

Para evitar essa ambiguidade, coloque os argumentos do aplicativo após um literal --:

dotnet run --project ConsoleApp.csproj -- --app-flag --app-name A.txt

O -- separador marca cada token a seguir como um argumento de aplicativo, portanto dotnet run , não os reordena nem os reinterpreta. O separador também faz scripts à prova de futuro em relação a novas dotnet run opções que podem corresponder posteriormente a um token encaminhado anteriormente para o aplicativo.

Note

O mesmo comportamento se aplica a dotnet build e a dotnet test em Microsoft. Modo Testing.Platform (MTP), que encaminha tokens não reconhecidos para o MSBuild ou para o aplicativo de teste, respectivamente. Para obter mais informações sobre dotnet test, consulte Encaminhar argumentos para o aplicativo de teste.

Opções

  • --

    Delimita os argumentos para dotnet run dos argumentos para o aplicativo que está sendo executado. Todos os argumentos após esse delimitador são passados para o aplicativo que está sendo executado.

  • -a|--arch <ARCHITECTURE>

    Especifica a arquitetura de destino. Essa é uma sintaxe abreviada para definir o RID (Identificador de Runtime), em que o valor fornecido é combinado com o RID padrão. Por exemplo, em um computador win-x64, a especificação de --arch x86 define o RID como win-x86. Se você usar essa opção, não use a opção -r|--runtime. Disponível desde .NET 6 Versão Prévia 7.

  • --artifacts-path <ARTIFACTS_DIR>

    Todos os arquivos de saída de compilação do comando executado irão para subpastas no caminho especificado, separados por projeto. Para obter mais informações, consulte Layout de saída de artefatos. Essa opção e o valor fornecido devem ser explicitamente em cascata em qualquer dotnet comando que dependa da saída de outro dotnet comando, por exemplo, ao usar dotnet build --no-restore e dotnet publish --no-build. Disponível desde .NET 8 SDK.

  • -c|--configuration <CONFIGURATION>

    Define a configuração da compilação. O padrão para a maioria dos projetos é Debug, mas você pode substituir as configurações de compilação em seu projeto.

  • --disable-build-servers

    Força o comando a ignorar todos os servidores de build persistentes. Essa opção fornece uma maneira consistente de desabilitar todo o uso do cache de build, o que força um build do zero. Um build que não depende de caches é útil quando os caches podem estar corrompidos ou incorretos por algum motivo. Disponível desde .NET 7 SDK.

  • -e|--environment <KEY=VALUE>

    Define a variável de ambiente especificada no processo que será executada pelo comando. A variável de ambiente especificada não é aplicada ao dotnet run processo.

    As variáveis de ambiente passadas por essa opção têm precedência sobre variáveis de ambiente ambiente, diretivas System.CommandLine env e environmentVariables do perfil de inicialização escolhido. Para obter mais informações, confira Variáveis de ambiente.

    (Essa opção foi adicionada ao SDK .NET 9.0.200.)

  • -f|--framework <FRAMEWORK>

    Compila e executa o aplicativo usando a estrutura especificada. A estrutura deve ser especificada no arquivo de projeto.

  • --file <FILE_PATH>

    O caminho para o aplicativo baseado em arquivo a ser executado. Se um caminho não for especificado, o diretório atual será usado para localizar e executar o arquivo. Para obter mais informações sobre aplicativos baseados em arquivo, consulte Criar aplicativos C# baseados em arquivo.

    No Unix, execute aplicativos baseados em arquivo diretamente usando o nome do arquivo adicionando uma diretiva shebang (#!) e definindo a permissão de execução. Para obter mais informações, consulte o suporte do Unix shebang (#!).

    Introduzido no .NET SDK 10.0.100.

  • --force

    Forçará todas as dependências a serem resolvidas mesmo se última restauração tiver sido bem-sucedida. A especificação desse sinalizador é o mesmo que a exclusão do arquivo project.assets.json.

  • --interactive

    Permite que o comando pare e aguarde entrada ou ação do usuário. Por exemplo, para concluir a autenticação.

  • -lp|--launch-profile <NAME>

    O nome do perfil de inicialização a ser usado ao iniciar o aplicativo. Para obter mais informações, consulte Perfis de inicialização.

  • --no-build

    Não compila o projeto antes da execução. Também define o sinalizador --no-restore implicitamente.

  • --no-cache

    Ignore as verificações atualizadas e sempre crie o programa antes de ser executado.

  • --no-dependencies

    Ao restaurar um projeto com referências de P2P (projeto a projeto), restaura o projeto raiz, não as referências.

  • --no-launch-profile

    Não tenta usar launchSettings.json para configurar o aplicativo.

  • --no-restore

    Não executa uma restauração implícita ao executar o comando.

  • --no-self-contained

    Publique seu aplicativo como um aplicativo dependente da estrutura. Um runtime .NET compatível deve ser instalado no computador de destino para executar seu aplicativo.

  • --os <OS>

    Especifica o sistema operacional (SO) de destino. Essa é uma sintaxe abreviada para definir o RID (Identificador de Runtime), em que o valor fornecido é combinado com o RID padrão. Por exemplo, em um computador win-x64, a especificação de --os linux define o RID como linux-x64. Se você usar essa opção, não use a opção -r|--runtime. Disponível desde .NET 6.

  • --project <PATH>

    Especifica o caminho do arquivo de projeto a ser executado (nome da pasta ou caminho completo). Se não é especificado, ele usa como padrão o diretório atual.

    A abreviação -p para --project foi preterida começando no SDK do .NET 6. Por um tempo limitado, -p ainda pode ser usado para --project , apesar do aviso de substituição. Se o argumento fornecido para a opção não contiver =, o comando aceitará -p como abreviação de --project. Caso contrário, o comando pressupõe que -p seja abreviação para --property. Esse uso flexível de -p para --project será eliminado gradualmente em .NET 7.

  • --property:<NAME>=<VALUE>

    Define uma ou mais propriedades MSBuild. Especifique várias propriedades delimitadas por ponto-e-vírgula ou repetindo a opção:

    --property:<NAME1>=<VALUE1>;<NAME2>=<VALUE2>
--property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>

    O formulário curto -p pode ser usado para --property. Se o argumento fornecido para a opção contiver =, -p será aceito como abreviação de --property. Caso contrário, o comando pressupõe que -p seja abreviação para --project.

    Para passar --property para o aplicativo em vez de definir uma propriedade MSBuild, forneça a opção após o separador de sintaxe --, por exemplo:

    dotnet run -- --property name=value

  • -r|--runtime <RUNTIME_IDENTIFIER>

    Especifica o runtime de destino para o qual restaurar os pacotes. Para obter uma lista de RIDs (Identificadores de Runtime), veja o Catálogo de RIDs.

  • --sc|--self-contained

    Publique o .NET runtime com seu aplicativo para que o runtime não precise ser instalado no computador de destino.

  • --tl:[auto|on|off]

    Especifica se o Agente de Terminal deve ser usado para a saída de build. O padrão é auto, que primeiro verifica o ambiente antes de habilitar o registro em log do terminal. A verificação de ambiente confirma se o terminal é capaz de usar recursos de saída modernos e não está usando uma saída padrão redirecionada antes de habilitar o novo agente. on ignora a verificação de ambiente e habilita o registro em log do terminal. off ignora a verificação de ambiente e usa o agente de console padrão.

    O Agente de Terminal mostra a fase de restauração seguida pela fase de build. Durante cada fase, os projetos de construção atuais aparecem na parte inferior do terminal. Cada projeto que está sendo criado gera tanto o destino do MSBuild em construção no momento quanto o tempo gasto nesse destino. Você pode pesquisar essas informações para saber mais sobre o build. Quando a build de um projeto é concluída, é gravada uma única seção "build concluída" que captura:

    • O nome do projeto criado.
    • A estrutura de destino (se houver vários destinos).
    • O status dessa build.
    • A saída primária dessa build (que contém um hiperlink).
    • Qualquer diagnóstico gerado para esse projeto.

    Essa opção está disponível a partir do .NET 8.

  • -v|--verbosity <LEVEL>

    Define o nível de detalhes do comando. Os valores permitidos são q[uiet], m[inimal], n[ormal], d[etailed] e diag[nostic]. O padrão é minimal. Para obter mais informações, consulte LoggerVerbosity.

  • -?|-h|--help

    Imprime uma descrição de como usar o comando.

Variáveis de ambiente

As seguintes fontes aplicam variáveis de ambiente ao aplicativo iniciado:

  1. Variáveis de ambiente do sistema operacional quando o comando é executado.
  2. Diretivas System.CommandLine env , como [env:key=value]. Elas se aplicam a todo dotnet run o processo, não apenas ao projeto que está sendo executado dotnet run.
  3. Valores gerados a partir do perfil de inicialização escolhido. dotnet run conjuntos DOTNET_LAUNCH_PROFILEe applicationUrl em conjuntos de Project perfil ASPNETCORE_URLS.
  4. environmentVariables do perfil de inicialização escolhido, se houver. Elas se aplicam ao projeto que está sendo executado por dotnet run.
  5. -e|--environment valores de opção da CLI (adicionados .NET SDK versão 9.0.200). Elas se aplicam ao projeto que está sendo executado por dotnet run.

O ambiente é construído na mesma ordem que essa lista, portanto, a opção -e|--environment tem a precedência mais alta.

Exemplos

  • Execute o projeto no diretório atual:

    dotnet run

  • Execute o aplicativo baseado em arquivo especificado no diretório atual:

    dotnet run --file ConsoleApp.cs

    O suporte a aplicativos baseados em arquivo foi adicionado ao SDK 10.0.100 .NET.

  • Execute o projeto especificado:

    dotnet run --project ./projects/proj1/proj1.csproj

  • Execute o projeto no diretório atual, especificando a configuração de versão:

    dotnet run --property:Configuration=Release

  • Execute o projeto no diretório atual (o argumento --help neste exemplo é passado para o aplicativo, visto que a opção vazia -- foi usada):

    dotnet run --configuration Release -- --help

  • Restaure as dependências e as ferramentas para o projeto no diretório atual, apenas mostrando uma saída mínima e, em seguida, execute o projeto:

    dotnet run --verbosity m

  • Execute o projeto no diretório atual usando a estrutura especificada e passe argumentos para o aplicativo:

    dotnet run -f net6.0 -- arg1 arg2

    No exemplo a seguir, três argumentos são passados para o aplicativo. Um argumento é passado usando -e dois argumentos são passados após --:

    dotnet run -f net6.0 -arg1 -- arg2 arg3
  • Last updated on