Opções avançadas do compilador C#

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.

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

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.

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.

<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.

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:
  • -target:appcontainerexe
  • -target:winmdobj
  • -platform:arm
• 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