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

Artigo
03/02/2024

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

MSBuild	csc.exe	Description
DocumentaçãoArquivo	`-doc:`	Gere o arquivo doc XML a partir de `///` comentários.
OutputAssembly	`-out:`	Especifique o arquivo de assembly de saída.
PlataformaTarget	`-platform:`	Especifique a CPU da plataforma de destino.
ProduceReferenceAssembly	`-refout:`	Gere um assembly de referência.
Tipo de alvo	`-target:`	Especifique o tipo do assembly de saída.

DocumentaçãoArquivo

A opção DocumentationFile permite que você coloque comentários de documentação em um arquivo XML. Para saber mais sobre como documentar seu código, consulte Tags 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 instruções Main ou de nível superior é gerado primeiro no XML. Muitas vezes, você desejará usar o arquivo de .xml gerado com o IntelliSense. O .xml nome do arquivo deve ser o mesmo que o nome do assembly. O arquivo .xml deve estar no mesmo diretório que o assembly. Quando o assembly é referenciado em um projeto do Visual Studio, o arquivo de .xml também é 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> tags especificando o nome do arquivo que contém o manifesto de assembly para o arquivo de saída. Para obter exemplos, consulte Como usar os recursos de documentação XML.

Nota

A opção DocumentationFile aplica-se a todos os arquivos no projeto. Para desativar avisos relacionados a comentários de documentação para um arquivo específico ou seção de código, use #pragma aviso.

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 onde a saída do compilador é colocada.

<OutputAssembly>folder</OutputAssembly>

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

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

Todos os módulos produzidos como parte de uma compilação tornam-se 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 de compilador OutputAssembly é necessária para que um exe seja o destino de um assembly amigo.

PlataformaTarget

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

<PlatformTarget>anycpu</PlatformTarget>

AnyCPU (padrão) compila seu assembly para ser executado em qualquer plataforma. Seu aplicativo é executado como um processo de 64 bits sempre que possível e retorna para 32 bits quando apenas esse modo está disponível.
anycpu32bitpreferred compila seu assembly para ser executado em qualquer plataforma. Seu aplicativo é executado no modo de 32 bits em sistemas que suportam aplicativos de 64 bits e 32 bits. Você pode especificar essa opção somente para projetos destinados ao .NET Framework 4.5 ou posterior.
O ARM compila o assembly para ser executado em um computador que tenha um processador Advanced RISC Machine (ARM).
ARM64 compila seu assembly para ser executado pelo CLR de 64 bits em um computador que tenha um processador Advanced RISC Machine (ARM) que suporta o conjunto de instruções A64.
x64 compila seu assembly para ser executado pelo CLR de 64 bits em um computador que suporta o conjunto de instruções AMD64 ou EM64T.
x86 compila seu assembly para ser executado pelo CLR de 32 bits compatível com x86.
O Itanium compila seu assembly para ser executado pelo CLR de 64 bits em um computador com um processador Itanium.

Em um sistema operacional Windows de 64 bits:

Os assemblies compilados com x86 são executados no CLR de 32 bits em execução no WOW64.
Uma DLL compilada com o anycpu é executada no mesmo CLR que o processo no qual ele é carregado.
Os executáveis compilados com o anycpu são executados no CLR de 64 bits.
Executáveis compilados com anycpu32bitpreferred executam no CLR de 32 bits.

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

Você define a opção PlatformTarget na página de propriedades Buildpara seu projeto no Visual Studio.

O comportamento de anycpu tem algumas nuances adicionais no .NET Core e .NET 5 e versões posteriores. Ao definir anycpu, publique seu aplicativo e execute-o com o x86 dotnet.exe ou o x64 dotnet.exe. Para aplicativos autônomos, a dotnet publish etapa empacota o executável para configurar o 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ária para representar a superfície pública da API da biblioteca. Eles incluem declarações para todos os membros que são significativas ao fazer referência a um assembly em ferramentas de compilação. As assembleias de referência excluem todas as implementações de membros 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 de assembly de referência. Por padrão, os assemblies de referência são gerados em uma ref subpasta do caminho intermediário (ou seja, obj/ref/). Para gerá-los sob o diretório de saída em vez disso (ou seja, bin/ref/) definido ProduceReferenceAssemblyInOutDir como true em seu projeto.

O .NET SDK 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.

Tipo de alvo

A opção de 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.
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 da Windows Store 8.x.

Nota

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

<TargetType>library</TargetType>

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

Se você criar um assembly, poderá indicar que todo ou parte do seu código é compatível com CLS com o CLSCompliantAttribute atributo.

biblioteca

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

exe

A opção exe faz com que o compilador crie um executável (EXE), aplicativo de console. 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 especificado de outra forma com a opção OutputAssembly, o nome do arquivo de saída leva o nome do arquivo de entrada que contém o ponto de entrada (método Main ou instruções de nível superior). Um e apenas um ponto de entrada é necessário nos arquivos de código-fonte que são compilados em um arquivo .exe. A opção de compilador StartupObject permite especificar qual classe contém o Main método, nos casos em que seu código tem mais de uma classe com um Main método.

módulo

Essa opção faz com que o compilador não gere um manifesto de assembly. Por padrão, o arquivo de saída criado pela compilação com essa opção terá uma extensão de .netmodule. Um arquivo que não tem um manifesto de assembly não pode ser carregado pelo tempo de execução do .NET. No entanto, tal arquivo pode ser incorporado no manifesto de assembly de um assembly com AddModules. Se mais de um módulo for criado em uma única compilação, os 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 faz referência a internal tipos em outro módulo, ambos os módulos devem ser incorporados em um manifesto de assembly, com AddModules. A criação de um módulo não é suportada no ambiente de desenvolvimento do Visual Studio.

Winexe

A opção winexe faz com que o compilador crie um executável (EXE), programa do Windows. O arquivo executável será criado com a extensão .exe. Um programa do Windows é aquele que fornece uma interface de usuário da biblioteca .NET ou com as APIs do Windows. Use exe para criar um aplicativo de console. A menos que especificado de outra forma com a opção OutputAssembly , o nome do arquivo de saída leva o nome do arquivo de entrada que contém o Main método. Um e apenas um Main método é 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 Main método, nos casos em que seu código tem mais de uma classe com um Main método.

Winmdobj

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

A configuração winmdobj sinaliza para o compilador que um módulo intermediário é necessário. O arquivo .winmdobj pode então ser alimentado através da WinMDExp ferramenta de exportação 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 usados pelo JavaScript ou C++ e pelo Tempo de Execução do Windows. A saída de um arquivo que é compilado usando a opção de 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 leva o nome do primeiro arquivo de entrada. Um Main método não é necessário.

AppContainerExe

Se você usar a opção de compilador appcontainerexe , o compilador criará um arquivo executável (.exe) do Windows que deve ser executado em um contêiner de aplicativo. Esta opção é equivalente a -target:winexe , mas foi concebida para aplicações da Loja Windows 8.x.

Para exigir que o aplicativo seja executado em um contêiner de aplicativo, essa opção define um pouco no arquivo PE (Portable Executable ). Quando esse bit é definido, ocorre um erro se o método CreateProcess tentar iniciar o arquivo executável fora de um contêiner de aplicativo. A menos que você use a opção OutputAssembly , o nome do arquivo de saída leva o nome do arquivo de entrada que contém o Main método.