This post shows how to create an Automatic Property, by turning an existing private field into a property.
You've got a private field that you would like to expose to users of your class, but you only want them to be able to get, not set the value.
You could expose the field itself to callers, but it's better to expose a property so that you can set different permissions for get and set, add behaviour when the value is set, and make it easy to version your class so that callers won't notice when you change your internal features.
For this walk-through, I'll assume you've already got a private field on your class that you want to expose publicly.
Encapsulating Fields
So starting with your private field, that has no public access:
class TestClass
{
private int _Property1;
}
You can use the refactoring support in Visual Studio's right-click menu to wrap the field with a property:
Go ahead and select the "All" option to update all usages of the _Property1 to use the new property we are creating:
Now all code will reference the Property1 property, rather than the private field:
class TestClass
{
private int _Property1;
public int Property1
{
get { return _Property1; }
set { _Property1 = value; }
}
}
Our final requirement was that Getting the value should be public, but the setter should be private, so external callers can't update our fields value.
You can do this by overriding the access of the setter, to make it more restricted:
class TestClass
{
private int _Property1;
public int Property1
{
get { return _Property1; }
private set { _Property1 = value; }
}
}
Note the addition of the private keyword to the property setter, while the public keyword now will just apply to the getter.
Automatic Properties
C# 3.0 added a handy new feature called Automatic Properties.
If all your accesses to a field (e.g. _Property1) are going through a property (Property1), then it seems like a waste to have to create a private field by hand.
Automatic Properties in C# will let the compiler do the work of creating the private field for you. All you have to do is create the property.
Change the code to:
class TestClass
{
public int Property1
{
get;
private set;
}
}
If you have no body for the getter and setter, the C# compiler will automatically create a field to store the value in. The accessibility of the setter can be set to private as above, so you have all the benefits of a private field, without having to create it yourself.
Now external callers can only reference the property Property1, while internal callers within your class can access both the getter and setter.
By following the above sequence of encapsulating, you won't have to manually change any of the callers of your original field to use the property:
- Encapsulate field
- Update all references to point to the new field
- Remove the original field, and the contents of the getter and setter
- Update access of the getter and setter as desired (e.g. make set private)
Snippets
If you're starting from scratch, and you don't already have a field to encapsulate, there are a couple of handy snippets you can use:
prop [tab] [tab] - this will create a regular automatic property, and let you set the type and name:
public int MyProperty { get; set; }
propg [tab] [tab] - this will do the same, but with a private setter:
public int MyProperty { get; private set; }
I hope this post gives you some quick tips when dealing with properties.
Kirk
Extras
It's always tempting to go off on a tangent talking about technicalities. If you're interested in such stuff, read on...
Field names for automatic properties
The compiler will choose a "magic" name for your field that is storing the data exposed by the automatic property. You can't refer to it directly from your code, and the compiler will make sure it's unique.
For example, my "Property1" has the following fieldname chosen by the compiler:
private int <Property1>k__BackingField;
You can see how it can be guaranteed to be unique -- it uses characters that are not allowed in C#!
Encapsulation
Why is it nicer to use a property than a field? There's a few reasons that I listed above: different permissions for get and set, add behaviour when the value is set, and make it easy to version your class so that callers won't notice when you change your internal features.
Accessibility
If you expose a field as public, you can't restrict your callers from updating it's value. A property can be made public for get, and private for set, which makes it easy to expose data, but still encapsulate it within your class.
Behaviour
Sometimes you'll want to do some validation checks when a property is set. For example, you might want to check that Property1 is never set to 0:
set {
if (_Property1 != 0)
_Property1 = value;
}
If you use a property, then you have the ability to add this logic inside the get or set method -- with a field that's not possible.
Versioning
If you expose a public field to callers, changing the name or data type of that field breaks the contract your class has with it's callers, and they will all need to be updated.
With a property, you can change the internals of your class, and where it stores the data, without affecting the caller of your property -- as long as the property has the same name, type and accessibility, they won't know anything has changed.
This helps with versioning your class, as changes to your class won't affect the rest of your program.
Cheers,
Kirk
Previous C# tips:
And other Visual Studio tips: