Compartilhar via

Opções avançadas do compilador C#

  • Artigo

As opções a seguir dão suporte a cenários avançados. A nova sintaxe MSBuild é mostrada em Negrito. A sintaxe mais antiga csc.exe é mostrada em code style.

  • MainEntryPoint, StartupObject / -main: especifique o tipo que contém o ponto de entrada.
  • PdbFile / -pdb: especifique o nome do arquivo de informações de depuração.
  • PathMap / -pathmap: especifique um mapeamento para os nomes do caminho de origem gerados pelo compilador.
  • ApplicationConfiguration / -appconfig: especifique um arquivo de configuração de aplicativo que contenha configurações de associação de assembly.
  • AdditionalLibPaths / -lib: especifique diretórios adicionais para pesquisar por referências.
  • GenerateFullPaths / -fullpath: o compilador gera caminhos totalmente qualificados.
  • PreferredUILang / -preferreduilang: especifique o nome do idioma de saída preferencial.
  • BaseAddress / -baseaddress: especifique o endereço básico para criação da biblioteca.
  • ChecksumAlgorithm / -checksumalgorithm: especifique o algoritmo para calcular a soma de verificação do arquivo de origem armazenada no PDB.
  • CodePage / -codepage: especifique a página de código a ser usada ao abrir arquivos de origem.
  • Utf8Output / -utf8output: gere mensagens do compilador em codificação UTF-8.
  • FileAlignment / -filealign: especifique o alinhamento usado em seções de arquivo de saída.
  • ErrorEndLocation / -errorendlocation: coluna e linha de saída do local final de cada erro.
  • NoStandardLib / -nostdlib: não faça referência à biblioteca padrão mscorlib.dll.
  • SubsystemVersion / -subsystemversion: especifique a versão do subsistema deste assembly.
  • ModuleAssemblyName / -moduleassemblyname: especifique o nome do assembly do qual esse módulo fará parte.
  • ReportIVTs / -reportivts: produz informações adicionais para informações sobre System.Runtime.CompilerServices.InternalsVisibleToAttribute.

Você adiciona qualquer uma dessas opções em um elemento <PropertyGroup> em seu arquivo *.csproj:

<PropertyGroup>
    <StartupObject>...</StartupObject>
    ...
</PropertyGroup>

MainEntryPoint ou StartupObject

Esta opção especifica a classe que contém o ponto de entrada para o programa, se mais de uma classe contiver o método Main.

<StartupObject>MyNamespace.Program</StartupObject>

ou

<MainEntryPoint>MyNamespace.Program</MainEntryPoint>

Em que Program é o tipo que contém o método Main. O nome de classe informado deve ser totalmente qualificado. Ele deve incluir o namespace completo que contém a classe, seguido do nome de classe. Por exemplo, quando o método Main é localizado dentro da classe Program no namespace MyApplication.Core, a opção do compilador deve ser -main:MyApplication.Core.Program. Se a sua compilação incluir mais de um tipo com o método Main, você poderá especificar qual tipo contém o método Main.

Observação

Essa opção não pode ser usada para um projeto que inclua instruções de nível superior, mesmo que esse projeto contenha um ou mais métodos Main.

PdbFile

A opção do compilador PdbFile especifica o nome e o local do arquivo de símbolos de depuração. O valor filename especifica o nome e o local do arquivo de símbolos de depuração.

<PdbFile>filename</PdbFile>

Quando você especifica DebugType, o compilador cria um arquivo .pdb no mesmo diretório onde o compilador cria o arquivo de saída (.exe ou .dll). O arquivo .pdb tem o mesmo nome de arquivo de base que o arquivo de saída. PdbFile permite especificar um nome de arquivo não padrão e um local para o arquivo .pdb. Essa opção do compilador não pode ser definida no ambiente de desenvolvimento do Visual Studio, nem pode ser alterada programaticamente.

PathMap

Observação

Especificar PathMap impede que os pontos de interrupção funcionem em builds de depuração local. Defina o PathMap apenas para a produção ou para os builds de integração contínua.

A opção do compilador PathMap especifica como mapear caminhos físicos para os nomes de caminho de origem emitidos pelo compilador. Essa opção mapeia cada caminho físico no computador em que o compilador é executado para um caminho correspondente que deve ser gravado nos arquivos de saída. No exemplo a seguir, path1 é o caminho completo para os arquivos de origem no ambiente atual e sourcePath1 é o caminho de origem substituído para path1 qualquer arquivo de saída. Para especificar vários caminhos de origem mapeados, separe-os com uma vírgula.

<PathMap>path1=sourcePath1,path2=sourcePath2</PathMap>

O compilador grava o caminho de origem em sua saída pelos seguintes motivos:

  1. O caminho de origem é substituído por um argumento quando o CallerFilePathAttribute é aplicado a um parâmetro opcional.
  2. O caminho de origem é inserido em um arquivo PDB.
  3. O caminho do arquivo PDB é inserido em um arquivo PE (executável portátil).

ApplicationConfiguration

A opção do compilador ApplicationConfigutation permite que um aplicativo C# especifique o local de um arquivo (app.config) de configuração de aplicativo de assembly para o CLR (Common Language Runtime) em tempo de associação do assembly.

<ApplicationConfiguration>file</ApplicationConfiguration>

Em que file é o arquivo de configuração de aplicativo que contém as configurações de associação de assembly. Uma aplicação do ApplicationConfiguration é para cenários avançados em que um assembly precisa referenciar, ao mesmo temo, a versão do .NET Framework e a versão do .NET Framework para Silverlight de um assembly de referência específico. Por exemplo, um designer XAML gravado no Windows Presentation Foundation (WPF) pode ter que referenciar a Área de Trabalho do WPF, para a interface do usuário do designer e o subconjunto do WPF incluído no Silverlight. O mesmo assembly do designer deve acessar ambos os assemblies. Por padrão, as referências separadas causam um erro do compilador, pois a associação de assembly considera os dois assemblies equivalentes. A opção do compilador ApplicationConfiguration permite a especificação do local de um arquivo app.config que desabilita o comportamento padrão por meio de uma marcação <supportPortability>, conforme mostrado no exemplo a seguir.

<supportPortability PKT="7cec85d7bea7798e" enable="false"/>

O compilador passa o local do arquivo para a lógica de associação de assembly do CLR.

Observação

Para usar o arquivo app.config que já está definido no projeto, adicione a marcação de propriedade <UseAppConfigForCompiler> ao arquivo .csproj e defina o valor dele como true. Para especificar um arquivo app.config diferente, adicione a marca de propriedade <AppConfigForCompiler> e defina seu valor para o local do arquivo.

O exemplo a seguir mostra um arquivo app.config que habilita um aplicativo a referenciar as implementações do .NET Framework e do .NET Framework para Silverlight de qualquer assembly do .NET Framework que exista em ambas as implementações. A opção do compilador ApplicationConfiguration especifica o local desse arquivo app.config.

<configuration>
  <runtime>
    <assemblyBinding>
      <supportPortability PKT="7cec85d7bea7798e" enable="false"/>
      <supportPortability PKT="31bf3856ad364e35" enable="false"/>
    </assemblyBinding>
  </runtime>
</configuration>

AdditionalLibPaths

A opção AdditionalLibPaths especifica o local dos assemblies referenciados com a opção References.

<AdditionalLibPaths>dir1[,dir2]</AdditionalLibPaths>

Em que dir1 é um diretório para o compilador examinar se um assembly referenciado não for encontrado no diretório de trabalho atual (o diretório do qual você está invocando o compilador) ou no diretório de sistema do Common Language Runtime. dir2 é um ou mais diretórios adicionais a serem pesquisados para as referências de assembly. Separe os nomes de diretório com vírgula e não use espaço em branco entre eles. O compilador pesquisa referências de assembly que não são totalmente qualificadas na seguinte ordem:

  1. Diretório de trabalho atual.
  2. O diretório de sistema do Common Language Runtime.
  3. Diretórios especificados por AdditionalLibPaths.
  4. Diretórios especificados pela variável de ambiente LIB.

Use Reference para especificar uma referência de assembly. AdditionalLibPaths é aditivo. Especificá-lo mais de uma vez o acrescenta aos valores anteriores. Como o caminho para o assembly dependente não é especificado no manifesto do assembly, o aplicativo vai encontrar e usar o assembly no cache de assembly global. O compilador que faz referência ao assembly não implica que o Common Language Runtime possa localizar e carregar o assembly em tempo de execução. Consulte Como o tempo de execução localiza assemblies para obter detalhes sobre como o runtime pesquisa assemblies referenciados.

GenerateFullPaths

A opção GenerateFullPaths faz com que o compilador especifique o caminho completo para o arquivo ao listar erros de compilação e avisos.

<GenerateFullPaths>true</GenerateFullPaths>

Por padrão, erros e avisos oriundos da compilação especificam o nome do arquivo no qual o erro foi encontrado. A opção GenerateFullPaths faz com que o compilador especifique o caminho completo para o arquivo. Essa opção do compilador não está disponível no Visual Studio e não pode ser alterada programaticamente.

PreferredUILang

Usando a opção do compilador PreferredUILang, é possível especificar o idioma em que o compilador C# exibe as saídas, como as mensagens de erro.

<PreferredUILang>language</PreferredUILang>

Em que language é o nome do idioma a ser usado na saída do compilador. É possível usar a opção do compilador PreferredUILang para especificar o idioma que você deseja que o compilador C# use nas mensagens de erro e em outras saídas da linha de comando. Se o pacote de idiomas não estiver instalado, será usada a configuração de idioma do sistema operacional no lugar.

BaseAddress

A opção BaseAddress permite especificar o endereço básico preferido para carregar a DLL. Para obter mais informações sobre quando e por que usar essa opção, consulte o Blog do Larry Osterman.

<BaseAddress>address</BaseAddress>

Em que address é o endereço básico da DLL. Esse endereço pode ser especificado como um número decimal, hexadecimal ou octal. O endereço básico padrão da DLL é definido pelo Common Language Runtime do .NET. A palavra de menor relevância neste endereço será abreviada. Por exemplo, se você especificar 0x11110001, ele é arredondado para 0x11110000. Para concluir o processo de assinatura de uma DLL, use SN.EXE com a opção -R.

ChecksumAlgorithm

Essa opção controla o algoritmo de soma de verificação que usamos para codificar os arquivos de origem no PDB.

<ChecksumAlgorithm>algorithm</ChecksumAlgorithm>

algorithm deve ser SHA1 (padrão) ou SHA256.

CodePage

Esta opção especifica qual página de código deve ser usada durante a compilação caso a página necessária não seja a página de código padrão atual do sistema.

<CodePage>id</CodePage>

Onde id é a ID da página de código a ser usada para todos os arquivos de código-fonte na compilação. O compilador primeiro tenta interpretar todos os arquivos de origem como UTF-8. Se os seus arquivos de código-fonte estiverem em uma codificação diferente de UTF-8 e usarem caracteres diferentes de ASCII de 7 bits, use a opção CodePage para especificar qual página de código deve ser usada. CodePage se aplica a todos os arquivos de código-fonte da sua compilação. Consulte GetCPInfo para obter informações sobre como localizar quais páginas de código têm suporte do sistema.

Utf8Output

A opção Utf8Output exibe a saída do compilador usando a codificação UTF-8.

<Utf8Output>true</Utf8Output>

Em algumas configurações internacionais, a saída do compilador não pode ser exibida corretamente no console. Use Utf8Output e redirecione a saída do compilador para um arquivo.

FileAlignment

A opção FileAlignment permite que você especifique o tamanho das seções em seu arquivo de saída. Os valores válidos são 512, 1024, 2048, 4096 e 8192. Esses valores estão em bytes.

<FileAlignment>number</FileAlignment>

Defina a opção FileAlignment na página Avançado das propriedades de Compilação para seu projeto no Visual Studio. Cada seção é alinhada em um limite que é um múltiplo do valor FileAlignment. Não há padrão fixo. Se FileAlignment não é especificado, o Common Language Runtime escolhe um padrão em tempo de compilação. Ao especificar o tamanho da seção, você afeta o tamanho do arquivo de saída. Modificar o tamanho da seção pode ser útil para programas executados em dispositivos menores. Use DUMPBIN para ver informações sobre as seções em seu arquivo de saída.

ErrorEndLocation

Instrui o compilador para emitir como saída a linha e a coluna do local final de cada erro.

<ErrorEndLocation>true</ErrorEndLocation>

Por padrão, o compilador grava o local inicial na origem para todos os erros e avisos. Quando essa opção é definida como true, o compilador grava o local inicial e final de cada erro e aviso.

NoStandardLib

NoStandardLib impede a importação de mscorlib.dll, que define todo o namespace System.

<NoStandardLib>true</NoStandardLib>

Use essa opção se desejar definir ou criar seus próprios objetos e namespace System. Se você não especificar NoStandardLib, o mscorlib.dll será importado no programa (o mesmo que especificar <NoStandardLib>false</NoStandardLib>).

SubsystemVersion

Especifica a versão mínima do subsistema em que é executado o arquivo executável. Normalmente, essa opção garante que o arquivo executável possa usar recursos de segurança que não estão disponíveis em versões mais antigas do Windows.

Observação

Para especificar o subsistema em si, use a opção do compilador TargetType.

<SubsystemVersion>major.minor</SubsystemVersion>

major.minor especifica a versão mínima obrigatória do subsistema, conforme expresso em uma notação de ponto para versões principais e secundárias. Por exemplo, você pode especificar que um aplicativo não pode ser executado em um sistema operacional mais antigo que o Windows 7. Defina o valor dessa opção como 6.01, conforme descreverá a tabela mais adiante neste artigo. Você especifica os valores de major e minor como inteiros. Zeros à esquerda na versão minor não alteram a versão, mas zeros à direita alteram. Por exemplo, 6.1 e 6.01 se referem à mesma versão, mas 6.10 se refere a uma versão diferente. É recomendável expressar a versão secundária como dois dígitos para evitar confusão.

A seguinte tabela lista as versões de subsistema comuns do Windows.

Versão do Windows Versão do subsistema
Windows Server 2003 5,02
Windows Vista 6,00
Windows 7 6.01
Windows Server 2008 6.01
Windows 8 6.02

O valor padrão da opção do compilador SubsystemVersion depende das condições da seguinte lista:

  • O valor padrão é 6.02 se qualquer opção do compilador na lista a seguir for definida:
  • O valor padrão será 6.00 se você estiver usando o MSBuild, se tiver como destino o .NET Framework 4.5 e se não definiu nenhuma das opções de compilador que foram especificadas anteriormente na lista.
  • O valor padrão é 4.00 se nenhuma das condições anteriores for verdadeira.

ModuleAssemblyName

Especifica o nome de um assembly cujos tipos não públicos um .netmodule pode acessar.

<ModuleAssemblyName>assembly_name</ModuleAssemblyName>

O ModuleAssemblyName deverá ser usado ao compilar um .netmodule e quando as seguintes condições forem true:

  • O .netmodule precisa acessar tipos não públicos em um assembly existente.
  • Você sabe o nome do assembly no qual o .netmodule será compilado.
  • O assembly existente concedeu acesso de assembly amigável ao assembly em que o .netmodule será compilado.

Para obter mais informações sobre a compilação de um .netmodule, confira a opção TargetType do módulo. Para obter mais informações sobre assemblies amigos, consulte Assemblies Amigáveis.

ReportIVTs

Habilite ou desabilite informações de diagnóstico adicionais sobre System.Runtime.CompilerServices.InternalsVisibleToAttribute encontradas durante a compilação:

<ReportIVTs>true</ReportIVTs>

Os diagnósticos serão habilitados se o conteúdo do elemento for true e desabilitados se o conteúdo for false ou não estiver presente.

ReportIVTs relata as seguintes informações quando habilitado:

  1. Qualquer diagnóstico de membro inacessível inclui seu assembly de origem, se diferente do assembly atual.
  2. O compilador imprime a identidade do assembly do projeto que está sendo compilado, o nome do assembly e a chave pública.
  3. Para cada referência passada para o compilador, ele imprime;
    1. A identidade do assembly da referência
    2. Se a referência concede InternalsVisibleTo ao projeto atual
    3. O nome e todas as chaves públicas de todos os assemblies concedidos InternalsVisibleTo deste assembly