Opções de corte

As propriedades e os itens do MSBuild descritos neste artigo influenciam o comportamento de implantações cortadas e independentes. Algumas das opções mencionam ILLink, que é o nome da ferramenta subjacente que implementa o corte. Para obter mais informações sobre a ferramenta subjacente, consulte a documentação do Trimmer.

O corte com PublishTrimmed foi introduzido no .NET Core 3.0. As outras opções estão disponíveis no .NET 5 e versões posteriores.

Ativar corte

• <PublishTrimmed>true</PublishTrimmed>

  Habilite o corte durante a publicação. Essa configuração também desativa recursos incompatíveis com trim e permite a análise de trim durante a compilação. No .NET 8 e aplicativos posteriores, essa configuração também habilita a vinculação de configuração e os geradores de origem de delegados de solicitação.

Nota

Se você especificar o corte como habilitado na linha de comando, sua experiência de depuração será diferente e você poderá encontrar bugs adicionais no produto final.

Coloque essa configuração no arquivo de projeto para garantir que a configuração se aplique durante dotnet buildo , não apenas dotnet publish.

Essa configuração permite cortar e cortar todos os assemblies por padrão. No .NET 6, somente assemblies que optaram por cortar via [AssemblyMetadata("IsTrimmable", "True")] (adicionados em projetos que definiram <IsTrimmable>true</IsTrimmable>) foram cortados por padrão. Você pode retornar ao comportamento anterior usando <TrimMode>partial</TrimMode>.

Essa configuração corta todos os assemblies que foram configurados para corte. Com Microsoft.NET.Sdk o .NET 6, isso inclui todos os assemblies com [AssemblyMetadata("IsTrimmable", "True")], que é o caso dos assemblies de tempo de execução do .NET. No .NET 5, assemblies do pacote de tempo de execução netcoreapp são configurados para corte por meio <IsTrimmable> de metadados MSBuild. Outros SDKs podem definir padrões diferentes.

Essa configuração também habilita o analisador Roslyn de compatibilidade de corte e desabilita recursos que são incompatíveis com o corte.

Granularidade de corte

Use a TrimMode propriedade para definir a granularidade de corte como um partial ou full. A configuração padrão para aplicativos de console (e, a partir do .NET 8, aplicativos Web SDK) é full:

<TrimMode>full</TrimMode>

Para cortar apenas assemblies que optaram por cortar, defina a propriedade como partial:

<TrimMode>partial</TrimMode>

Se você alterar o modo de corte para partial, você pode optar por assemblies individuais para cortar usando um <TrimmableAssembly> item MSBuild.

<ItemGroup>
  <TrimmableAssembly Include="MyAssembly" />
</ItemGroup>

Isso é equivalente à configuração [AssemblyMetadata("IsTrimmable", "True")] ao construir a montagem.

As configurações de granularidade a seguir controlam o quão agressivamente a IL não utilizada é descartada. Isso pode ser definido como uma propriedade que afeta todos os assemblies de entrada do aparador ou como metadados em um assembly individual, que substitui a configuração da propriedade.

• <TrimMode>link</TrimMode>

  Habilite o corte no nível de membro, que remove membros não utilizados dos tipos. Este é o padrão no .NET 6+.

• <TrimMode>copyused</TrimMode>

  Habilite o corte no nível da montagem, que mantém um conjunto inteiro se qualquer parte dele for usada (de uma forma compreendida estaticamente).

Assemblies com <IsTrimmable>true</IsTrimmable> metadados, mas não explícitos TrimMode , usarão o global TrimMode. O padrão TrimMode para Microsoft.NET.Sdk está link no .NET 6+ e copyused em versões anteriores.

Cortar montagens adicionais

No .NET 6+, PublishTrimmed corta assemblies com o seguinte atributo de nível de assembly:

[AssemblyMetadata("IsTrimmable", "True")]

As bibliotecas de estrutura têm esse atributo. No .NET 6+, você também pode optar por cortar uma biblioteca sem esse atributo, especificando o assembly pelo nome (sem a .dll extensão).

Configurações de corte para montagens individuais

Ao publicar um aplicativo cortado, o SDK calcula uma ItemGroup chamada ManagedAssemblyToLink que representa o conjunto de arquivos a serem processados para corte. ManagedAssemblyToLink pode ter metadados que controlam o comportamento de corte por montagem. Para definir esses metadados, crie um destino que seja executado antes do destino interno PrepareForILLink . O exemplo a seguir mostra como habilitar o corte de MyAssembly.

<Target Name="ConfigureTrimming"
        BeforeTargets="PrepareForILLink">
  <ItemGroup>
    <ManagedAssemblyToLink Condition="'%(Filename)' == 'MyAssembly'">
      <IsTrimmable>true</IsTrimmable>
    </ManagedAssemblyToLink>
  </ItemGroup>
</Target>

Você também pode usar esse destino para substituir o comportamento de corte especificado pelo autor da biblioteca, definindo <IsTrimmable>false</IsTrimmable> um assembly com [AssemblyMetadata("IsTrimmable", "True"]).

Não adicione ou remova itens do ManagedAssemblyToLink, porque o SDK calcula esse conjunto durante a publicação e espera que ele não seja alterado. Os metadados suportados são:

• <IsTrimmable>true</IsTrimmable>

  Controle se o conjunto dado está aparado.

• <TrimMode>copyused</TrimMode> ou <TrimMode>link</TrimMode>

  Controle a granularidade de corte deste conjunto. Esses metadados têm precedência sobre o .TrimMode A configuração TrimMode em uma montagem implica <IsTrimmable>true</IsTrimmable>.

• <TrimmerSingleWarn>True</TrimmerSingleWarn>

  Controle se deseja mostrar avisos únicos para este assembly.

Montagens raiz

Se um assembly não é cortado, ele é considerado "enraizado", o que significa que ele e todas as suas dependências estaticamente compreendidas serão mantidas. Assemblies adicionais podem ser "enraizados" pelo nome (sem a .dll extensão):

<ItemGroup>
  <TrimmerRootAssembly Include="MyAssembly" />
</ItemGroup>

Descritores raiz

Outra maneira de especificar raízes para análise é usando um arquivo XML que usa o formato de descritor de trimmer. Isso permite que você faça root em membros específicos em vez de um assembly inteiro.

<ItemGroup>
  <TrimmerRootDescriptor Include="MyRoots.xml" />
</ItemGroup>

Por exemplo, MyRoots.xml pode enraizar um método específico que é acessado dinamicamente pelo aplicativo:

<linker>
  <assembly fullname="MyAssembly">
    <type fullname="MyAssembly.MyClass">
      <method name="DynamicallyAccessedMethod" />
    </type>
  </assembly>
</linker>

Avisos de análise

• <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

  Habilite avisos de análise de corte.

O corte remove o IL que não é acessível estaticamente. Os aplicativos que usam reflexão ou outros padrões que criam dependências dinâmicas podem ser quebrados por corte. Para avisar sobre esses padrões, defina <SuppressTrimAnalysisWarnings> como false. Essa configuração exibirá avisos sobre todo o aplicativo, incluindo seu próprio código, código de biblioteca e código de estrutura.

Analisador Roslyn

A configuração PublishTrimmed no .NET 6+ também habilita um analisador Roslyn que mostra um conjunto limitado de avisos de análise. Você também pode habilitar ou desabilitar o analisador independentemente do PublishTrimmed.

• <EnableTrimAnalyzer>true</EnableTrimAnalyzer>

  Habilite um analisador Roslyn para um subconjunto de avisos de análise de corte.

Suprimir avisos

Você pode suprimir códigos de aviso individuais usando as propriedades usuais do MSBuild respeitadas pela cadeia de ferramentas, incluindo NoWarn, WarningsAsErrors, WarningsNotAsErrorse TreatWarningsAsErrors. Há uma opção adicional que controla o comportamento de aviso como erro do ILLink de forma independente:

• <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

  Não trate os avisos ILLink como erros. Isso pode ser útil para evitar transformar avisos de análise de corte em erros ao tratar avisos do compilador como erros globalmente.

Mostrar avisos detalhados

No .NET 6+, a análise de corte produz no máximo um aviso para cada montagem proveniente de um PackageReference, indicando que os internos do assembly não são compatíveis com o corte. Você também pode mostrar avisos individuais para todos os conjuntos:

• <TrimmerSingleWarn>false</TrimmerSingleWarn>

  Mostrar todos os avisos detalhados, em vez de colapsá-los para um único aviso por montagem.

Remover símbolos

Os símbolos são geralmente cortados para corresponder às montagens aparadas. Você também pode remover todos os símbolos:

• <TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

  Remova símbolos do aplicativo cortado, incluindo PDBs incorporados e arquivos PDB separados. Isso se aplica ao código do aplicativo e a quaisquer dependências que vêm com símbolos.

O SDK também torna possível desativar o suporte ao depurador usando a propriedade DebuggerSupport. Quando o suporte ao depurador está desativado, o corte remove símbolos automaticamente (TrimmerRemoveSymbols o padrão será true).

Trim recursos da biblioteca de estrutura

Várias áreas de recursos das bibliotecas de estrutura vêm com diretivas trimmer que tornam possível remover o código para recursos desativados.

Propriedade MSBuild	Description
AutoreleasePoolSupport	Quando definido como false, remove o código que cria pools de liberação automática em plataformas suportadas. false é o padrão para o SDK do .NET.
DebuggerSupport	Quando definido como false, remove o código que permite melhores experiências de depuração. Essa configuração também remove símbolos.
EnableUnsafeBinaryFormatterSerialization	Quando definido como false, remove o suporte à serialização BinaryFormatter. Para obter mais informações, consulte Os métodos de serialização BinaryFormatter estão obsoletos e a implementação BinaryFormatter na caixa de entrada foi removida e sempre lança.
EnableUnsafeUTF7Encoding	Quando definido como false, remove o código de codificação UTF-7 inseguro. Para obter mais informações, consulte Os caminhos de código UTF-7 estão obsoletos.
EventSourceSupport	Quando definido como false, remove o código e a lógica relacionados a EventSource.
HttpActivityPropagationSupport	Quando definido como false, remove o código relacionado ao suporte de diagnóstico para System.Net.Http.
InvariantGlobalization	Quando definido como true, remove o código e os dados específicos da globalização. Para obter mais informações, consulte Modo invariante.
MetadataUpdaterSupport	Quando definido como false, remove a lógica específica de atualização de metadados relacionada à recarga a quente.
MetricsSupport	Quando definido como false, remove o suporte para System.Diagnostics.Metrics instrumentação.
StackTraceSupport (.NET 8+)	Quando definido como false, remove o suporte para gerar rastreamentos de pilha (por exemplo, Environment.StackTrace ou Exception.ToString) pelo tempo de execução. A quantidade de informações removidas das cadeias de caracteres de rastreamento de pilha pode depender de outras opções de implantação. Esta opção não afeta os rastreamentos de pilha gerados por depuradores.
UseNativeHttpHandler	Quando definido como true, usa a implementação de plataforma padrão do HttpMessageHandler para Android e iOS e remove a implementação gerenciada.
UseSystemResourceKeys	Quando definido como true, remove mensagens de exceção para System.* assemblies. Quando uma exceção é lançada de um System.* assembly, a mensagem é uma ID de recurso simplificada em vez da mensagem completa.
XmlResolverIsNetworkingEnabledByDefault (.NET 8+)	Quando definido como false, remove o suporte para resolver URLs que não sejam de arquivo no System.Xml. Somente a resolução do sistema de arquivos é suportada.

Essas propriedades fazem com que o código relacionado seja cortado e também desabilitam recursos por meio do arquivo runtimeconfig . Para obter mais informações sobre essas propriedades, incluindo as opções de runtimeconfig correspondentes, consulte opções de recursos. Alguns SDKs podem ter valores padrão para essas propriedades.

Recursos do Framework desativados ao cortar

Os recursos a seguir são incompatíveis com o corte porque exigem código que não é referenciado estaticamente. Esses recursos são desativados por padrão em aplicativos cortados.

Aviso

Habilite esses recursos por sua conta e risco. É provável que quebrem aplicativos cortados sem trabalho extra para preservar o código referenciado dinamicamente.

• <BuiltInComInteropSupport>

  O suporte COM integrado está desativado.

• <CustomResourceTypesSupport>

  Não há suporte para o uso de tipos de recursos personalizados. Os caminhos de código do ResourceManager que usam reflexão para tipos de recursos personalizados são cortados.

• <EnableCppCLIHostActivation>

  A ativação do host C++/CLI está desabilitada.

• <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

  DesigntimeLicenseContextSerializer O uso da BinaryFormatter serialização está desativado.

• <StartupHookSupport>

  A execução de código antes Main com DOTNET_STARTUP_HOOKS não é suportada. Para obter mais informações, consulte Gancho de inicialização do host.