Esquemas de namespace personalizados

Os tipos em uma biblioteca .NET Multi-platform App UI (.NET MAUI) podem ser referenciados em XAML declarando um namespace XML para a biblioteca, com a declaração de namespace especificando o nome do namespace CLR (Common Language Runtime) e um nome de assembly:

<ContentPage ...
             xmlns:controls="clr-namespace:MyCompany.Controls;assembly=MyCompany.Controls">
    ...
</ContentPage>

No entanto, especificar um namespace CLR e um nome de assembly em uma xmlns definição pode ser incômodo e propenso a erros. Além disso, várias declarações de namespace XML podem ser necessárias se a biblioteca contiver tipos em vários namespaces.

Uma abordagem alternativa é definir um esquema de namespace personalizado, como http://mycompany.com/schemas/controls, que mapeia para um ou mais namespaces CLR. Isso permite que uma única declaração de namespace XML faça referência a todos os tipos em um assembly, mesmo que eles estejam em namespaces diferentes. Ele também permite que uma única declaração de namespace XML faça referência a tipos em vários assemblies.

Para obter mais informações sobre namespaces XAML, consulte Namespaces XAML.

Definir um esquema de namespace personalizado

Imagine uma biblioteca que expõe alguns controles simples, como CircleButton:

namespace MyCompany.Controls
{
    public class CircleButton : Button
    {
        ...
    }
}

Todos os controles na biblioteca residem no MyCompany.Controls namespace. Esses controles podem ser expostos a um assembly de chamada por meio de um esquema de namespace personalizado.

Um esquema de namespace personalizado é definido com a XmlnsDefinitionAttribute classe, que especifica o mapeamento entre um namespace XAML e um ou mais namespaces CLR. O XmlnsDefinitionAttribute usa dois argumentos: o nome do namespace XAML e o nome do namespace CLR. O nome do namespace XAML é armazenado na propriedade e o nome do XmlnsDefinitionAttribute.XmlNamespace namespace CLR é armazenado na XmlnsDefinitionAttribute.ClrNamespace propriedade.

Observação

A XmlnsDefinitionAttribute classe também tem uma propriedade chamada AssemblyName, que pode ser opcionalmente definida como o nome do assembly. Isso só é necessário quando um namespace CLR referenciado de um está em um XmlnsDefinitionAttribute assembly externo.

O XmlnsDefinitionAttribute deve ser definido no nível de assembly no projeto que contém os namespaces CLR que serão mapeados no esquema de namespace personalizado:

using MyCompany.Controls;

[assembly: XmlnsDefinition("http://mycompany.com/schemas/controls", "MyCompany.Controls")]

Esse código cria um esquema de namespace personalizado que mapeia a http://mycompany.com/schemas/controls URL para o MyCompany.Controls namespace CLR.

Importante

Você deve instruir o vinculador a preservar os tipos no assembly que são mapeados por meio do esquema de namespace personalizado ou preservar o assembly inteiro. Para obter mais informações, consulte Preservar código.

O esquema de namespace personalizado pode ser usado para resolução de tipos em arquivos XAML.

Consumir um esquema de namespace personalizado

Para consumir tipos do esquema de namespace personalizado, o compilador XAML requer que haja uma referência de código do assembly que consome os tipos para o assembly que define os tipos. Isso pode ser feito adicionando uma classe contendo um Init método ao assembly que define os tipos que serão consumidos por meio de XAML:

namespace MyCompany.Controls
{
    public static class Controls
    {
        public static void Init()
        {
        }
    }
}

O Init método pode então ser chamado a partir do assembly que consome tipos do esquema de namespace personalizado:

using MyCompany.Controls;

namespace CustomNamespaceSchemaDemo
{
    public partial class MainPage : ContentPage
    {
        public MainPage()
        {
            Controls.Init();
            InitializeComponent();
        }
    }
}

Aviso

A falha em incluir essa referência de código resultará na incapacidade do compilador XAML de localizar o assembly que contém os tipos de esquema de namespace personalizados.

Para consumir o CircleButton controle, um namespace XAML é declarado, com a declaração de namespace especificando a URL do esquema de namespace personalizado:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:controls="http://mycompany.com/schemas/controls"
             x:Class="CustomNamespaceSchemaDemo.MainPage">
    <StackLayout>
        ...
        <controls:CircleButton Text="+"
                               BackgroundColor="Fuchsia"
                               BorderColor="Black"
                               CircleDiameter="100" />
        <controls:CircleButton Text="-"
                               BackgroundColor="Teal"
                               BorderColor="Silver"
                               CircleDiameter="70" />
        ...
    </StackLayout>
</ContentPage>

CircleButton As instâncias podem ser adicionadas ContentPage ao declarando-as com o prefixo de controls namespace.

Para localizar os tipos de esquema de namespace personalizados, o .NET MAUI pesquisará instâncias de assemblies XmlnsDefinitionAttribute referenciados. Se o atributo de um elemento em um arquivo XAML corresponder ao valor da XmlNamespace propriedade em um XmlnsDefinitionAttribute, o .NET MAUI tentará usar o xmlns XmlnsDefinitionAttribute.ClrNamespace valor da propriedade para resolução do tipo. Se a resolução de tipo falhar, o .NET MAUI continuará a tentar a resolução de tipo com base em quaisquer instâncias correspondentes XmlnsDefinitionAttribute adicionais.

O resultado é que duas CircleButton instâncias são exibidas: