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
.
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 o PathMap impedirá que os pontos de interrupção funcionem nos builds de depuração locais. 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:
- O caminho de origem é substituído por um argumento quando o CallerFilePathAttribute é aplicado a um parâmetro opcional.
- O caminho de origem é inserido em um arquivo PDB.
- 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:
- Diretório de trabalho atual.
- O diretório de sistema do Common Language Runtime.
- Diretórios especificados por AdditionalLibPaths.
- 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:
- Qualquer diagnóstico de membro inacessível inclui seu assembly de origem, se diferente do assembly atual.
- O compilador imprime a identidade do assembly do projeto que está sendo compilado, o nome do assembly e a chave pública.
- Para cada referência passada para o compilador, ele imprime;
- A identidade do assembly da referência
- Se a referência concede
InternalsVisibleTo
ao projeto atual - O nome e todas as chaves públicas de todos os assemblies concedidos
InternalsVisibleTo
deste assembly