{"id":51534,"date":"2024-04-23T10:00:00","date_gmt":"2024-04-23T17:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=51534"},"modified":"2024-04-23T08:47:50","modified_gmt":"2024-04-23T15:47:50","slug":"csharp-primary-constructors-refactoring","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/csharp-primary-constructors-refactoring\/","title":{"rendered":"Refactor your C# code with primary constructors"},"content":{"rendered":"

C# 12 as part of .NET 8<\/a> introduced a compelling set of new features! In this post, we explore one of these features, specifically primary constructors<\/em>, explaining its usage and relevance. We’ll then demonstrate a sample refactoring to show how it can be applied in your code, discussing the benefits and potential pitfalls. This will help you understand the impact of the change and help influence your adoption of the feature.<\/p>\n

Primary Constructors 1\ufe0f\u20e3<\/h2>\n

Primary constructors are considered an “Everyday C#” developer feature. They allow you to define a class<\/code> or struct<\/code> along with its constructor in a single concise declaration. This can help you reduce the amount of boilerplate code you need to write. If you’ve been following along with C# versions, you’re likely familiar with record<\/code> types, which included the first examples of primary constructors.<\/p>\n

Differentiating from record<\/code> types<\/h3>\n

Record types<\/a> were introduced as a type modifier of class<\/code> or struct<\/code> that simplifies syntax for building simple classes like data containers. Records can include a primary constructor. This constructor not only generates a backing field but also exposes a public property for each parameter. Unlike traditional class<\/code> or struct<\/code> types, where primary constructor parameters are accessible throughout the class definition, records are designed to be transparent data containers. They inherently support value-based equality, aligning with their intended role as data holders. Consequently, it’s logical for their primary constructor parameters to be accessible as properties.<\/p>\n

Refactoring example\u2728<\/h3>\n

.NET provides many templates<\/a>, and if you’ve ever created a Worker Service<\/a>, you’ve likely seen the following Worker<\/code> class template code:<\/p>\n

namespace Example.Worker.Service\r\n{\r\n    public class Worker : BackgroundService\r\n    {\r\n        private readonly ILogger<Worker> _logger;\r\n\r\n        public Worker(ILogger<Worker> logger)\r\n        {\r\n            _logger = logger;\r\n        }\r\n\r\n        protected override async Task ExecuteAsync(CancellationToken stoppingToken)\r\n        {\r\n            while (!stoppingToken.IsCancellationRequested)\r\n            {\r\n                if (_logger.IsEnabled(LogLevel.Information))\r\n                {\r\n                    _logger.LogInformation(\"Worker running at: {time}\", DateTimeOffset.Now);\r\n                }\r\n                await Task.Delay(1000, stoppingToken);\r\n            }\r\n        }\r\n    }\r\n}<\/code><\/pre>\n
The preceding code is a simple Worker<\/code> service that logs a message every second. Currently, the Worker<\/code> class has a constructor that requires an ILogger<Worker><\/code> instance as a parameter and assigns it to a readonly<\/code> field of the same type. This type information is in two places, in the definition of the constructor, but also on the field itself. This is a common pattern in C# code, but it can be simplified with primary constructors.<\/p>\n
It’s worth mentioning that the refactoring tooling for this specific feature isn’t available in Visual Studio Code, but you can still refactor to primary constructors manually. To refactor this code using primary constructors in Visual Studio, you can use the Use primary constructor (and remove fields)<\/code> refactoring option. Right-click on the Worker<\/code> constructor, select Quick Actions and Refactorings...<\/code> (or press Ctrl<\/kbd> + .<\/kbd>), and choose Use primary constructor (and remove fields)<\/code>.<\/p>\n
Consider the following video demonstrating Use primary constructor<\/em> refactoring functionality:<\/p>\n
https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2024\/04\/refactor-primary-ctor.mp4<\/a><\/video><\/div><\/p>\n
The resulting code now resembles the following C# code:<\/p>\n
namespace Example.Worker.Service\r\n{\r\n    public class Worker(ILogger<Worker> logger) : BackgroundService\r\n    {\r\n        protected override async Task ExecuteAsync(CancellationToken stoppingToken)\r\n        {\r\n            while (!stoppingToken.IsCancellationRequested)\r\n            {\r\n                if (logger.IsEnabled(LogLevel.Information))\r\n                {\r\n                    logger.LogInformation(\"Worker running at: {time}\", DateTimeOffset.Now);\r\n                }\r\n                await Task.Delay(1000, stoppingToken);\r\n            }\r\n        }\r\n    }\r\n}<\/code><\/pre>\n
That’s it, you’ve successfully refactored the Worker<\/code> class to use a primary constructor! The ILogger<Worker><\/code> field has been removed, and the constructor has been replaced with a primary constructor. This makes the code more concise and easier to read. The logger<\/code> instance is now available throughout the class (as it’s in scope), without the need for a separate field declaration.<\/p>\n
Additional considerations \ud83e\udd14<\/h2>\n
Primary constructors can remove your hand-written field declarations that were assigned in the constructor, but with a caveat. They’re not entirely functionally equivalent if you have defined your fields as readonly<\/code> because primary constructor parameters for non-record types are mutable. So, when you’re using this refactoring approach, be aware that you’re changing the semantics of your code. If you want to maintain the readonly<\/code> behavior, use a field declaration in place and assign the field using the primary constructor parameter:<\/p>\n
namespace Example.Worker.Service;\r\n\r\npublic class Worker(ILogger<Worker> logger) : BackgroundService\r\n{\r\n    private readonly ILogger<Worker> _logger = logger;\r\n\r\n    protected override async Task ExecuteAsync(CancellationToken stoppingToken)\r\n    {\r\n        while (!stoppingToken.IsCancellationRequested)\r\n        {\r\n            if (_logger.IsEnabled(LogLevel.Information))\r\n            {\r\n                _logger.LogInformation(\"Worker running at: {time}\", DateTimeOffset.Now);\r\n            }\r\n            await Task.Delay(1000, stoppingToken);\r\n        }\r\n    }\r\n}<\/code><\/pre>\n
Additional constructors \ud83c\udd95<\/h2>\n
When you define a primary constructor, you can still define additional constructors. These constructors are required, however; to call the primary constructor. Calling the primary constructor ensures that the primary constructor parameters are initialized everywhere in the class declaration. If you need to define additional constructors, you must call the primary constructor using the this<\/code> keyword.<\/p>\n
namespace Example.Worker.Service\r\n{\r\n    \/\/ Primary constructor\r\n    public class Worker(ILogger<Worker> logger) : BackgroundService\r\n    {\r\n        private readonly int _delayDuration = 1_000;\r\n\r\n        \/\/ Secondary constructor, calling the primary constructor\r\n        public Worker(ILogger<Worker> logger, int delayDuration) : this(logger)\r\n        {\r\n            _delayDuration = delayDuration;\r\n        }\r\n\r\n        \/\/ Omitted for brevity...\r\n    }\r\n}<\/code><\/pre>\n
Additional constructors aren’t always needed. Let’s do some bonus refactoring to include a few other features!<\/p>\n
Bonus refactoring \ud83c\udf89<\/h2>\n
Primary constructors are awesome, but there’s more we can do to improve the code.<\/p>\n
C# includes file-scoped namespaces<\/a>. They’re a really nice feature that reduces a level of nesting and improves readability. Continuing with the previous example, place your cursor at the end of the namespace name, and press the ;<\/kbd> key (this isn’t supported in Visual Studio Code, but again you can do this manually). This will convert the namespace to a file-scoped namespace.<\/p>\n
Consider the following video demonstrating this functionality:<\/p>\n
https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2024\/04\/refactor-file-scope-ns.mp4<\/a><\/video><\/div><\/p>\n
With a few additional edits, the final refactored code is as follows:<\/p>\n
namespace Example.Worker.Service;\r\n\r\npublic sealed class Worker(ILogger<Worker> logger) : BackgroundService\r\n{\r\n    protected override async Task ExecuteAsync(CancellationToken stoppingToken)\r\n    {\r\n        while (!stoppingToken.IsCancellationRequested)\r\n        {\r\n            if (logger.IsEnabled(LogLevel.Information))\r\n            {\r\n                logger.LogInformation(\"Worker running at: {time}\", DateTimeOffset.Now);\r\n            }\r\n\r\n            await Task.Delay(1_000, stoppingToken);\r\n        }\r\n    }\r\n}<\/code><\/pre>\n
In addition to refactoring to file-scoped namespaces, I also added the sealed<\/code> modifier, as there’s a performance benefit in multiple situations. Finally, I’ve also updated the numeric literal passed into the Task.Delay<\/code> using the digit separator<\/a> feature, to improve the readability. Did you know there’s a lot more to simplify your code? Check out What’s new in C#<\/a> to learn more!<\/p>\n
Next steps \ud83d\ude80<\/h2>\n
Try this out in your own code! Look for opportunities to refactor your code to use primary constructors and see how it can simplify your codebase. If you’re using Visual Studio, check out the refactoring tooling. If you’re using Visual Studio Code, you can still refactor manually. To learn more, explore the following resources:<\/p>\n