|
|||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||
|
Announcements
Want a new Job?
Chapters
Services
Feature Zones
|
Note: This is an unedited contribution. If this article is inappropriate,
needs attention or copies someone else's work without reference then please
Report This Article
IntroductionNArrange is a stand-alone, configurable .NET code beautification tool that automatically organizes code members and elements within .NET classes. It allows developers to easily sort class contents according to their style and layout conventions. NArrange works by parsing source code files into a document object model, arranging the elements then rewriting the arranged source code. NArrange helps reduce the amount of time developers spend arranging members within source code files and when used as part of check-in procedures can also help reduce source code repository conflicts. With NArrange, developers don't need to worry about where they place a new member definition in a class, they can just type away and run NArrange prior to compilation. After formatting, the new member will be automatically moved to the appropriate location in the source file. NArrange is not only a great time saver, but it also helps enforce coding style standards across a team when a common configuration file is used. Obtaining NArrangeNArrange is an open source tool and can be downloaded from SourceForge at http://sourceforge.net/project/showfiles.php?group_id=213288. Using NArrangeTo demonstrate the common usage scenarios of NArrange we'll start by creating a new project in our C# editor, in this case Visual Studio®, and add a stub class with a constructor. Note that since NArrange is a stand-alone tool without any IDE dependencies, it can be used along with any code editor or within automated build processes.
With the project saved, NArrange can then be run against the source code file, project or solution. For running NArrange from the command line refer to Command Line Usage or to integrate with Visual Studio® as an external tool see Microsoft® Visual Studio® Setup. When running NArrange with an editor, it is recommended to backup or commit your source first or use the built-in backup feature, which makes reverting formatting changes a snap. Either way, please be sure to protect your time investment in your code prior to running the tool.
After running NArrange, the constructor we added to the stub class will automatically be enclosed in a "Constructors" region (see image below).
Since our stub class doesn't yet have any functionality we'll then add a new method, called Demo, that writes a friendly message to the console. Note that when adding the new method we're not taking any care in regard to its placement within the class. In this case, we are adding it as the first member just inside the class body, before the constructor.
After adding the new member we'll run NArrange again against the source file or project. The new method will be automatically moved to the proper location in the file and enclosed in an appropriate region (see below). The default configuration for NArrange also sorts members within groups or regions alphabetically by member name.
Scrolling up to the top of the source file, you will also notice that NArrange automatically enclosed the header comments in a region and applied grouping and sorting to using directives (see image below).
Command Line UsageTo arrange a file just run the following: >narrange-console <source file> [optional output file]
If an output file is not specified, the original source file will be overwritten. Alternatively, you can run NArrange against a C# or VB project file or solution. When arranging a project or solution, the original source files will be overwritten. The command line usage is as follows: narrange-console <input> [output] [/c:configuration]
[/b] [/r] [/t]
input Specifies the source code file, project or solution to arrange.
output For a single source file, specifies the output file
to write arranged code to.
[Optional] If not specified the input source
file will be overwritten.
/c Configuration - Specifies the XML configuration file to use.
[Optional] If not specified the default
configuration will be used.
/b Backup - Specifies to create a backup before arranging
[Optional] If not specified, no backup will be created.
Only valid if an output file is not specified
and cannot be used in conjunction with Restore.
/r Restore - Restores arranged files from the latest backup
[Optional] When this flag is provided, no files will be arranged.
Only valid if an output file is not specified
and cannot be used in conjunction with Backup.
/t Trace - Detailed logging
Microsoft® Visual Studio® Setup
Creating a Custom Configuration FileBy default, NArrange uses a configuration that is, for the most part, compatible with the member ordering rules defined by the Microsoft StyleCop source analysis tool. An exception to this is file header regions. To override the default arrangement of source code members, a custom configuration file can be used. To create your own custom configuration file, you should start by creating a copy of DefaultConfig.xml and renaming it appropriately. Note that NArrange does not read DefaultConfig.xml, but rather it is provided as an example for creating a custom configuration. The actual default configuration is embedded within the NArrange core assembly. The NArrange Configuration Editor, shown below, can be used to ease editing of the XML configuration. It can be launched using narrange-config.exe.
By defining a sort attribute for elements in a region, NArrange will sort those elements alphabetically in the region by the specified attribute. Valid element attributes are:
Attributes can also be qualified with a scope. For example You may notice that filter conditions can be applied to elements, which are used to filter elements into the appropriate group or region. Filter expressions can use the element attributes above using the
Strings in element expressions should be enclosed with single quotes. LimitationsOne of the biggest limitations with the current version of NArrange is that it cannot handle many scenarios involving preprocessor directives ( For conditional compilation preprocessor directives ( Supported LanguagesNArrange currently supports organization of C# and Visual Basic .NET source code files. Although NArrange has been built and tested under the .NET Framework 2.0 it includes support for many 3.0 and 3.5 language features such as:
Many 3.+ language features are excluded from this list, such as LINQ and Lambda Expressions. However, NArrange does not currently parse to the statement level of constructors, methods and properties, so these features are inherently supported. LicensingNArrange is licensed and distributed under the Common Public License Version 1.0. A copy of this license is included with the source distribution and can also be viewed online at http://narrange.sourceforge.net/license.txt. SupportPlease direct all support questions, feature requests and bug reports to the NArrange SourceForge project site or to the CodeProject forum for this article. History05/12/2008 - Initial authoring for inclusion within the NArrange preliminary documentation and introduction on CodeProject. For the most up-to-date documentation please refer to http://narrange.sourceforge.net. Copyright © 2008 James Nies
|
||||||||||||||||||||||||||||||||||||||