Skip to content

Csharp 73 autoproperty field attributes #5157

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
May 8, 2018
Merged

Csharp 73 autoproperty field attributes #5157

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
64f616c
move samples to samples repo
BillWagner Apr 25, 2018
25ea52e
move samples to samples repo
BillWagner Apr 25, 2018
2a49738
finishing update content for new attributes
BillWagner May 3, 2018
62845e1
fix build errors
BillWagner May 4, 2018
e48b6df
respond to feedback.
BillWagner May 4, 2018
d568f58
add link to attributes tutotial
BillWagner May 8, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 78 additions & 135 deletions docs/csharp/programming-guide/concepts/attributes/attributeusage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,141 +1,84 @@
---
title: "AttributeUsage (C#)"
ms.date: 07/20/2015
ms.assetid: 22c45568-9a6a-4c2f-8480-f38c1caa0a99
ms.date: 04/25/2018
---
# AttributeUsage (C#)
Determines how a custom attribute class can be used. `AttributeUsage` is an attribute that can be applied to custom attribute definitions to control how the new attribute can be applied. The default settings look like this when applied explicitly:

```csharp
[System.AttributeUsage(System.AttributeTargets.All,
AllowMultiple = false,
Inherited = true)]
class NewAttribute : System.Attribute { }
```

In this example, the `NewAttribute` class can be applied to any attribute-able code entity, but can be applied only once to each entity. It is inherited by derived classes when applied to a base class.

The `AllowMultiple` and `Inherited` arguments are optional, so this code has the same effect:

```csharp
[System.AttributeUsage(System.AttributeTargets.All)]
class NewAttribute : System.Attribute { }
```

The first `AttributeUsage` argument must be one or more elements of the <xref:System.AttributeTargets> enumeration. Multiple target types can be linked together with the OR operator, like this:

```csharp
using System;

[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field)]
class NewPropertyOrFieldAttribute : Attribute { }
```

If the `AllowMultiple` argument is set to `true`, then the resulting attribute can be applied more than once to a single entity, like this:

```csharp
using System;

[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
class MultiUseAttr : Attribute { }

[MultiUseAttr]
[MultiUseAttr]
class Class1 { }

[MultiUseAttr, MultiUseAttr]
class Class2 { }
```

In this case `MultiUseAttr` can be applied repeatedly because `AllowMultiple` is set to `true`. Both formats shown for applying multiple attributes are valid.

If `Inherited` is set to `false`, then the attribute is not inherited by classes that are derived from a class that is attributed. For example:

```csharp
using System;

[AttributeUsage(AttributeTargets.Class, Inherited = false)]
class Attr1 : Attribute { }

[Attr1]
class BClass { }

class DClass : BClass { }
```

In this case `Attr1` is not applied to `DClass` via inheritance.

## Remarks
The `AttributeUsage` attribute is a single-use attribute--it cannot be applied more than once to the same class. `AttributeUsage` is an alias for <xref:System.AttributeUsageAttribute>.

For more information, see [Accessing Attributes by Using Reflection (C#)](../../../../csharp/programming-guide/concepts/attributes/accessing-attributes-by-using-reflection.md).

## Example
The following example demonstrates the effect of the `Inherited` and `AllowMultiple` arguments to the `AttributeUsage` attribute, and how the custom attributes applied to a class can be enumerated.

```csharp
using System;

// Create some custom attributes:
[AttributeUsage(System.AttributeTargets.Class, Inherited = false)]
class A1 : System.Attribute { }

[AttributeUsage(System.AttributeTargets.Class)]
class A2 : System.Attribute { }

[AttributeUsage(System.AttributeTargets.Class, AllowMultiple = true)]
class A3 : System.Attribute { }

// Apply custom attributes to classes:
[A1, A2]
class BaseClass { }

[A3, A3]
class DerivedClass : BaseClass { }

public class TestAttributeUsage
{
static void Main()
{
BaseClass b = new BaseClass();
DerivedClass d = new DerivedClass();

// Display custom attributes for each class.
Console.WriteLine("Attributes on Base Class:");
object[] attrs = b.GetType().GetCustomAttributes(true);
foreach (Attribute attr in attrs)
{
Console.WriteLine(attr);
}

Console.WriteLine("Attributes on Derived Class:");
attrs = d.GetType().GetCustomAttributes(true);
foreach (Attribute attr in attrs)
{
Console.WriteLine(attr);
}
}
}
```

## Sample Output

```
Attributes on Base Class:
A1
A2
Attributes on Derived Class:
A3
A3
A2
```

## See Also

Determines how a custom attribute class can be used. <xref:System.AttributeUsageAttribute> is an attribute you apply to custom attribute definitions. The `AttributeUsage` attribute enables you to control:

- Which program elements attribute may be applied to. Unless you restrict is usage, an attribute may be applied to any of the following program elements:
- assembly
- module
- field
- event
- method
- param
- property
- return
- type
- Whether an attribute can be applied to a single program element multiple times.
- Whether attributes are inherited by derived classes.

The default settings look like the following example when applied explicitly:

[!code-csharp[Define a new attribute](../../../../../samples/snippets/csharp/attributes/NewAttribute.cs#1)]

In this example, the `NewAttribute` class can be applied to any supported program element. But it can be applied only once to each entity. The attribute is inherited by derived classes when applied to a base class.

The <xref:System.AttributeUsageAttribute.AllowMultiple> and <xref:System.AttributeUsageAttribute.Inherited> arguments are optional, so the following code has the same effect:

[!code-csharp[Omit optional attributes](../../../../../samples/snippets/csharp/attributes/NewAttribute.cs#2)]

The first <xref:System.AttributeUsageAttribute> argument must be one or more elements of the <xref:System.AttributeTargets> enumeration. Multiple target types can be linked together with the OR operator, like the following example shows:

[!code-csharp[Create an attribute for fields or properties](../../../../../samples/snippets/csharp/attributes/NewPropertyOrFieldAttribute.cs#1)]

Beginning in C# 7.3, attributes can be applied to either the property or the backing field for an auto-implemented property. The attribute applies to the property, unless you specify the `field` specifier on the attribute. Both are shown in the following example:

[!code-csharp[Create an attribute for fields or properties](../../../../../samples/snippets/csharp/attributes/NewPropertyOrFieldAttribute.cs#2)]

If the <xref:System.AttributeUsageAttribute.AllowMultiple> argument is `true`, then the resulting attribute can be applied more than once to a single entity, as shown in the following example:

[!code-csharp[Create and use an attribute that can be applied multiple times](../../../../../samples/snippets/csharp/attributes/MultiUseAttribute.cs#1)]

In this case, `MultiUseAttribute` can be applied repeatedly because `AllowMultiple` is set to `true`. Both formats shown for applying multiple attributes are valid.

If <xref:System.AttributeUsageAttribute.Inherited> is `false`, then the attribute isn't inherited by classes derived from an attributed class. For example:

[!code-csharp[Create and use an attribute that can be applied multiple times](../../../../../samples/snippets/csharp/attributes/NonInheritedAttribute.cs#1)]

In this case `NonInheritedAttribute` isn't applied to `DClass` via inheritance.

## Remarks

The `AttributeUsage` attribute is a single-use attribute--it can't be applied more than once to the same class. `AttributeUsage` is an alias for <xref:System.AttributeUsageAttribute>.

For more information, see [Accessing Attributes by Using Reflection (C#)](accessing-attributes-by-using-reflection.md).

## Example

The following example demonstrates the effect of the <xref:System.AttributeUsageAttribute.Inherited> and <xref:System.AttributeUsageAttribute.AllowMultiple> arguments to the <xref:System.AttributeUsageAttribute> attribute, and how the custom attributes applied to a class can be enumerated.

[!code-csharp[Applying and querying attributes](../../../../../samples/snippets/csharp/attributes/Program.cs#1)]

## Sample Output

```text
Attributes on Base Class:
FirstAttribute
SecondAttribute
Attributes on Derived Class:
ThirdAttribute
ThirdAttribute
SecondAttribute
```

## See Also
<xref:System.Attribute>
<xref:System.Reflection>
[C# Programming Guide](../../../../csharp/programming-guide/index.md)
[Attributes](../../../../../docs/standard/attributes/index.md)
[Reflection (C#)](../../../../csharp/programming-guide/concepts/reflection.md)
[Attributes](../../../../csharp/programming-guide/concepts/attributes/index.md)
[Creating Custom Attributes (C#)](../../../../csharp/programming-guide/concepts/attributes/creating-custom-attributes.md)
[Accessing Attributes by Using Reflection (C#)](../../../../csharp/programming-guide/concepts/attributes/accessing-attributes-by-using-reflection.md)
[C# Programming Guide](../..//index.md)
[Attributes](../../../..//standard/attributes/index.md)
[Reflection (C#)](../reflection.md)
[Attributes](index.md)
[Creating Custom Attributes (C#)](creating-custom-attributes.md)
[Accessing Attributes by Using Reflection (C#)](accessing-attributes-by-using-reflection.md)
Loading