Associar uma aplicação .NET MAUI Mac Catalyst

Quando constrói a sua aplicação, a .NET Multi-platform App UI (.NET MAUI) pode usar um linker chamado ILLink para reduzir o tamanho total da aplicação. ILLink reduz o tamanho analisando o código intermédio produzido pelo compilador. Ele remove métodos, propriedades, campos, eventos, estruturas e classes não utilizados para produzir um aplicativo que contém apenas dependências de código e assembly necessárias para executar o aplicativo.

Comportamento dos ligadores

O linker suporta três modos para aplicações .NET MAUI no iOS e Mac Catalyst:

• Não criar ligação. Desabilitar a ligação garante que as assembleias não são modificadas.
• Adicionar apenas os assemblies do SDK. Neste modo, o linker deixa as suas assembleias intocadas e reduz o tamanho das assembleias do SDK ao remover tipos e membros que a sua aplicação não utiliza.
• Liga todas as assembleias. Quando liga todas as assemblies, o linker realiza otimizações adicionais para tornar a sua aplicação o mais reduzida possível. Modifica o código intermédio do seu código-fonte, o que pode quebrar a sua aplicação se usar funcionalidades usando uma abordagem que a análise estática do linker não consegue detetar. Nestes casos, pode ser necessário fazer ajustes ao seu código-fonte para que a sua aplicação funcione corretamente.

O comportamento do linker pode ser configurado para cada configuração de compilação da sua aplicação.

Advertência

Ativar o linker para a configuração de depuração da sua aplicação poderá afetar a sua experiência de depuração, pois pode remover acessores de propriedades que permitem inspecionar o estado dos seus objetos.

Para configurar o comportamento dos linkers no Visual Studio Code, deve adicionar a $(MtouchLink) propriedade de construção a um grupo de propriedades no ficheiro .csproj da sua aplicação. Esta propriedade de construção deve ser definida para None, SdkOnly, ou Full:

<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Debug|net8.0-maccatalyst|AnyCPU'">
  <MtouchLink>SdkOnly</MtouchLink>
</PropertyGroup>

Em alternativa, pode especificar o comportamento do linker através da CLI ao construir e publicar a sua aplicação. Para mais informações, consulte Publicar uma aplicação .NET MAUI para Mac Catalyst.

Importante

A $(MtouchLink) propriedade de build pode ser definida separadamente para cada configuração de build da tua app.

Preservar código

Quando usas a ferramenta de limpeza de código, por vezes, esta remove código que poderias ter chamado dinamicamente, mesmo que de forma indireta. Pode instruir a ferramenta de otimização a preservar os membros, anotando-os com o atributo DynamicDependency. Este atributo pode ser usado para expressar uma dependência de um tipo e subconjunto de membros, ou de membros específicos.

Importante

Todos os membros da BCL que não possam ser estaticamente determinados como usados pela aplicação estão sujeitos a serem removidos.

O DynamicDependency atributo pode ser aplicado a construtores, corpos e métodos:

[DynamicDependency("Helper", "MyType", "MyAssembly")]
static void RunHelper()
{
    var helper = Assembly.Load("MyAssembly").GetType("MyType").GetMethod("Helper");
    helper.Invoke(null, null);
}

Neste exemplo, o DynamicDependency garante que o Helper método é mantido. Sem o atributo, o corte removeria Helper de MyAssembly ou removeria MyAssembly completamente se não for referenciado em nenhum outro lugar.

O atributo especifica o membro a manter pelo atributo string ou pelo atributo DynamicallyAccessedMembers. O tipo e o assembly estão implícitos no contexto do atributo, ou estão explicitamente especificados no próprio atributo (por Type, ou por strings para o nome do tipo e do assembly).

As cadeias de tipo e membro utilizam uma variação do formato da ID de comentário da documentação do C#, sem incluir o prefixo do membro. A string membro não deve incluir o nome do tipo declarante, podendo omitir parâmetros para manter todos os membros do nome especificado. Os seguintes exemplos mostram usos válidos:

[DynamicDependency("Method()")]
[DynamicDependency("Method(System,Boolean,System.String)")]
[DynamicDependency("MethodOnDifferentType()", typeof(ContainingType))]
[DynamicDependency("MemberName")]
[DynamicDependency("MemberOnUnreferencedAssembly", "ContainingType", "UnreferencedAssembly")]
[DynamicDependency("MemberName", "Namespace.ContainingType.NestedType", "Assembly")]
// generics
[DynamicDependency("GenericMethodName``1")]
[DynamicDependency("GenericMethod``2(``0,``1)")]
[DynamicDependency("MethodWithGenericParameterTypes(System.Collections.Generic.List{System.String})")]
[DynamicDependency("MethodOnGenericType(`0)", "GenericType`1", "UnreferencedAssembly")]
[DynamicDependency("MethodOnGenericType(`0)", typeof(GenericType<>))]

Preservar conjuntos

É possível especificar conjuntos que devem ser excluídos do processo de apara, permitindo que outros conjuntos sejam aparados. Esta abordagem pode ser útil quando não consegues usar facilmente o DynamicDependency atributo ou não controlas o código que está a ser cortado.

Quando corta todas as assembleias, podes dizer ao trimmer para saltar uma montagem definindo um TrimmerRootAssembly item MSBuild no ficheiro do projeto:

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

Observação

A .dll extensão não é necessária ao definir a TrimmerRootAssembly propriedade MSBuild.

Se o aparador omite uma montagem, é considerado fixo, o que significa que este e todas as suas dependências estaticamente reconhecidas são mantidos. Pode ignorar assemblies adicionais ao adicionar mais propriedades do MSBuild ao arquivo <ItemGroup>.

Preservar assembleias, tipos e membros

Pode passar ao trimmer um ficheiro de descrição XML que especifica quais os conjuntos, tipos e membros que devem ser mantidos.

Para excluir um membro do processo de corte ao cortar todas as assembleias, defina o TrimmerRootDescriptor item MSBuild no ficheiro do projeto para o ficheiro XML que define os membros a excluir:

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

O ficheiro XML utiliza o formato descritor trimmer para definir quais membros excluir:

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

Neste exemplo, o ficheiro XML especifica um método que é acedido dinamicamente pela aplicação, que é excluído do corte.

Quando um assembly, tipo ou membro está listado no XML, a ação padrão é a preservação, o que significa que, independentemente de a ferramenta de otimização achar que é usado ou não, é preservado na saída.

Observação

As etiquetas de preservação são ambíguas. Se não fornecer o próximo nível de detalhe, isso incluirá todas as crianças. Se um conjunto for listado sem quaisquer tipos, então todos os tipos e membros do conjunto serão preservados.

Marque uma montagem como segura para remoção de componentes

Se tiver uma biblioteca no seu projeto ou for um desenvolvedor de uma biblioteca reutilizável e quiser que o trimmer trate o seu conjunto como trimmável, pode indicar que o assembly é seguro para trim adicionando a propriedade IsTrimmable MSBuild ao ficheiro do projeto para o assembly.

<PropertyGroup>
    <IsTrimmable>true</IsTrimmable>
</PropertyGroup>

Isto marca a sua montagem como "aparável" e permite avisos de corte para esse projeto. Ser "trimmable" significa que o seu conjunto é considerado compatível com corte e não deve ter avisos de corte quando o conjunto for compilado. Quando usado numa aplicação cortada, os elementos não utilizados do conjunto são removidos na saída final.

Ao usar a implementação Native AOT em .NET 9+, definir a propriedade MSBuild IsAotCompatible para true também atribui um valor true à propriedade IsTrimmable e ativa propriedades adicionais de build do analisador AOT. Para mais informações sobre analisadores AOT, veja analisadores de compatibilidade AOT. Para mais informações sobre a implementação Native AOT para .NET MAUI, consulte Deployment Native AOT.

Definir a IsTrimmable propriedade MSBuild como true no ficheiro do projeto insere o AssemblyMetadata atributo na sua assembleia:

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

Em alternativa, podes adicionar o AssemblyMetadata atributo à tua assembly sem teres adicionado a IsTrimmable propriedade MSBuild ao ficheiro do projeto da tua assembly.

Observação

Se a IsTrimmable propriedade MSBuild for definida para um assembly, isto tem precedência sobre o AssemblyMetadata("IsTrimmable", "True") atributo. Isto permite-lhe escolher incluir um assembly no processo de trimagem, mesmo que não tenha o atributo, ou desativar a trimagem de um assembly que tenha o atributo.

Suprimir avisos de análise

Quando o otimizador está ativado, remove IL que não é alcançável de forma estática. Aplicações que usam reflexão ou outros padrões que criam dependências dinâmicas podem acabar por falhar como resultado. Para alertar sobre tais padrões, ao marcar uma assembly como trim safe, os autores da biblioteca devem definir a SuppressTrimAnalysisWarnings propriedade MSBuild como false:

<PropertyGroup>
  <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>
</PropertyGroup>

Não suprimir os avisos de análise de trim incluirá avisos sobre toda a aplicação, incluindo o seu próprio código, código da biblioteca e código do SDK.

Mostrar avisos detalhados

A análise de trim produz, no máximo, um aviso para cada conjunto proveniente de um PackageReference, indicando que os componentes internos do conjunto não são compatíveis com o trimming. Como autor de biblioteca, ao marcar uma assembly como trim safe, deve ativar avisos individuais para todas as assemblies definindo a TrimmerSingleWarn propriedade MSBuild para false:

<PropertyGroup>
  <TrimmerSingleWarn>false</TrimmerSingleWarn>
</PropertyGroup>

Esta configuração mostra todos os avisos detalhados, em vez de os comprimir para um único aviso por montagem.