Dotnet Run

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

Nome

dotnet run - Executa o código-fonte sem qualquer compilação explícita ou comandos de lançamento.

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

Description

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

Os arquivos de saída são gravados no local padrão, que é bin/<configuration>/<target>. Por exemplo, se você tiver um netcoreapp2.1 aplicativo 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 obj diretório.

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

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

dotnet myapp.dll

Para mais informações sobre o driver dotnet, consulte .NET CLI Overview.

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

Restauração implícita

Você não precisa executar dotnet restore porque ele é executado implicitamente por todos os comandos que exigem uma restauração para ocorrer, como dotnet new, dotnet build, dotnet run, dotnet test, dotnet publishe dotnet pack. Para desativar a restauração implícita, use a --no-restore opção.

O comando dotnet restore continua a ser útil em certos cenários onde a restauração explicitamente faz sentido, como builds de integração contínua em Azure DevOps Services ou em sistemas de build que precisam de controlar explicitamente quando ocorre a restauração.

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

Este comando suporta as dotnet restore opções quando passado na forma longa (por exemplo, --source). Opções de formulário curto, como -s, não são suportadas.

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 este comando terminar, o download será interrompido. Para obter mais informações, consulte Manifestos de publicidade.

Perfis de lançamento

Os perfis de lançamento configuram como dotnet run inicia uma aplicação durante o desenvolvimento. Para um projeto ao estilo SDK, coloque as definições em Properties/launchSettings.json. Em vez disso, os projetos Visual Basic utilizamMy Project/launchSettings.json.

Aplicações baseadas em ficheiros podem usar um [ApplicationName].run.json ficheiro ao lado do ficheiro de origem. Para a ordem de pesquisa de ficheiros e exemplos, consulte Perfis de Lançamento para aplicações baseadas em ficheiros.

O ficheiro de definições de lançamento contém um objeto de topo profiles . Cada propriedade em profiles define um perfil nomeado:

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

O parser das definições de lançamento do SDK .NET aceita comentários JSON e vírgulas finais.

Selecione um perfil

Use --launch-profile <NAME> para selecionar um perfil nomeado. A correspondência do nome é indistinta a maiúsculas e maiúsculas. Nomes de perfil que diferem apenas por caso são ambíguos e produzem erro.

Se não especificares um nome, dotnet run seleciona o primeiro perfil por ordem de ficheiro que commandName suporta. Uso --no-launch-profile para saltar o ficheiro de definições de lançamento.

Quando dotnet run aplica um perfil, este define DOTNET_LAUNCH_PROFILE para o nome do perfil selecionado no processo de lançamento. Uma fonte posterior de variáveis de ambiente pode sobrepor o valor.

Tipos de perfis suportados

O SDK .NET suporta estes commandName valores para dotnet run. Os valores são diferenciados entre maiúsculas e maiúsculas.

commandName Comportamento
Project Constrói o projeto e inicia o comando produzido pelo projeto.
Executable Inicia o comando especificado por executablePath. A menos que especifique --no-build, dotnet run continua a construir o projeto primeiro.

Propriedades comuns

dotnet run reconhece estas propriedades para ambos os tipos de perfis suportados:

dotnet run expande %NAME% referências de variáveis de ambiente em valores de cadeia suportados. No .NET 11 e versões posteriores, também expande referências de propriedades do MSBuild em valores que utiliza para lançar o processo, usando a mesma substituição de token que o Visual Studio. Não expande referências ao estilo $NAME shell.

Property Comportamento
commandLineArgs Especifica argumentos para o processo iniciado. Argumentos explícitos de aplicação na linha de comandos têm prioridade. Para um Project perfil, os argumentos fornecidos pelo project também têm prioridade.
environmentVariables Especifica variáveis de ambiente para o processo lançado. Os valores do perfil sobrepõem variáveis de ambiente herdadas e geradas pelo SDK, e -e\|--environment os valores sobrepõem-se aos valores do perfil.
dotnetRunMessages Quando true, imprime Building... antes dotnet run de construir o projeto. A predefinição é false. Esta propriedade não controla a mensagem que identifica o ficheiro de definições de lançamento.

Use environmentVariables para aplicar definições de configuração em tempo de execução em tempo de desenvolvimento que tenham uma forma variável de ambiente. Por exemplo, um perfil pode definir definições de GC como DOTNET_gcServer. Para as definições disponíveis, nomes de variáveis de ambiente e regras de precedência, consulte definições de configuração em tempo de execução .NET e opções de configuração em tempo de execução para recolha de lixo.

Nem todas as definições de tempo de execução têm uma forma de variável ambiental. Para configurar uma aplicação independentemente do seu perfil de lançamento, use uma propriedade ou RuntimeHostConfigurationOption item do MSBuild no projeto, ou utilize um runtimeconfig.template.json ficheiro. Algumas definições também podem ser alteradas em código com AppContext.SetSwitch. Estes mecanismos produzem ou modificam a configuração em tempo de execução da aplicação; não são propriedades adicionais launchSettings.json .

Project propriedades

dotnet run reconhece estas propriedades adicionais quando commandName é Project:

Property Comportamento
applicationUrl Começa ASPNETCORE_URLS o processo de lançamento. Um ASPNETCORE_URLS valor em environmentVariables ou de -e\|--environment tem precedência.
launchBrowser Diz à ferramenta de lançamento se deve abrir um navegador. dotnet run mantém esta propriedade no perfil analisado, mas não abre um navegador.
launchUrl Diz à ferramenta de lançamento qual URL abrir. dotnet run mantém esta propriedade no perfil analisado, mas não abre um navegador nem usa o URL.

O applicationUrl comportamento suporta ASP.NET Core, mas os perfis de lançamento e as outras propriedades comuns aplicam-se a qualquer projeto .NET ao estilo SDK executável.

Executable propriedades

dotnet run reconhece estas propriedades adicionais quando commandName é Executable:

Property Comportamento
executablePath Required. Especifica o processo a começar. O SDK expande as referências de variáveis suportadas, mas não resolve um valor relativo no ficheiro de definições de lançamento. Use um caminho absoluto ou um comando que o sistema operativo consiga localizar.
workingDirectory Optional. Especifica o diretório de trabalho para o processo de lançamento. O SDK expande as referências de variáveis suportadas e resolve um caminho relativo em relação ao diretório que contém o ficheiro de definições de lançamento. Se omitir a propriedade, o diretório de trabalho passa por defeito ao diretório que contém o projeto ou a aplicação baseada em ficheiros.

Visual Studio e extensões de depurador

launchSettings.json é um formato de entrada partilhado, mas cada consumidor decide quais os valores a apoiar e como os interpretar. Visual Studio, depuradores e outras ferramentas conseguem reconhecer mais commandName valores e propriedades do que dotnet run.

A tabela seguinte compara o dotnet run contrato com o comportamento comum dos sistemas de projeto .NET no Visual Studio:

Ambiente ou comportamento dotnet run Visual Studio
Tipos de perfis suportados Suporta Project e Executable. Suporta Project, Executable, e um vazio commandName. Extensões instaladas no sistema de projetos podem adicionar outros tipos de perfis.
Expansão variável Expande %NAME% as referências de variáveis ambientais. No .NET 11 e versões posteriores, também expande as referências de propriedades do MSBuild nos valores que utiliza para lançar o processo. Expande variáveis de ambiente e propriedades MSBuild em executablePath, commandLineArgs, workingDirectory, launchUrl, valores de variáveis de ambiente e definições de extensão com valores de string.
commandLineArgs para Project Usa o valor do perfil apenas quando o projeto não fornece argumentos de execução e não passa argumentos de aplicação na linha de comandos. Adiciona o valor do perfil aos argumentos de execução do projeto.
workingDirectory para Project Ignora a propriedade. Sustenta a propriedade. Um caminho relativo é relativo ao diretório do projeto.
workingDirectory para Executable Um caminho relativo é relativo ao diretório que contém o ficheiro de definições de lançamento. Se for omitido, o caminho passa por defeito para o diretório do projeto ou da aplicação baseada em ficheiros. Um caminho relativo é relativo ao diretório do projeto. Se for omitido, o caminho passa por defeito para o diretório de saída quando esse diretório existe, ou para o diretório do projeto caso contrário.
Relativo executablePath Passa o valor para o sistema operativo sem o rebasear. Resolve um valor com componentes path do diretório de trabalho do perfil. Para um nome executável simples, o Visual Studio verifica o seu próprio diretório atual e depois PATH.
launchBrowser e launchUrl Mantém os valores no perfil analisado, mas não abre o navegador. Disponibiliza os valores ao fornecedor de lançamentos. Por exemplo, as ferramentas ASP.NET Core podem abrir um navegador.
applicationUrl Define ASPNETCORE_URLS. Disponibiliza o valor aos fornecedores instalados de lançamento, como as ferramentas ASP.NET Core.
dotnetRunMessages Controla a Building... mensagem. Não usa essa propriedade para controlar a saída do Visual Studio.
Propriedades do depurador Ignora propriedades específicas do depurador. Utiliza propriedades como nativeDebugging, sqlDebugging, jsWebView2Debugging, remoteDebugEnabled, e hotReloadEnabled quando o projeto e o depurador suportam a funcionalidade.

No .NET 11 e versões posteriores, ambos os consumidores expandem "$(ProjectDir)". Em versões anteriores, nenhum valor único workingDirectory identificava o diretório do projeto para ambos os consumidores. O Visual Studio expande "$(ProjectDir)", enquanto dotnet run o trata como texto literal e resolve caminhos relativos a partir do diretório que contém o ficheiro de definições de lançamento. Por isso, use ".." com dotnet run um convencional Properties/launchSettings.json ou My Project/launchSettings.json lima. O Visual Studio resolve o mesmo valor para o pai do diretório do projeto.

As aplicações Windows Forms e WPF não adicionam outro dotnet run tipo de perfil. Use um Project perfil com definições comuns como commandLineArgs e environmentVariables. No Visual Studio, estes tipos de projetos de ambiente de trabalho também podem usar propriedades de depuração aplicáveis, como nativeDebugging para depuração mista gerida e nativa ou jsWebView2Debugging para WebView2. As propriedades do navegador e das URLs só têm efeito quando um fornecedor de lançamento ou a aplicação as consome.

Outros tipos de projetos e cargas de trabalho do Visual Studio podem instalar fornecedores de lançamento que adicionam tipos de perfil ou interpretam propriedades extra. Essas extensões não acrescentam suporte a dotnet run: a CLI salta tipos de perfil não suportados durante a seleção por defeito e reporta um erro quando seleciona um explicitamente.

Para as definições de depuração suportadas pelo Visual Studio e a interface do project, consulte Project settings for a .NET C# debug configuration.

Arguments

<applicationArguments>

Argumentos passados para o aplicativo que está sendo executado.

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

Encaminhar os argumentos para a candidatura

dotnet run encaminha qualquer token que não reconheça para a aplicação. Os tokens encaminhados mantêm a ordem original, mas dotnet run primeiro removem as opções que compreendem. Quando uma opção reconhecida aparece entre o nome de uma opção não reconhecida e o seu valor, remover a opção reconhecida pode alterar o significado dos tokens remanescentes.

Por exemplo, o seguinte comando intercala a opção --project reconhecida entre os tokens que a aplicação pretende receber:

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

Após dotnet run consumir --project ConsoleApp.csproj, a aplicação recebe --app-flag --app-name A.txt. A aplicação então trata A.txt como valor de --app-name, que não corresponde à linha de comandos original.

Para evitar esta ambiguidade, coloque os argumentos da aplicação após um literal --:

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

O -- separador marca cada token seguinte como argumento de aplicação, por isso dotnet run não os reordena nem reinterpreta. O separador também prepara scripts para o futuro contra novas dotnet run opções que mais tarde podem corresponder a um token previamente encaminhado para a aplicação.

Note

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

Opções

  • --

    Delimita argumentos a dotnet run partir de argumentos para o aplicativo que está sendo executado. Todos os argumentos após esse delimitador são passados para a execução do aplicativo.

  • -a|--arch <ARCHITECTURE>

    Especifica a arquitetura de destino. Esta é uma sintaxe abreviada para definir o Runtime Identifier (RID), onde o valor fornecido é combinado com o RID padrão. Por exemplo, em uma win-x64 máquina, especificar --arch x86 define o RID como win-x86. Se você usar essa opção, não use a -r|--runtime opção. Disponível desde .NET 6 Preview 7.

  • --artifacts-path <ARTIFACTS_DIR>

    Todos os arquivos de saída de compilação do comando executado irão em subpastas sob o caminho especificado, separados por projeto. Para obter mais informações, consulte Layout de saída de artefatos. Esta opção e o valor fornecido devem ser explicitamente encadeados 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 o SDK .NET 8.

  • -c|--configuration <CONFIGURATION>

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

  • --disable-build-servers

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

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

    Define a variável de ambiente especificada no processo que será executado 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 as variáveis de ambiente ambiente, diretivas System.CommandLine env e environmentVariables do perfil de inicialização escolhido. Para obter mais informações, consulte Variáveis de ambiente.

    (Esta opção foi adicionada no .NET SDK 9.0.200.)

  • -f|--framework <FRAMEWORK>

    Cria 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 aplicações baseadas em ficheiros diretamente usando o nome do ficheiro, adicionando uma diretiva shebang (#!) e definindo a permissão de execução. Para mais informações, consulte o suporte ao Shebang Unix (#!).

    Introduzido no .NET SDK 10.0.100.

  • --force

    Força todas as dependências a serem resolvidas, mesmo que a última restauração tenha sido bem-sucedida. Especificar esse sinalizador é o mesmo que excluir o arquivo project.assets.json .

  • --interactive

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

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

    O nome do perfil de lançamento a usar ao lançar a aplicação. Para mais informações, consulte Perfis de Lançamento.

  • --no-build

    Não cria o projeto antes da execução. Também coloca implicitamente a --no-restore bandeira.

  • --no-cache

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

  • --no-dependencies

    Ao restaurar um projeto com referências de projeto a projeto (P2P), restaura o projeto raiz e 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 a sua candidatura como uma aplicação dependente do framework. Um runtime .NET compatível deve ser instalado na máquina de destino para executar a sua aplicação.

  • --os <OS>

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

  • --project <PATH>

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

    A abreviatura -p para --project está obsoleta começando no SDK .NET 6. Por um tempo limitado, -p ainda pode ser usado para --project apesar do aviso de depreciaçã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 assume que -p é a abreviação de --property. Este uso flexível de -p para --project será gradualmente eliminado em .NET 7.

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

    Define uma ou mais propriedades do 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>

    A forma -p abreviada pode ser usada para --property. Se o argumento fornecido para a opção contiver =, -p é aceite como abreviatura de --property. Caso contrário, o comando assume que -p é a abreviação de --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 tempo de execução de destino para o qual restaurar pacotes. Para obter uma lista de identificadores de tempo de execução (RIDs), consulte o catálogo RID.

  • --sc|--self-contained

    Publique o runtime .NET com a sua aplicação para que o runtime não precise de ser instalado na máquina de destino.

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

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

    O Terminal Logger mostra a fase de restauração seguida pela fase de compilação. Durante cada fase, os projetos atualmente em construção aparecem na parte inferior do terminal. Cada projeto que está construindo produz tanto a meta do MSBuild que está sendo criada quanto a quantidade de tempo gasto nessa meta. Você pode pesquisar essas informações para saber mais sobre a compilação. Quando um projeto termina de construir, uma única seção "construção concluída" é escrita que captura:

    • O nome do projeto construído.
    • A estrutura de destino (se multidirecionada).
    • O status dessa compilação.
    • A saída primária dessa compilação (que é hiperligada).
    • Qualquer diagnóstico gerado para esse projeto.

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

  • -v|--verbosity <LEVEL>

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

  • -?|-h|--help

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

Variáveis de ambiente

As seguintes fontes aplicam variáveis de ambiente à aplicação lançada:

  1. Variáveis de ambiente do sistema operacional quando o comando é executado.
  2. Diretivas System.CommandLine env , como [env:key=value]. Estes aplicam-se a todo dotnet run o processo, não apenas ao projeto que está a ser gerido pela dotnet run.
  3. Valores gerados a partir do perfil de lançamento escolhido. dotnet run define DOTNET_LAUNCH_PROFILE, e applicationUrl num Project perfil define ASPNETCORE_URLS.
  4. environmentVariables Do perfil de lançamento escolhido, se houver. Estas aplicam-se ao projeto que está a ser gerido pela dotnet run.
  5. -e|--environment valores das opções CLI (adicionados no SDK .NET versão 9.0.200). Estas aplicam-se ao projeto que está a ser gerido pela dotnet run.

O ambiente é construído na mesma ordem que esta lista, de modo que a -e|--environment opção tem a maior precedência.

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 aplicações baseadas em ficheiros foi adicionado no .NET SDK 10.0.100.

  • 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 --help argumento neste exemplo é passado para o aplicativo, já que a opção em branco -- é usada):

    dotnet run --configuration Release -- --help

  • Restaure dependências e ferramentas para o projeto no diretório atual mostrando apenas a 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 depois de --:

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