An open source tool for arranging .NET source code
SourceForge.net Logo

Documentation

Version 0.2.7.0
Last Modified: 08/10/2008

Index

- Introduction
    - What is NArrange?
    - Supported Languages
     - Obtaining NArrange
    - Licensing
    - Support
- Using NArrange
    - Demo
    - Command Line Usage
    - Microsoft® Visual Studio® Setup
- Configuration
    - Creating a Custom Configuration File
    - Sorting and Expressions
    - Formatting
    - File Extensions and Filtering
    - File Encoding
- Limitations
    - Preprocessor Directives

Introduction

What is NArrange?

NArrange 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.

Supported Languages

NArrange 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:

  • Partial Methods
  • Extension Methods
  • Object Initializers

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.

NArrange has been designed with the intention of supporting many .NET languages. If you are interested in implementing a parser/writer for an additonal CLI language, please contact an NArrange contributor through the SourceForge project site. NArrange is still in the early stages of development so any suggestions to help make the framework more compatible with other languages would be greatly appreciated.

Obtaining NArrange

NArrange is an open source tool and can be downloaded from SourceForge at http://sourceforge.net/project/showfiles.php?group_id=213288.

Licensing

NArrange 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.

Support

Please direct all support questions, feature requests and bug reports to the NArrange SourceForge project site.

Using NArrange

Demo

To 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.


Figure: New Project with a Class Stub

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.


Figure: Running NArrange as a VS External Tool

After running NArrange, the constructor we added to the stub class will automatically be enclosed in a #Constructors region (see image below).


Figure: After Running NArrange Against the Stub Class

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.


Figure: Adding a New Member

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.


Figure: Rearranged Class with New Method

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).


Figure: Header Region and Sorted Using Directives

Command Line Usage

To 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, solution or 
        directory 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

  1. From the Tools menu, select External Tools.
  2. Add a new entry for NArrange.
    • For the Command, select the location of narrange-console.exe.
    • For arguments, pass the solution, project or file path macro depending on your preference. When choosing this, you may want to take into consideration your revision control system (i.e. whether or not files are marked as read-only). NArrange cannot arrange read-only files. It is recommended to pass the /b argument to specify that an automatic backup be created in your user temp directory.

  3. It is also recommended to setup a restore command using the same parameters, replacing /b with /r. However, be careful when using restore as it will revert any edits made to a file since the last NArrange.



Configuration

Creating a Custom Configuration File

By 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 can start by creating a copy of DefaultConfig.xml and renaming 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.


Figure: Configuration Editor

The figure below shows sections from a sample XML configuration file. NArrange uses the ordering of Element and Region tags in the configuration file to define the ordering of code members in the output source files.


Figure: Sample NArrange Configuration File

Sorting and Expressions

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:

  • Name - Returns the code element name.

  • Access - Returns the element access.
    Valid comparison value strings for this attribute are:
    • None
    • Public
    • Protected
    • Internal
    • Protected, Internal

  • Modifier - Returns element modifiers as a comma separated list.
    Valid comparison value strings for this attribute are:
    • Abstract
    • Sealed
    • Static
    • Unsafe
    • Virtual
    • Override
    • New
    • ReadOnly
    • Constant
    • External
    • Partial

  • ElementType - Returns the NArrange element type.
    Valid comparison value strings for this attribute are:
    • Comment
    • Attribute
    • Using
    • Namespace
    • Region
    • ConditionDirective
    • Field
    • Constructor
    • Property
    • Method
    • Event
    • Delegate
    • Type

  • Type - Returns the return type of the element (e.g. 'string').
    For Type elements, this returns the sub-type: 'Class', 'Structure', 'Interface', 'Enum' or 'Module' (VB only)

  • Attributes - Returns a comma separated list of the names of all attributes associated with an element.

Attributes can also be qualified with a scope. For example $(Element.Name) or $(Parent.ElementType).

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 $(AttributeHere) syntax. Filter expressions use string comparison and the following operators are available:

Operator Name Syntax
Equality ==
Inequality !=
Contains :
Regular Expression Match =~
Logical Or Or
Logical And And
Negate !(inner expression)

Strings in element expressions should be enclosed with single quotes.

Formatting

The following formatting options are available.

Tabs - Allows specification of "Tabs" or "Spaces" and the number of spaces per tab 

<CodeConfiguration>
    <Formatting>
        ...
        <Tabs Style="Tabs" SpacesPerTab="4"/>
        ...
    </Formatting>
</CodeConfiguration>

Closing Comments - Allows specification of whether or not a closing comment should be written after an element with body text (e.g. method, constructor). This is off by default. The Format string allows accepts element attribute parameters. 

<CodeConfiguration>
    <Formatting>
        ...
       <ClosingComments Enabled="false" Format="End $(ElementType) $(Name)"/>
        ...
    </Formatting>
</CodeConfiguration>

Regions - Formatting and configuration for all regions. The "EndRegionNameEnabled" flag allows control over whether the region name is written in the closing preprocessor directive.

<CodeConfiguration>
    <Formatting>
        ...
        <Regions EndRegionNameEnabled="true" Style="Default"
            CommentDirectiveBeginPattern="^\s?\$\(\s?Begin\s?\)\s?(?&lt;Name&gt;.*)$"
            CommentDirectiveEndPattern="^\s?\$\(\s?End\s?\)\s?(?&lt;Name&gt;.*)?$"
            CommentDirectiveBeginFormat=" $(Begin) {0}"
            CommentDirectiveEndFormat=" $(End) {0}"/>
        ...
    </Formatting>
</CodeConfiguration>

Additionally, the Style attribute controls how regions are written. If the CommentDirective region style is chosen, then regions will be parsed and written according to the comment directive regular expression pattern and format properties. Note that if the comment directive attributes are modified, it is critical that the regular expressions correspond with the format strings. If there is a mismatch, then after initial arrangement, NArrange will no longer be able to interpret the comments as region start and end comments. When the comment directive region style is used and the format of the comments needs to be changed, it is necessary to change the style to the default (Directive), arrange, then modify the patterns and format before rearranging the source code.

Another style that is available is NoDirective. With this style, members within the configured regions will be written without any directives (as a group). Directives can be omitted for individual regions by setting the Region element's DirectivesEnabled attribute to false. This technique is also useful for grouping elements.

More formatting options will likely be made available in future versions of NArrange.

File Extensions and Filtering

The default NArrange configuration file has standard extension names set up for each included language package (C# and Visual Basic .NET). Thus, .cs and .vb files will automatically be handled. If however, an additional file extension needs to be recognized as source code, an extension can be registered in the XML configuration file.

The following demonstrates adding an additional file extension, .mycs, to be recognized as C# source code:

<SourceHandler Language="CSharp" Assembly="NArrange.CSharp, Version=0.2.1.0, Culture=neutral, PublicKeyToken=null">
    <!-- List of project extensions handled by the handler's IProjectParser -->
    <ProjectExtensions>
        <Extension Name="csproj"/>
    </ProjectExtensions>
    <!-- List of source file extensions valid for the handler's ICodeParser-->
    <SourceExtensions>
        <Extension Name="cs">
            <Filter Condition="!($(File.Name) : '.Designer.')"/>
        </Extension>
        <!-- If your project uses other extensions for C# files add them here-->
        <Extension Name="mycs"/>
    </SourceExtensions>
</SourceHandler>

In the configuration snippet above it should also be observed that the .cs extension has filtering applied. By default, .Designer.cs files will be excluded from arrangement. This is done as to not conflict with code generators, visual designers and custom tools. If further filtering is required, the following attributes are available for files:

  • File.Name - Returns the filename without a path
  • File.Path - Returns the entire path for the file
  • File.Attributes - Returns file attributes as a comma separated list (for a list of available values, refer to the System.IO.FileAttributes enumeration)

File Encoding

By default, NArrange will attempt to detect the encoding for your source code files. File encodings supported for detection include the system Ansi Default (e.g. CodePage 1252 Western-European), UTF-8, UTF-16 (big/little endian) and UTF-32 (little endian). If the detection process does not properly detect the encoding, it is possible to force a particular encoding for reading and writing all source code files.

The following setting is used to provide the default encoding detection:

<CodeConfiguration>
    ...
    <Encoding CodePage="Detect"/> 
    ...
</CodeConfiguration>

Valid CodePage values include:

  • "Detect" - Detect file encodings (NArrange default)
  • "Default" - Use the system default ANSI encoding (e.g. CodePage 1252 Western-European) for all source code files
  • CodePage - e.g. "65001" for UTF-8 for all source code files

Limitations

Preprocessor Directives

One of the biggest limitations with the current version of NArrange is that it cannot handle many scenarios involving preprocessor directives (#pragma, #define, etc.). Thus, you will get a warning message indicating that files containing unhandled preprocessor directives cannot be parsed. Note that this is not an issue if the preprocessor directive is within a member body.

For conditional compilation preprocessor directives (#if, #else, etc.), basic support is available. So long as the conditional compilation preprocessor directive completely encloses types/members in their entirety (with all attributes and comments), NArrange will preserve the directive and process any enclosed elements. However, the scenario where a directive starts at the class level and intersects a member declaration in any manner is not supported and will result in a parsing error.

 

Copyright © 2007-2008 James Nies