Classe FlagsAttribute (System)

Cambia visualizzazione:
ScriptFree
Riferimento a .NET Framework
Classe FlagsAttribute
Il presente articolo è stato tradotto manualmente. Per visualizzare questa pagina e contemporaneamente visualizzarne il contenuto in lingua inglese, passare alla visualizzazione semplificata.

Indica che un'enumerazione può essere gestita come un campo di bit, ovvero un insieme di flag.

Gerarchia di ereditarietà

System.Object
  System.Attribute
    System.FlagsAttribute

Spazio dei nomi:  System
Assembly:  mscorlib (in mscorlib.dll)
Sintassi

Visual Basic
<SerializableAttribute> _
<AttributeUsageAttribute(AttributeTargets.Enum, Inherited := False)> _
<ComVisibleAttribute(True)> _
Public Class FlagsAttribute _
	Inherits Attribute
C#
[SerializableAttribute]
[AttributeUsageAttribute(AttributeTargets.Enum, Inherited = false)]
[ComVisibleAttribute(true)]
public class FlagsAttribute : Attribute
Visual C++
[SerializableAttribute]
[AttributeUsageAttribute(AttributeTargets::Enum, Inherited = false)]
[ComVisibleAttribute(true)]
public ref class FlagsAttribute : public Attribute
F#
[<SerializableAttribute>]
[<AttributeUsageAttribute(AttributeTargets.Enum, Inherited = false)>]
[<ComVisibleAttribute(true)>]
type FlagsAttribute =  
    class
        inherit Attribute
    end

Il tipo FlagsAttribute espone i seguenti membri.

Costruttori

  Nome Descrizione
Metodo pubblico Supportato da XNA Framework dk06fkbc.PortableClassLibrary(it-it,VS.100).gif FlagsAttribute Inizializza una nuova istanza della classe FlagsAttribute.
In alto
Proprietà

  Nome Descrizione
Proprietà pubblica TypeId Quando è implementata in una classe derivata, ottiene un identificatore univoco della classe Attribute. (Ereditato da Attribute)
In alto
Metodi

  Nome Descrizione
Metodo pubblico Supportato da XNA Framework dk06fkbc.PortableClassLibrary(it-it,VS.100).gif Equals Infrastruttura. Restituisce un valore che indica se l'istanza è uguale a un oggetto specificato. (Ereditato da Attribute)
Metodo protetto Supportato da XNA Framework dk06fkbc.PortableClassLibrary(it-it,VS.100).gif Finalize Consente a un oggetto di provare a liberare risorse ed eseguire altre operazioni di pulitura prima che l'oggetto stesso venga recuperato dalla procedura di Garbage Collection. (Ereditato da Object)
Metodo pubblico Supportato da XNA Framework dk06fkbc.PortableClassLibrary(it-it,VS.100).gif GetHashCode Restituisce il codice hash per l'istanza. (Ereditato da Attribute)
Metodo pubblico Supportato da XNA Framework dk06fkbc.PortableClassLibrary(it-it,VS.100).gif GetType Ottiene l'oggetto Type dell'istanza corrente. (Ereditato da Object)
Metodo pubblico IsDefaultAttribute Quando è sottoposto a override in una classe derivata, indica se il valore di questa istanza è il valore predefinito della classe derivata. (Ereditato da Attribute)
Metodo pubblico Supportato da XNA Framework Match Quando è sottoposto a override in una classe derivata, restituisce un valore che indica se questa istanza equivale a un oggetto specificato. (Ereditato da Attribute)
Metodo protetto Supportato da XNA Framework dk06fkbc.PortableClassLibrary(it-it,VS.100).gif MemberwiseClone Consente di creare una copia dei riferimenti dell'oggetto Object corrente. (Ereditato da Object)
Metodo pubblico Supportato da XNA Framework dk06fkbc.PortableClassLibrary(it-it,VS.100).gif ToString Restituisce una stringa che rappresenta l'oggetto corrente. (Ereditato da Object)
In alto
Implementazioni esplicite dell'interfaccia

  Nome Descrizione
Implementazione esplicita dell'interfaccia Metodo privato _Attribute.GetIDsOfNames Esegue il mapping di un set di nomi a un set corrispondente di ID di invio. (Ereditato da Attribute)
Implementazione esplicita dell'interfaccia Metodo privato _Attribute.GetTypeInfo Recupera le informazioni sul tipo relative a un oggetto, che possono essere utilizzate per ottenere informazioni sul tipo relative a un'interfaccia. (Ereditato da Attribute)
Implementazione esplicita dell'interfaccia Metodo privato _Attribute.GetTypeInfoCount Recupera il numero delle interfacce di informazioni di tipo fornite da un oggetto (0 o 1). (Ereditato da Attribute)
Implementazione esplicita dell'interfaccia Metodo privato _Attribute.Invoke Fornisce l'accesso a proprietà e metodi esposti da un oggetto. (Ereditato da Attribute)
In alto
Note

In genere, i campi di bit vengono utilizzati per elenchi di elementi che potrebbero essere generati in modo combinato, mentre le costanti enumerate vengono generalmente utilizzate per elenchi di elementi che si escludono mutualmente. Di conseguenza, i campi di bit sono progettati per essere combinati con un'operazione OR bit per bit per generare valori senza nome, mentre le costanti enumerate non sono progettate per tale utilizzo. L'utilizzo dei campi di bit varia nei diversi linguaggi rispetto all'utilizzo delle costanti enumerate.

Attributi di FlagsAttribute

L'oggetto AttributeUsageAttribute viene applicato a questa classe e viene specificato false dalla relativa proprietà Inherited. Questo attributo può essere applicato soltanto a enumerazioni.

Indicazioni per FlagsAttribute e Enum

  • Utilizzare l'attributo personalizzato FlagsAttribute per un'enumerazione solo se è necessario eseguire un'operazione bit per bit (AND, OR, EXCLUSIVE OR) su un valore numerico.

  • Definire le costanti di enumerazione come potenze di due, ossia 1, 2, 4, 8 e così via. Questo significa che i singoli flag nelle costanti di enumerazione combinate non si sovrappongono.

  • È consigliabile creare una costante enumerata per le combinazioni di flag più comuni. Se ad esempio si utilizza un'enumerazione per le operazioni di I/O sui file che contiene le costanti enumerate Read = 1 e Write = 2, creare la costante enumerata ReadWrite = Read OR Write, che unisce i flag Read e Write. L'operazione OR bit per bit utilizzata per unire i flag costituisce una funzionalità avanzata che non dovrebbe essere richiesta per attività semplici, ma solo in determinate circostanze.

  • Prestare attenzione se si definisce un numero negativo come costante enumerata di flag, perché molte posizioni di flag potrebbero essere impostate su 1, creando confusione nel codice e favorendo gli errori.

  • Per verificare se un flag è impostato in un valore numerico, è possibile eseguire un'operazione AND bit per bit tra il valore numerico e la costante enumerata di flag, che imposta su zero tutti i bit del valore numerico che non corrispondono al flag, quindi verificare se il risultato dell'operazione è uguale alla costante enumerata di flag.

  • Utilizzare None come nome della costante enumerata di flag il cui valore è zero. Non è possibile utilizzare la costante enumerata None in un'operazione AND bit per bit per verificare un flag, perché il risultato è sempre pari a zero. È tuttavia possibile eseguire un confronto logico, non bit per bit, tra il valore numerico e la costante enumerata None per determinare se alcuni bit del valore numerico sono impostati.

    Se si crea un'enumerazione di valori anziché un'enumerazione di flag, è comunque utile creare una costante enumerata None, perché per impostazione predefinita la memoria utilizzata per l'enumerazione viene inizializzata su zero da Common Language Runtime. Di conseguenza, se non si definisce una costante il cui valore è zero, l'enumerazione conterrà un valore non valido quando verrà creata.

    Se l'applicazione deve rappresentare un caso predefinito ovvio, è consigliabile utilizzare a tale scopo una costante enumerata il cui valore è zero. Se non sono presenti casi predefiniti, è preferibile utilizzare una costante enumerata il cui valore è zero che indichi il caso non rappresentato da nessuna delle altre costanti enumerate.

  • Non definire un valore di enumerazione al solo scopo di rispecchiare lo stato dell'enumerazione stessa. Ad esempio, non definire una costante di enumerazione che si limita a contrassegnare la fine dell'enumerazione. Se è necessario determinare l'ultimo valore dell'enumerazione, controllare in modo esplicito tale valore. È inoltre possibile effettuare un controllo di intervallo della prima e dell'ultima costante enumerata se tutti i valori dell''intervallo sono validi.

  • Non specificare le costanti enumerate riservate per utilizzi futuri.

  • Quando si definisce un metodo o una proprietà che accetta una costante enumerata come valore, è consigliabile convalidare il valore perché è possibile eseguire il cast di un valore numerico sul tipo di enumerazione anche se tale valore numerico non è definito nell'enumerazione.

Esempi

Nell'esempio di codice riportato di seguito viene illustrato l'utilizzo dell'attributo FlagsAttribute e viene mostrato l'effetto sul metodo ToString dell'utilizzo diFlagsAttribute su una dichiarazione Enum.

Visual Basic

' Example of the FlagsAttribute attribute.
Imports System
Imports Microsoft.VisualBasic

Module FlagsAttributeDemo

    ' Define an Enum without FlagsAttribute.
    Enum SingleHue as Short
        Black = 0
        Red = 1
        Green = 2
        Blue = 4
    End Enum

    ' Define an Enum with FlagsAttribute.
    <FlagsAttribute( )> _
    Enum MultiHue as Short
        Black = 0
        Red = 1
        Green = 2
        Blue = 4
    End Enum

    Sub Main( )
        Console.WriteLine( _
            "This example of the FlagsAttribute attribute " & _
            vbCrLf & "generates the following output." )
        Console.WriteLine( vbCrLf & _
            "All possible combinations of values of an " & _
            vbCrLf & "Enum without FlagsAttribute:" & vbCrLf )

        ' Display all possible combinations of values.
        Dim val as Integer
        For val = 0 to 8
            Console.WriteLine( "{0,3} - {1}", _
                val, CType( val, SingleHue ).ToString( ) )
        Next val

        Console.WriteLine( vbCrLf & _
            "All possible combinations of values of an " & _
            vbCrLf & "Enum with FlagsAttribute:" & vbCrLf )

        ' Display all possible combinations of values.
        ' Also display an invalid value.
        For val = 0 to 8
            Console.WriteLine( "{0,3} - {1}", _
                val, CType( val, MultiHue ).ToString( ) )
        Next val
    End Sub 
End Module 

' This example of the FlagsAttribute attribute
' generates the following output.
' 
' All possible combinations of values of an
' Enum without FlagsAttribute:
' 
'   0 - Black
'   1 - Red
'   2 - Green
'   3 - 3
'   4 - Blue
'   5 - 5
'   6 - 6
'   7 - 7
'   8 - 8
' 
' All possible combinations of values of an
' Enum with FlagsAttribute:
' 
'   0 - Black
'   1 - Red
'   2 - Green
'   3 - Red, Green
'   4 - Blue
'   5 - Red, Blue
'   6 - Green, Blue
'   7 - Red, Green, Blue
'   8 - 8


C#

// Example of the FlagsAttribute attribute.
using System;

class FlagsAttributeDemo
{
    // Define an Enum without FlagsAttribute.
    enum SingleHue : short
    {
        Black = 0,
        Red = 1,
        Green = 2,
        Blue = 4
    };

    // Define an Enum with FlagsAttribute.
    [FlagsAttribute] 
    enum MultiHue : short
    {
        Black = 0,
        Red = 1,
        Green = 2,
        Blue = 4
    };

    static void Main( )
    {
        Console.WriteLine( 
            "This example of the FlagsAttribute attribute \n" +
            "generates the following output." );
        Console.WriteLine( 
            "\nAll possible combinations of values of an \n" +
            "Enum without FlagsAttribute:\n" );

        // Display all possible combinations of values.
        for( int val = 0; val <= 8; val++ )
            Console.WriteLine( "{0,3} - {1}", 
                val, ( (SingleHue)val ).ToString( ) );

        Console.WriteLine( 
            "\nAll possible combinations of values of an \n" +
            "Enum with FlagsAttribute:\n" );

        // Display all possible combinations of values.
        // Also display an invalid value.
        for( int val = 0; val <= 8; val++ )
            Console.WriteLine( "{0,3} - {1}", 
                val, ( (MultiHue)val ).ToString( ) );
    } 
} 

/*
This example of the FlagsAttribute attribute
generates the following output.

All possible combinations of values of an
Enum without FlagsAttribute:

  0 - Black
  1 - Red
  2 - Green
  3 - 3
  4 - Blue
  5 - 5
  6 - 6
  7 - 7
  8 - 8

All possible combinations of values of an
Enum with FlagsAttribute:

  0 - Black
  1 - Red
  2 - Green
  3 - Red, Green
  4 - Blue
  5 - Red, Blue
  6 - Green, Blue
  7 - Red, Green, Blue
  8 - 8
*/


Visual C++

// Example of the FlagsAttribute attribute.
using namespace System;

// Define an Enum without FlagsAttribute.
enum class SingleHue : short
{
   Black = 0,
   Red = 1,
   Green = 2,
   Blue = 4
};


// Define an Enum with FlagsAttribute.

[FlagsAttribute]
enum class MultiHue : short
{
   Black = 0,
   Red = 1,
   Green = 2,
   Blue = 4
};

int main()
{
   Console::WriteLine( "This example of the FlagsAttribute attribute \n"
   "generates the following output." );
   Console::WriteLine( "\nAll possible combinations of values of an \n"
   "Enum without FlagsAttribute:\n" );

   // Display all possible combinations of values.
   for ( int val = 0; val <= 8; val++ )
      Console::WriteLine( "{0,3} - {1}", val, ((SingleHue)val).ToString() );
   Console::WriteLine( "\nAll possible combinations of values of an \n"
   "Enum with FlagsAttribute:\n" );

   // Display all possible combinations of values.
   // Also display an invalid value.
   for ( int val = 0; val <= 8; val++ )
      Console::WriteLine( "{0,3} - {1}", val, ((MultiHue)val).ToString() );
}

/*
This example of the FlagsAttribute attribute
generates the following output.

All possible combinations of values of an
Enum without FlagsAttribute:

  0 - Black
  1 - Red
  2 - Green
  3 - 3
  4 - Blue
  5 - 5
  6 - 6
  7 - 7
  8 - 8

All possible combinations of values of an
Enum with FlagsAttribute:

  0 - Black
  1 - Red
  2 - Green
  3 - Red, Green
  4 - Blue
  5 - Red, Blue
  6 - Green, Blue
  7 - Red, Green, Blue
  8 - 8
*/


Informazioni sulla versione

.NET Framework

Supportato in: 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supportato in: 4, 3.5 SP1

Supportato in:
Piattaforme

Windows 7, Windows Vista SP1 o versione successiva, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (componenti di base del server non supportati), Windows Server 2008 R2 (componenti di base del server supportati con SP1 o versione successiva), Windows Server 2003 SP2

.NET Framework non supporta tutte le versioni di ciascuna piattaforma. Per un elenco delle versioni supportate, vedere Requisiti di sistema di .NET Framework.
Codice thread safe

Qualsiasi membro static (Shared in Visual Basic) pubblico di questo tipo è thread-safe. I membri di istanza non sono garantiti come thread-safe.
Vedere anche

Riferimenti