Compartilhar via

ExperimentalAttribute

  • Artigo

Nota

Este artigo é uma especificação de recurso. A especificação serve como o documento de design para o recurso. Ele inclui alterações de especificação propostas, juntamente com as informações necessárias durante o design e o desenvolvimento do recurso. Esses artigos são publicados até que as alterações de especificação propostas sejam finalizadas e incorporadas na especificação ECMA atual.

Pode haver algumas discrepâncias entre a especificação do recurso e a implementação concluída. Essas diferenças são capturadas nas notas pertinentes da reunião de design de idioma (LDM).

Você pode aprender mais sobre o processo de adoção de especletos de recursos no padrão da linguagem C# no artigo sobre as especificações .

Relatar avisos para referências a tipos e membros marcados com System.Diagnostics.CodeAnalysis.ExperimentalAttribute.

namespace System.Diagnostics.CodeAnalysis
{
    [AttributeUsage(AttributeTargets.Assembly |
                    AttributeTargets.Module |
                    AttributeTargets.Class |
                    AttributeTargets.Struct |
                    AttributeTargets.Enum |
                    AttributeTargets.Constructor |
                    AttributeTargets.Method |
                    AttributeTargets.Property |
                    AttributeTargets.Field |
                    AttributeTargets.Event |
                    AttributeTargets.Interface |
                    AttributeTargets.Delegate, Inherited = false)]
    public sealed class ExperimentalAttribute : Attribute
    {
        public ExperimentalAttribute(string diagnosticId)
        {
            DiagnosticId = diagnosticId;
        }

        public string DiagnosticId { get; }
        public string? UrlFormat { get; set; }
        public string? Message { get; set; }
    }
}

Diagnóstico relatado

Embora o diagnóstico seja tecnicamente um aviso, para que o compilador permita suprimi-lo, ele é tratado como um erro para fins de relatório. Isso fará com que o build falhe se o diagnóstico não for suprimido.

O diagnóstico é emitido para qualquer referência a um tipo ou membro que seja:

  • tipos marcados com o atributo,
  • em um assembly ou módulo marcado com o atributo,

exceto quando a referência ocorre em membros [Experimental], quando ela é automaticamente suprimida.

Também é possível suprimir o diagnóstico por meios usuais, como uma opção de compilador explícita ou #pragma.
Por exemplo, se a API estiver marcada com [Experimental("DiagID")] ou [Experimental("DiagID", UrlFormat = "https://example.org/{0}")], o diagnóstico poderá ser suprimido com #pragma warning disable DiagID.

Um erro será gerado se a ID de diagnóstico fornecida ao atributo experimental não for um identificador C# válido.

Se um valor para a propriedade Message não for fornecido, a mensagem de diagnóstico é específica, onde '{0}' é o nome do membro ou o tipo totalmente qualificado.

'{0}' is for evaluation purposes only and is subject to change or removal in future updates.

Se for fornecido um valor para a propriedade Message, a mensagem de diagnóstico é específica, onde '{0}' é o nome do membro ou o tipo totalmente qualificado e '{1}' é o Message.

'{0}' is for evaluation purposes only and is subject to change or removal in future updates: '{1}'.

O atributo não é herdado de tipos base ou membros substituídos.

ObsoleteAttribute e DeprecatedAttribute

Avisos para [Experimental] são relatados nos membros [Obsolete] ou [Deprecated].
Avisos e erros de [Obsolete] e [Deprecated] são reportados nos membros [Experimental].
Mas avisos e erros para [Obsolete] e [Deprecated] são relatados em vez de [Experimental] se houver vários atributos.