Redesigner

Redesgner is a tool to generate and validate ASP.NET designer files

Disclaimer

This project was NOT written by myself. The author is Sean Werkema, and the original code can be found on SourceForge

I have created this repository on GitHub for my own convenience, and I have notified Sean. I did this because I am not familiar with SVN and would prefer not to become familiar with Source Forge :)

The Source Forge project has not had any activity in several years.

Overview

ASP.NET is a powerful website development framework, but the .designer files it requires can be a pain to work with. They can often get broken, corrupted, or out-of-sync with the markup, leading to complicated problems that are often difficult to resolve.

Redesigner is a command-line tool that can read and parse .aspx and .ascx files and generate .designer files for them. It runs quickly and reliably, and can display lots of useful information about how the .designer file was generated. It does not use or require Visual Studio, either!

It has an open-source license (the New BSD license) and can be reused anywhere for nearly any purpose, for free!

Usage

Redesigner is a command-line tool, and is invoked like this:

Redesigner.exe [-w website.dll] [-r path\to\root\of\website] [options] files.aspx ...

A simple use to regenerate a .designer file for MyPage.aspx might look like this:

Redesigner.exe -w MyWebsite\bin\MyWebsite.dll -r MyWebsite MyWebsite\MyPage.aspx

Note: Your website must be able to be compiled! Redesigner must be able to reflect against your website's DLL, so if you can't compile your website's DLL, do whatever you have to do to hack your website until you can get it to compile.

Currently, Redesigner can generate .designer.cs files for .aspx and .ascx files. It can handle <%@ Register %> directives found in markup, and registered namespaces and user controls found in your website's web.config. It can handle server controls, user controls, and HTML controls, data-bound controls and template controls, and complex nested control properties. It uses the same parsing regular expressions ASP.NET uses to ensure that it will analyze your markup the same way that ASP.NET will.

Redesigner can process whole directories of .ascx and .aspx files simply by specifying a directory name instead of just a .aspx or .ascx filename. It will recursively search the directory for all .ascx and .aspx files contained therein and will process all of them in a batch.

Generate Mode

In generate mode (the default mode), Redesigner will recreate one or more .designer files for the given .aspx or .ascx input file. Any existing .designer file will be replaced with one that Redesigner generates based on the control declarations found in the markup. The formatting and structure matches Visual Studio's, and should be readable by Visual Studio.

Regenerating a .designer file for MyPage.aspx might look like this:

Redesigner.exe -w MyWebsite\bin\MyWebsite.dll -r MyWebsite MyWebsite\MyPage.aspx

Regenerating .designer files for a whole directory tree might look like this:

Redesigner.exe -w MyWebsite\bin\MyWebsite.dll -r MyWebsite MyWebsite

Generate mode will display detailed error messages when it finds an error while parsing and analyzing a .aspx or .ascx file. In addition, it will also set Redesigner's exit code to describe the overall state of the generation task (see EXIT CODES below).

Verify Mode

In verify mode, turned on with the --verify option, Redesigner will attempt to determine whether existing .designer files are "correct" for their markup. It checks the layout of the file, whether the types match, whether all the control properties exist and are in the right order, and even whether the curly braces are in the right places (relative to how Visual Studio expects them).

A simple use to validate an existing .designer file for MyPage.aspx might look like this:

Redesigner.exe --verify -w MyWebsite\bin\MyWebsite.dll -r MyWebsite MyWebsite\MyPage.aspx

Validating an entire directory tree of .designer files might look like this:

Redesigner.exe --verify -w MyWebsite\bin\MyWebsite.dll -r MyWebsite MyWebsite

Verify mode will display detailed error messages when it finds an error in a .designer file. In addition, it will also set Redesigner's exit code to describe the overall state of the validation (see EXIT CODES below).

Verbose Option

If you want detailed information about what Redesigner is doing, you can add the --verbose option to the command-line. This will cause Redesigner to print out a huge quantity of text describing what it found in your markup, where it found the controls while reflecting, and lots of useful information that may be valuable when tracking down errors in your markup. The --verbose option prints a lot of text, but that's better than just saying "Exception of type System.Exception was thrown", isn't it? :-)

Quiet Options

Redesigner can generate a lot of output. If you want it to only display text when it encounters an error, and to omit all other text, add the --quiet option to the command-line.

Exit Codes

Redesigner attempts to be helpful by setting its exit code to a meaningful value. The exit codes it uses are as follows:

0:   Success: All tasks completed successfully.

1:   Nothing to do: No .aspx or .ascx files were given on the command-line.
2:   Help: The user requested help via the -h or --help command-line options.
3:   Command-line error: The command-line is not well-formed or has incompatible options.

-1:  Failed generation: At least one of the .designer files that was to be generated failed
      because of errors in the markup.
-2:  Failed validation: At least one of the .designer files that was to be verified was
      either broken, internally inconsistent, or failed to match its associated markup.
-3:  Redesigner encountered an internal processing error and was forced to stop.

Note that in some environments, the negative exit codes may become large positive numbers (for example, MS-DOS would turn -1 into 255). To ensure scripts behave correctly, it is safest to test only that the exit code was zero (success) or nonzero (failure).

Options

--help Show help on usage and command-line options.

--website website.dll -w website.dll The path to the DLL that contains the website's code-behind. [required]

--root pathname -r pathname Specify the path to the website's root, where the web.config file is located. [required]

--verify Verify that the existing designer file(s) were generated correctly.

--generate Generate replacement designer file(s) for the given pages/controls. [default]

--verbose Turn on verbose logging of page processing, which can help locate and diagnose errors.

--quiet Turn off all messages except errors.

TODO

Future plans include:

* Support for reading and processing .master files.

* Generating and verifying .designer.vb files (not just .designer.cs files).

* Creating a Redesigner.dll that can be reused in other applications.

* Creating a right-click plugin for Visual Studio to allow Redesigner to generate and verify
   .designer files for individual pages as well as folders.

* Creating a "Repair-If-Needed" mode that regenerates .designer files only for those that
   fail verification.

Bugs

* Redesigner does not currently support controls that do clever things with ControlBuilder
   classes, such as using them to switch "obvious" types via GetChildControlType().  Any
   custom controls that heavily use ControlBuilder may mis-compile.

* Controls that have been moved from the .designer file to the code-behind will be
   considered "missing" in verify mode, and will be regenerated in the .designer file in
   generate-mode.  Redesigner has no way to know that the required control declarations
   were moved, and adding support for this is somewhere between "challenging" and
   "impossible".

* Redesigner currently requires your website to be a compiled DLL.  It is theoretically
   possible to generate and verify using only the website's source code, but it's a
   nontrivial task to parse it on the fly to extract the class declarations and property
   names.  Support for this is possible but not currently planned.

LICENSE

This software is released under the terms of the "New BSD License," as follows:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

dazinator / Redesigner

readme