Compartilhar via

Opções do compilador C# que controlam a geração de código

  • Artigo

As opções a seguir controlam a geração de código pelo compilador. A nova sintaxe MSBuild é mostrada em Negrito. A sintaxe csc.exe mais antiga é mostrada em code style.

  • DebugType / -debug: emitir (ou não emitir) informações de depuração.
  • Optimize / -optimize: habilitar otimizações.
  • Deterministic / -deterministic: produzir saída equivalente byte por byte da mesma fonte de entrada.
  • ProduceOnlyReferenceAssembly / -refonly: produzir um assembly de referência, em vez de um assembly completo, como a saída primária.

Observação

Consulte Opções do compilador para obter mais informações sobre como configurar essas opções para o seu projeto.

DebugType

A opção DebugType faz o compilador gerar informações de depuração e colocá-las nos arquivos de saída. As informações de depuração são adicionadas por padrão.

<DebugType>pdbonly</DebugType>

Para todas as versões do compilador que começam com o C# 6.0, não há diferença entre pdbonly e full. Escolha pdbonly. Para alterar o local do arquivo .pdb, consulte PdbFile.

Os seguintes valores são válidos:

Valor Significado
full Emita informações de depuração no arquivo .pdb usando o formato padrão para a plataforma atual:
Windows: um arquivo pdb do Windows.
Linux/macOS: um arquivo PDB portátil .
pdbonly Mesmo que full. Confira a observação abaixo para obter mais informações.
portable Emita informações de depuração no arquivo .pdb usando o formato PDB portátil multiplataforma.
embedded Emita informações de depuração no .dll/.exe em si (o arquivo .pdb não é produzido) usando o formato PDB Portátil.

Importante

As informações a seguir se aplicam somente a compiladores mais antigos que o C# 6.0. O valor desse elemento pode ser full ou pdbonly. O argumento full, que será aplicado se pdbonly não for especificado, permite anexar um depurador ao programa em execução. Especificar pdbonly habilita a depuração do código-fonte quando o programa é iniciado no depurador, mas exibirá somente o assembler quando o programa em execução for anexado ao depurador. Use essa opção para criar builds de depuração. Caso Full seja usado, lembre-se de que isso influenciará a velocidade e o tamanho do código otimizado JIT e haverá um pequeno impacto na qualidade do código com full. Recomenda-se pdbonly ou nenhum PDB para gerar código de versão. Uma diferença entre pdbonly e full é que, com full, o compilador emite uma DebuggableAttribute, que é usada para avisar ao compilador JIT que as informações de depuração estão disponíveis. Portanto, haverá um erro se o código contiver DebuggableAttribute definido como false, caso full seja usado. Para obter informações sobre como configurar o desempenho de depuração de um aplicativo, consulte Facilitando a Depuração de uma Imagem.

Otimizar

A opção Optimize habilita ou desabilita otimizações executadas pelo compilador para tornar o arquivo de saída menor, mais rápido e mais eficiente. A opção Optimize está habilitada por padrão para uma configuração de build Release. Está desativado por padrão para Depuração e qualquer outra configuração de compilação.

<Optimize>true</Optimize>

Defina a opção Optimize na página de propriedades da Build para seu projeto no Visual Studio.

Optimize também informa o Common Language Runtime para otimizar o código em tempo de execução. Por padrão, as otimizações estão desabilitadas. Especifique Optimize+ para habilitar otimizações. Ao criar um módulo a ser usado por um assembly, use as mesmas configurações Optimize usadas pelo assembly. É possível combinar as opções Optimize e Debug.

Determinística

Faz com que o compilador produza um assembly cuja saída byte a byte é idêntica entre compilações para entradas idênticas.

<Deterministic>true</Deterministic>

Por padrão, a saída do compilador de um determinado conjunto de entradas é exclusiva, pois o compilador adiciona um carimbo de data/hora e um MVID (um Module.ModuleVersionId. Basicamente, é um GUID que identifica exclusivamente o módulo e a versão.), que é gerado com base em números aleatórios. Use a opção <Deterministic> para produzir um assembly determinística, cujo conteúdo binário seja idêntico entre compilações, desde que a entrada permaneça a mesma. Nesse build, os campos de carimbo de data/hora e MVID serão substituídos por valores derivados de um hash de todas as entradas de compilação. O compilador considera as seguintes entradas que afetam o determinismo:

  • A sequência de parâmetros de linha de comando.
  • O conteúdo do arquivo de resposta .rsp do compilador.
  • A versão precisa do compilador usado e seus assemblies referenciados.
  • O caminho do diretório atual.
  • O conteúdo binário de todos os arquivos passados explicitamente para o compilador direta ou indiretamente, incluindo:
    • Arquivos de origem
    • Assemblies referenciados
    • Módulos referenciados
    • Recursos
    • O arquivo de chave de nome forte
    • @ arquivos de resposta
    • Analisadores
    • Conjuntos de regras
    • Outros arquivos que podem ser usados por analisadores
  • A cultura atual (para o idioma no qual as mensagens de diagnóstico e exceção são produzidas).
  • A codificação padrão (ou a página de código atual) se a codificação não for especificada.
  • A existência, a inexistência e o conteúdo dos arquivos em caminhos de pesquisa do compilador (especificados, por exemplo, por -lib ou -recurse).
  • A plataforma CLR (Common Language Runtime) na qual o compilador é executado.
  • O valor de %LIBPATH%, que pode afetar o carregamento de dependência do analisador.

A compilação determinística pode ser usada para estabelecer se um binário é compilado de uma fonte confiável. A saída determinística pode ser útil quando a origem está disponível publicamente. Ele também pode determinar se as etapas de build que dependem de alterações no binário usado no processo de build.

ProduceOnlyReferenceAssembly

A opção ProduceOnlyReferenceAssembly indica que um assembly de referência deve ser gerado em vez de um assembly de implementação, como a saída primária. O parâmetro ProduceOnlyReferenceAssembly silenciosamente desabilita a geração de PDBs, uma vez que assemblies de referência não podem ser executados.

<ProduceOnlyReferenceAssembly>true</ProduceOnlyReferenceAssembly>

Assemblies de referência são um tipo especial de assembly. Os assemblies contêm apenas a quantidade mínima de metadados necessários para representar a superfície de API pública da biblioteca. Eles incluem declarações para todos os membros que são significativas ao referenciar um assembly em ferramentas de build, mas excluem todas as implementações de membros e declarações de membros privados que não têm nenhum impacto observável em seu contrato de API. Para obter mais informações, consulte Assemblies de referência.

As opções ProduceOnlyReferenceAssembly e ProduceReferenceAssembly são mutuamente exclusivas.