Opções do compilador C# que controlam a saída do compilador

  • Artigo

As seguintes opções controlam a geração de saída do compilador.

MSBuild csc.exe Descrição
DocumentationFile -doc: Gere o arquivo de documento XML a partir de comentários ///.
OutputAssembly -out: Especifique o arquivo de assembly de saída.
PlatformTarget -platform: Especifique a CPU da plataforma de destino.
ProduceReferenceAssembly -refout: Gera um assembly de referência.
TargetType -target: Especifique o tipo do assembly de saída.

DocumentationFile

A opção DocumentationFile permite colocar comentários de documentação em um arquivo XML. Para saber mais sobre como documentar seu código, consulte Marcações Recomendadas para Comentários de Documentação. O valor especifica o caminho para o arquivo XML de saída. O arquivo XML contém os comentários nos arquivos de código-fonte da compilação.

<DocumentationFile>path/to/file.xml</DocumentationFile>

O arquivo de código-fonte que contém as instruções principal ou de nível superior é apresentado primeiro no XML. Você geralmente deseja usar o arquivo .xml gerado com o IntelliSense. O nome.xml deve ser o mesmo que o nome do assembly. O arquivo .xml deve estar no mesmo diretório que o assembly. Quando o assembly for referenciado em um projeto do Visual Studio, o arquivo .xml também será encontrado. Para obter mais informações sobre como gerar comentários de código, consulte Fornecendo comentários de código. A menos que você compile com <TargetType:Module>, file conterá <assembly> e </assembly> e marcações especificando o nome do arquivo com o manifesto do assembly para o arquivo de saída. Por exemplo, consulte Como usar as funcionalidades da documentação XML.

Observação

A opção DocumentationFile se aplica a todos os arquivos no projeto. Para desabilitar avisos relacionados aos comentários de documentação para um arquivo ou uma seção específica do código, use #pragma warning.

Essa opção pode ser usada em qualquer projeto no estilo SDK do .NET. Para obter mais informações, consulte propriedade DocumentationFile.

OutputAssembly

A opção OutputAssembly especifica o nome do arquivo de saída. O caminho de saída especifica a pasta em que a saída do compilador é colocada.

<OutputAssembly>folder</OutputAssembly>

Especifique o nome completo e a extensão do arquivo que você deseja criar. Se você não especificar o nome do arquivo de saída, o MSBuild usará o nome do projeto para especificar o nome do assembly de saída. Projetos de estilo antigo usam as seguintes regras:

  • Um .exe extrairá seu nome do arquivo do código-fonte que contém o método Main ou instruções de alto nível.
  • Um arquivo .dll ou .netmodule extrairá seu nome do primeiro arquivo de código-fonte.

Os módulos produzidos como parte de uma compilação se tornam arquivos associados a qualquer assembly também produzido na compilação. Use ildasm.exe para exibir o manifesto do assembly para ver os arquivos associados.

A opção do compilador OutputAssembly é necessária para que um exe seja o destino de um assembly amigável.

PlatformTarget

Especifica qual versão do CLR pode executar o assembly.

<PlatformTarget>anycpu</PlatformTarget>
  • O anycpu (padrão) compila seu assembly para que ele seja executado em qualquer plataforma. Seu aplicativo será executado como um processo de 64 bits sempre que possível e realizará fallback para 32 bits quando apenas esse modo estiver disponível.
  • anycpu32bitpreferred compila seu assembly para que ele seja executado em qualquer plataforma. Seu aplicativo é executado no modo 32 bits em sistemas que dão suporte para aplicativos de 32 bits e 64 bits. É possível especificar essa opção apenas para projetos que definem como destino o .NET Framework 4.5 ou posterior.
  • O ARM compila seu assembly para que ele seja executado em um computador que tem um processador ARM (Advanced RISC Machine).
  • ARM64 compila o assembly para execução pelo CLR de 64 bits em um computador que tem um processador ARM (Máquina RISC Avançada) que dá suporte ao conjunto de instruções A64.
  • x64 compila o assembly para ser executado pelo CLR de 64 bits em um computador que dá suporte ao conjunto de instruções AMD64 ou EM64T.
  • x86 compila o assembly para ser executado pelo CLR compatível com x86 de 32 bits.
  • Itanium compila o assembly para ser executado pelo CLR de 64 bits em um computador com um processador Itanium.

Em um sistema operacional do Windows de 64 bits:

  • Assemblies compilados com x86 serão executados no CLR de 32 bits em execução no x86.
  • Uma DLL compilada com o anycpu é executada no mesmo CLR que o processo no qual ela é carregada.
  • Os executáveis compilados com anycpu são executados no CLR de 64 bits.
  • Os executáveis compilados com anycpu32bitpreferred são executados no CLR de 32 bits.

A configuração anycpu32bitpreferred é válida apenas para arquivos .EXE (executáveis) e requer o .NET Framework 4.5 ou posterior. Para obter mais informações sobre o desenvolvimento de um aplicativo para ser executado em um sistema operacional Windows de 64 bits, consulte Aplicativos de 64 bits.

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

O comportamento de anycpu tem algumas nuances adicionais no .NET Core e no .NET 5 e versões posteriores. Quando você definir anycpu, publique seu aplicativo e execute-o com o dotnet.exe x86 ou o dotnet.exe x64. Para aplicativos autocontidos, a etapa dotnet publish empacota o executável para configurar RID.

ProduceReferenceAssembly

A opção ProduceReferenceAssembly controla se o compilador produz assemblies de referência.

<ProduceReferenceAssembly>true</ProduceReferenceAssembly>

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

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

Geralmente, você não precisa trabalhar diretamente com arquivos assembly de referência. Por padrão, assemblies de referência são gerados em uma ref subpasta do caminho intermediário (ou seja, obj/ref/). Para gerá-los no diretório de saída (ou seja bin/ref/, ) configure ProduceReferenceAssemblyInOutDir para true no seu projeto.

O SDK do .NET 6.0.200 fez uma alteração que moveu assemblies de referência do diretório de saída para o diretório intermediário por padrão.

TargetType

A opção do compilador TargetType pode ser especificada em uma das seguintes formas:

  • library: para criar uma biblioteca de códigos. library é o valor padrão.
  • exe: para criar um arquivo .exe.
  • module para criar um módulo.
  • winexe para criar um programa do Windows.
  • winmdobj para criar um arquivo .winmdobj intermediário.
  • appcontainerexe para criar um arquivo .exe para aplicativos Windows 8.x Store.

Observação

Para destinos .NET Framework, a menos que você especifique o módulo, essa opção faz com que um manifesto do assembly .NET Framework seja colocado em um arquivo de saída. Para obter mais informações, consulte Assemblies no .NET e atributos comuns.

<TargetType>library</TargetType>

O compilador cria apenas um manifesto do assembly por compilação. As informações sobre todos os arquivos em uma compilação são colocados no manifesto do assembly. Ao gerar vários arquivos de saída na linha de comando, apenas um manifesto do assembly pode ser criado e ele deve ir para o primeiro arquivo de saída especificado na linha de comando.

Se você criar um assembly, pode indicar que todo ou parte do seu código está em conformidade com CLS com o atributo CLSCompliantAttribute.

biblioteca

A opção library faz com que o compilador crie uma DLL (biblioteca de vínculo dinâmico) em vez de um EXE (arquivo executável). A DLL será criada com a extensão .dll A menos que seja especificado de outra forma com a opção OutputAssembly, o nome do arquivo de saída usa o nome do primeiro arquivo de entrada. Ao criar um arquivo .dll, um método Main não é necessário.

exe

A opção exe faz com que o compilador crie um aplicativo de console executável (EXE). O arquivo executável será criado com a extensão .exe. Use winexe para criar um executável de programa do Windows. A menos que seja especificado de outra forma com a opção OutputAssembly, o nome do arquivo de saída usará o nome do arquivo de entrada que contém o método Main ou instruções de alto nível). Somente um método ponto de entrada é necessário nos arquivos de código-fonte que são compilados em um arquivo .exe. A opção do compilador StartupObject permite especificar qual classe contém o método Main, nos casos em que o código tem mais de uma classe com um método Main.

module

Essa opção faz com que o compilador não gere um manifesto do assembly. Por padrão, o arquivo de saída criado por meio da compilação com essa opção terá uma extensão .netmodule. Um arquivo que não tem um manifesto do assembly não pode ser carregado pelo tempo de execução do .NET. No entanto, esse arquivo pode ser incorporado no manifesto do assembly de um assembly com AddModules. Se mais de um módulo for criado em uma única compilação, tipos internos em um módulo estarão disponíveis para outros módulos na compilação. Quando o código em um módulo referencia tipos internal em outro módulo, os dois módulos deverão ser incorporados em um manifesto do assembly, com AddModules. Não há suporte para a criação de um módulo no ambiente de desenvolvimento do Visual Studio.

winexe

A opção winexe faz com que o compilador crie um programa do Windows executável (EXE). O arquivo executável será criado com a extensão .exe. Um programa do Windows é aquele que fornece uma interface do usuário da biblioteca do .NET ou com as APIs do Windows. Use exe para criar um aplicativo de console. A menos que seja especificado de outra forma com a opção OutputAssembly, o nome do arquivo de saída usará o nome do arquivo de entrada que contém o método Main. Somente um método Main é necessário nos arquivos de código-fonte que são compilados em um arquivo .exe. A opção StartupObject permite especificar qual classe contém o método Main, nos casos em que o código tem mais de uma classe com um método Main.

winmdobj

Se você usar a opção winmdobj, o compilador criará um arquivo .winmdobj intermediário que pode ser convertido em um arquivo binário do Windows Runtime (.winmd). O arquivo .winmd pode, então, ser consumido por programas JavaScript e C++, bem como programas de linguagem gerenciada.

A configuração winmdobj indica para o compilador que um módulo intermediário é necessário. O arquivo .winmdobj pode, então, ser alimentado por meio da ferramenta de exportação WinMDExp para produzir um arquivo de metadados do Windows (.winmd). O arquivo .winmd contém o código da biblioteca original e os metadados do WinMD que são usados pelo JavaScript ou C++ e pelo Windows Runtime. A saída de um arquivo que é compilado usando a opção do compilador winmdobj é usada apenas como entrada para a ferramenta de exportação WimMDExp. O arquivo .winmdobj em si não é referenciado diretamente. A menos que você use a opção OutputAssembly, o nome do arquivo de saída usará o nome do primeiro arquivo de entrada. Um método Main não é necessário.

appcontainerexe

Se você usar a opção do compilador appcontainerexe, o compilador criará um arquivo executável (.exe) do Windows que deverá ser executado em um contêiner de aplicativos. Essa opção é equivalente a -target:winexe, mas foi projetada para aplicativos Windows 8.x Store.

Para exigir que o aplicativo seja executado em um contêiner de aplicativos, esta opção define um bit no arquivo PE. Quando esse bit estiver definido, ocorrerá um erro se o método CreateProcess tentar inicializar o arquivo executável fora de um contêiner de aplicativos. A menos que você use a opção OutputAssembly, o nome do arquivo de saída usará o nome do arquivo de entrada que contém o método Main.