Csharp 73 autoproperty field attributes #5157

BillWagner · 2018-05-03T21:50:20Z

Fixes #3962

Update articles where attaching attributes to the backing field of an auto-implemented property should be mentioned.

Also, update the Serialization walkthrough to remove the Windows Forms dependency, and make it run on .NET Core.

Dependent on dotnet/samples#38 (Build will fail until that is merged.)

So much inline code...

Also, run acrolinx and update where needed.

BillWagner · 2018-05-04T01:38:15Z

closing and re-opening to force a new build

One will require a samples PR

These are needed for the build to pass in dotnet/docs#5157

BillWagner · 2018-05-04T14:24:31Z

PR dotnet/samples#39 fixes the build errors, and related snippet include alignment (some snippets display the wrong code.)

rpetrusha · 2018-05-04T15:41:03Z

Since the samples have merged, closing and reopening to begin new build.

BillWagner · 2018-05-04T15:44:06Z

@rpetrusha I think it will still fail. A few of the errors were in the snippet files. I opened dotnet/samples#39 to fix those. Once you review those changes, then this one should build.

rpetrusha · 2018-05-04T15:53:22Z

@BillWagner, sorry, in reviewing your source code PR I didn't notice that MultiUseAttribute.cs has an opening <Snippet1> tag but a closing <Snippet2> tag. Because of that, the build is continuing to fail even though the samples have been merged.

These are needed for the build to pass in dotnet/docs#5157

rpetrusha · 2018-05-04T16:17:54Z

Closing and reopening to resume build after code examples were merged.

rpetrusha

I've left a number of small nits and grammatical corrections, @BillWagner, along with some suggestions for further revision that are really unrelated to your PR but would help improve the overall topic. You might not want to address them now and instead open an issue to address them later.

rpetrusha · 2018-05-04T15:38:11Z

docs/csharp/programming-guide/concepts/attributes/attributeusage.md

-
-## See Also  
+
+Determines how a custom attribute class can be used. <xref:System.AttributeUsageAttribute> is an attribute you apply to custom attribute definitions. It controls how the new attribute can be applied. The default settings look like the following example when applied explicitly:


"It controls how the new attribute can be applied." is a rather vague sentence, and it's only a bit later that it becomes clear what this means. I think that I'd some variation of this sentence with a bulleted list of what it controls -- the program element to which the attribute can be applied, whether the same attribute can be applied multiple times, and inheritance.

rpetrusha · 2018-05-04T15:48:34Z

docs/csharp/programming-guide/concepts/attributes/attributeusage.md

+
+[!code-csharp[Define a new attribute](../../../../../samples/snippets/csharp/attributes/NewAttribute.cs#1)]
+
+In this example, the `NewAttribute` class can be applied to any attribute-able code entity. But it can be applied only once to each entity. The attribute is inherited by derived classes when applied to a base class.


I'm not quite sure about attribute-able, and I'm not sure anyone will know what it means. I think I would phrase this as "supported code element" or "supported program element" and perhaps provide a list.

I put the list of supported program elements above. That seemed more clear.

rpetrusha · 2018-05-04T15:59:25Z

docs/csharp/programming-guide/concepts/attributes/index.md

+
+## Using attributes
+
+Attributes can be placed on most any declaration, though a specific attribute might restrict the types of declarations on which it is valid. In C#, you specify an attribute by placing the name of the attribute, enclosed in square brackets ([]), above the declaration of the entity to which it applies.


the commas around "enclosed in square brackets..." aren't necessary

rpetrusha · 2018-05-04T16:01:15Z

docs/csharp/programming-guide/concepts/attributes/index.md

-int Method3() { return 0; }  
-```  
-
+> By convention, all attribute names end with the word "Attribute" to distinguish them from other items in the .NET Framework. However, you do not need to specify the attribute suffix when using attributes in code. For example, `[DllImport]` is equivalent to `[DllImportAttribute]`, but `DllImportAttribute` is the attribute's actual name in the .NET Framework.


perhaps in the .NET Framework -> in the .NET Framework Class Library, or "of the .NET Framework type"

If we rephrase it, then Framework might be omitted at all?

rpetrusha · 2018-05-04T16:06:54Z

docs/csharp/programming-guide/concepts/attributes/index.md

+[DllImport("user32.dll", ExactSpelling=false, SetLastError=false)]
+```
+
+The first parameter, the DLL name, is positional and always comes first; the others are named. In this case, both named parameters default to false, so they can be omitted. Refer to the individual attribute's documentation for information on default parameter values.


In terms of "Refer to...", the problem is that you have to know that the positional parameters correspond to an attribute constructor, and named/optional parameters to either properties or fields. That should probably be specified here.

rpetrusha · 2018-05-04T16:13:55Z

...rogramming-guide/concepts/serialization/walkthrough-persisting-an-object-in-visual-studio.md

 > [!IMPORTANT]
->  This example creates a new file if the file does not already exist. If an application must create a file, that application must `Create` permission for the folder. Permissions are set by using access control lists. If the file already exists, the application needs only `Write` permission, a lesser permission. Where possible, it is more secure to create the file during deployment, and only grant `Read` permissions to a single file (instead of Create permissions for a folder). Also, it is more secure to write data to user folders than to the root folder or the Program Files folder.  
-  
+> This example creates a new file if the file does not already exist. If an application must create a file, that application must have `Create` permission for the folder. Permissions are set by using access control lists. If the file already exists, the application needs only `Write` permission, a lesser permission. Where possible, it's more secure to create the file during deployment, and only grant `Read` permissions to a single file (instead of Create permissions for a folder). Also, it's more secure to write data to user folders than to the root folder or the Program Files folder.


no comma between "deployment" and "and only grant"

rpetrusha · 2018-05-04T16:21:19Z

...rogramming-guide/concepts/serialization/walkthrough-persisting-an-object-in-visual-studio.md

+
+[!code-csharp[Disable serialization for an auto-implemented property](../../../../../samples/csharp/serialization/Loan.cs#4)]
+
+The next step is to add the serialization code to the LoanApp application. In order to serialize the class and write it to a file, you use the <xref:System.IO> and <xref:System.Runtime.Serialization.Formatters.Binary> namespaces. To avoid typing the fully qualified names, you can add references to the necessary class libraries as shown in the following code:


the references aren't to the necessary class libraries, but to namespaces.

rpetrusha · 2018-05-04T16:22:49Z

docs/csharp/properties.md

+
+### Attaching attributes to auto-implemented properties
+
+Beginning with C# 7.3, field attributes can be attached to the compiler


compiler generate --> compiler-generated

pkulikov · 2018-05-06T16:44:35Z

docs/csharp/programming-guide/concepts/attributes/index.md

+
+For more information, see:
+
+- [Creating Custom Attributes (C#)](creating-custom-attributes.md)  


There is the tutorial on attributes. I think it's worth to be mentioned in this list.
By the way, should this tutorial be updated as well for the scope of this PR?

I added that link. When I read that tutorial, I didn't see where it should reference the new field: syntax for auto implemented properties.

These are needed for the build to pass in dotnet/docs#5157

BillWagner added 3 commits May 3, 2018 17:45

move samples to samples repo

64f616c

So much inline code...

move samples to samples repo

25ea52e

finishing update content for new attributes

2a49738

Also, run acrolinx and update where needed.

BillWagner requested review from mairaw and rpetrusha May 3, 2018 21:50

BillWagner added the 🚧 Hold for related PR Indicates a PR can only be merged when other related PRs are merged (see comments for links) label May 3, 2018

BillWagner closed this May 4, 2018

BillWagner reopened this May 4, 2018

fix build errors

62845e1

One will require a samples PR

BillWagner added a commit to BillWagner/samples that referenced this pull request May 4, 2018

fix snippet include errors

068f0a6

These are needed for the build to pass in dotnet/docs#5157

BillWagner mentioned this pull request May 4, 2018

fix snippet include errors dotnet/samples#39

Merged

rpetrusha closed this May 4, 2018

rpetrusha reopened this May 4, 2018

rpetrusha pushed a commit to dotnet/samples that referenced this pull request May 4, 2018

fix snippet include errors (#39)

533673a

These are needed for the build to pass in dotnet/docs#5157

rpetrusha closed this May 4, 2018

rpetrusha reopened this May 4, 2018

rpetrusha approved these changes May 4, 2018

View reviewed changes

respond to feedback.

e48b6df

pkulikov reviewed May 6, 2018

View reviewed changes

BillWagner removed the 🚧 Hold for related PR Indicates a PR can only be merged when other related PRs are merged (see comments for links) label May 8, 2018

add link to attributes tutotial

d568f58

BillWagner merged commit 5cef653 into dotnet:master May 8, 2018

BillWagner deleted the csharp73-autoproperty-field-attributes branch May 8, 2018 13:56

karelz pushed a commit to karelz/samples that referenced this pull request Aug 31, 2018

fix snippet include errors (dotnet#39)

537f7fd

These are needed for the build to pass in dotnet/docs#5157


		## See Also

		Determines how a custom attribute class can be used. <xref:System.AttributeUsageAttribute> is an attribute you apply to custom attribute definitions. It controls how the new attribute can be applied. 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 attribute-able code entity. But it can be applied only once to each entity. The attribute is inherited by derived classes when applied to a base class.


		## Using attributes

		Attributes can be placed on most any declaration, though a specific attribute might restrict the types of declarations on which it is valid. In C#, you specify an attribute by placing the name of the attribute, enclosed in square brackets ([]), above the declaration of the entity to which it applies.


		[!code-csharp[Disable serialization for an auto-implemented property](../../../../../samples/csharp/serialization/Loan.cs#4)]

		The next step is to add the serialization code to the LoanApp application. In order to serialize the class and write it to a file, you use the <xref:System.IO> and <xref:System.Runtime.Serialization.Formatters.Binary> namespaces. To avoid typing the fully qualified names, you can add references to the necessary class libraries as shown in the following code:


		### Attaching attributes to auto-implemented properties

		Beginning with C# 7.3, field attributes can be attached to the compiler


		For more information, see:

		- [Creating Custom Attributes (C#)](creating-custom-attributes.md)

Csharp 73 autoproperty field attributes #5157

Csharp 73 autoproperty field attributes #5157

Uh oh!

Conversation

BillWagner commented May 3, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BillWagner commented May 4, 2018

Uh oh!

BillWagner commented May 4, 2018

Uh oh!

rpetrusha commented May 4, 2018

Uh oh!

BillWagner commented May 4, 2018

Uh oh!

rpetrusha commented May 4, 2018

Uh oh!

rpetrusha commented May 4, 2018

Uh oh!

rpetrusha left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pkulikov May 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

BillWagner commented May 3, 2018 •

edited

Loading

pkulikov May 6, 2018 •

edited

Loading