Copyright (c) 2012-7 by Sean Werkema All rights reserved.
Redesigner is a tool to generate and validate ASP.NET WebForms designer files.
ASP.NET WebForms 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!
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.
Compatibility Note: If you're using ASP.NET version 4.0 or higher, you should use the net40
feature branch, or you may see errors describing "unknown controls." The master
branch of the Redesigner code targets .NET 2.x/3.5.
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.
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).
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).
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? :-)
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.
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).
-
--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.
Future plans may 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.
-
Redesigner does not currently support controls that do clever things with
ControlBuilder
classes, such as using them to switch "obvious" types viaGetChildControlType()
. Any custom controls that heavily useControlBuilder
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.
-
Redesigner was originally written by Sean Werkema in October-December 2012. I updated it to v1.1 in January 2013.
-
Thanks to Darrell Tunnell for convincing me this tool is still needed, for getting it out of SourceForge and onto GitHub, and for getting the README and LICENSE converted.
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.