Copyright © Neumont University. All rights reserved.
Copyright © ORM Solutions, LLC. All rights reserved.
NORMA is a plugin to Visual Studio for designing relational databases using Object-Role Modeling version 2 standard, a fact-based conceptual modeling approach. Object-Role Models are easier for people to understand, validate adapt than the corresponding Entity-Relationship Models.
For licensing terms, see the adjacent LICENSE.txt file.
Several third-party components are required to build or compile the main portion of this software prior to Visual Studio 2017 (instructions for the newer environments are at the end of this file). These components can be obtained as follows:
PLiX - Programming Language in XML
IMPORTANT: You will need to establish the Visual Studio experimental
hive before building NORMA by running Visual Studio once in this
environment. Use the link provided by the VS SDK, or run devenv.exe /RootSuffix Exp
from a Visual Studio command prompt. For Visual
Studio 2008, make sure you use either the provided shortcut or add
/RANU
(run as normal user) to the command line. After running
FirstTimeBuildVS2008.bat you should use devenv /rootsuffix Exp
instead of devenv /rootsuffix Exp /RANU
.
Microsoft Visual Studio Modeling and Visualization Tools (DSL Tools SDK), installs after the primary SDK
Additional components used by other portions of this software include:
Several build scripts are available for building common combinations of the NORMA components:
To set the version of Visual Studio that NORMA is being built for, use
the TargetVisualStudioVersion
environment variable. The supported
values are:
SET TargetVisualStudioVersion=v8.0
SET TargetVisualStudioVersion=v9.0
SET TargetVisualStudioVersion=v10.0
SET TargetVisualStudioVersion=v11.0
SET TargetVisualStudioVersion=v12.0
SET TargetVisualStudioVersion=v14.0
SET TargetVisualStudioVersion=v15.0
SET TargetVisualStudioVersion=v16.0
Note that these are set for you with the VS20xx.bat
files discussed
below, which we strongly recommend you run before launching Visual
Studio from a command prompt.
These values correspond to Visual Studio 20xx:
TargetVisualStudioVersion | VS version name |
---|---|
v8.0 | 2005 |
v9.0 | 2008 |
v10.0 | 2010 |
v11.0 | 2012 |
v12.0 | 2013 |
v14.0 | 2015 |
v15.0 | 2017 |
v16.0 | 2019 |
See the comments in SetupEnvironment.bat for additional details on how the options are used.
The project files (.csproj
, etc) are multitargeted to work correctly
in Visual Studio 2005 and higher. However, the solution files (.sln
)
have slightly different formats in each VS version. If you open a
VS2005 solution file in VS2008 then you will be prompted to
upgrade. *.VS2008.sln
files are provided as companions to all
*.sln
files for use in VS2008, and you will find corresponding
.sln
files for each successive version of VisualStudio. However, the
*.VS2008.sln
files are not sufficient for successfully building in
VS2008 (etc).
You must set the TargetVisualStudioVersion
to the correct version
(listed above) before opening a NORMA project file from any of the
Visual Studio IDE environments. There is also registry information
that needs to be set so that the ToolsVersion
setting the project
files match the target environment. The easiest way to do this (after
the initial batch files mentioned above have completed successfully)
is with the following steps. You may want to put these steps into an
easily accessible batch file. The example given is for Visual Studio
2008, but 2010, 2012, 2013, and 2015 work similarly.
VS2008.bat
batch file in the command prompt. Each of
these batch files (matching the VS20xx
environment you're
opening) do two things. First, it sets the
TargetVisualStudioVersion variable to the appropriate
value. Second, it updates the registry to copy the contents of the
tools version matching your system to the tools version
12.34
. All of the NORMA .csproj
files use
ToolsVersion="12.34"
(a fake number), and modifying the contents
of the corresponding registry key allows the same .csproj
file to
be used for all of the visual studio versions.devenv ORMPackage.VS2008.sln
VS2015 builds are exhibiting an additional issue where the VSCT.exe
file used during the build cannot load VSCTCompress.dll
. The only
current solution for this is to include the directory containing this
file on your path. With the Visual Studio SDK installed you should
have an environment variable call VSSDK140Install
. The VSCT
directory is %VSSDK140Install%\VisualStudioIntegration\Tools\Bin
. The
VS2015.bat
file has been extended to automatically extend the path
in your local command prompt as needed (be sure to run as an admin or
the batch file will not complete).
To build from the command line for VS2008:
VS2008.bat
(BuildVS2008.bat
, etc)After getting a new drop, we recommend you use Build /t:Rebuild
(or
BuildVS2008 /t:Rebuild
) to update your files.
You can build the VS2005 pieces using a VS2008 SDK installation (plus
a handful of files) by defining the TargetVisualStudioVersion=v8.0
environment variable before running a *VS2008
batch file. The exact
details of this approach are still being worked out, but you should
only need to do this if you are building installation packages.
The general directions are the same as for the VS2008 approach (open a
Visual Studio 2010 Command Prompt, navigate to the NORMA directory,
set TargetVisualStudioVersion=v10.0
, and use the VS2010 solutions
and batch files).
The general directions are the same as for the VS2008 approach (open a
Visual Studio 2012 Command Prompt, navigate to the NORMA directory,
set TargetVisualStudioVersion=v11.0
, and use the VS2012 solutions
and batch files).
The installation process on VS2012 is not as easy as on VS2010, which
simply required extension files to be copied into place. You will
likely to need run devenv /setup
for VS2012 regardless of what you
do with the Visual Studio installations. See additional readme
information in the (VSIXInstall/VS2012)[VSIXInstall/VS2012] directory.
The general directions are the same as for the VS2008 approach (open a
Visual Studio 2013 Command Prompt, navigate to the NORMA directory,
set TargetVisualStudioVersion=v12.0
, and use the VS2013 solutions
and batch files).
The installation process on VS2013 is not as easy as on VS2010, which
simply required extension files to be copied into place. You will
likely to need run devenv /setup
for VS2013 regardless of what you
do with the Visual Studio installations. See additional readme
information in the (VSIXInstall/VS2013](VSIXInstall/VS2013) directory.
If NORMA is not functioning after the first dev build (the first clue will be in the file new dialog, which will simply say 'ORMModel' instead of 'Object-Role Modeling File') then you will need to reset the VSIX installation following the directions from the readme in the VSIXInstall/VS2013 directory. This should be required only after the first build, or in situations indicated in the readme.
The general directions are the same as for the VS2008 approach (open a
Visual Studio 2015 Command Prompt, navigate to the NORMA directory,
set TargetVisualStudioVersion=v14.0
, and use the VS2015 solutions
and batch files).
The installation process on VS2015 is not as easy as on VS2010, which
simply required extension files to be copied into place. You will
likely to need run devenv /setup
for VS2015 regardless of what you
do with the Visual Studio installations. See additional readme
information in the (VSIXInstall/VS2015](VSIXInstall/VS2015) directory.
If NORMA is not functioning after the first dev build (the first clue will be in the file new dialog, which will simply say 'ORMModel' instead of 'Object-Role Modeling File') then you will need to reset the VSIX installation following the directions from the readme in the VSIXInstall/VS2015 directory. This should be required only after the first build, or in situations indicated in the readme.
The build and installation process for VS2015 (and earlier) and VS2017 (and later) is radically different because of the side-by-side installation support introduced with VS2017. When NORMA is installed through the Visual Studio Marketplace installer it will be installed for all users, which means it will appear in all Visual Studio instances. However, as a developer you will be developing NORMA in a Visual Studio instance, so you don't can't have NORMA running in that instance while you develop it. If you already have NORMA installed as an extension please uninstall it.
VS2017.bat
or VS2019.bat
, which will fail with instructions on how to create a VS20xxInstallation.bat file. Following the instructions, then run VS20xx.bat
again. In earlier VS versions built NORMA files will be under the C:\Program Files (x86)\ORM Solutions
directory. With the side-by-side installs, the location will be based on the VS version and (15.0 for VS2017, 16.0 for VS2019) and the VisualStudioInstallSuffix you just set. For example, my install suffix for VS2019 is f5148b42, so the build NORMA files install under the %localappdata%\Microsoft\VisualStudio\16.0_f5148b42Exp\ORM Solutions\Natural ORM Architect
directory. The exact install directory is based on the git version--you can run NORMAGitVer.bat
to see it. Note that the schema files will be copied to the Visual Studio installation, which is why you need to be running as an administrator.FirstTimeBuildVS20xx /t:Rebuild
. Note that this step usually does not have to be rerun. However, if you have problems after updating your Visual Studio installation try rerunning this.BuildVS20xx /t:Rebuild
to finish the NORMA build. This will build everything, including creating the .vsix project, which automatically writes to your Exp registry to install the product. If you are building individual components you do not need to rerun this step unless you do a git pull or commit that changes the result of NORMAGitVer. If this happens and you do not rebuild, then the other projects will writer to the new version while the registry is still pointing to the version when you last ran this.devenv ORMPackage.VS20xx.sln
from your command prompt will now let you build the core package, with similar packages for other extensions. There is no central solution that builds them all together, just the BuildVS20xx.bat
.Note that the Setup directory is no longer used for VS2017 and above, so you will not see BuildSetup or BuildAll batch files for the newer versions.
At this point, the basic protocol is much simpler:
VS20xx
(xx matching your VS version).devenv WHATEVER.VS20xx.sln
where xx again matches your version. If you get the wrong solution file you'll get a solution upgrade warning message. Just cancel and try with the solution file that matches your Visual Studio version. Just remember that you need to launch the VS version to open these projects from inside an environment where you've run the correspond VS20xx
batch file--you can't just double click them in your file explorer. Buildvs20xx /t:Rebuild
to reset the registry with the right version, and rerun BuildDevToolsVS20xx /t:Rebuild
if you see any build issues.Note that if you need to regenerate .dsl files you will need to make some modifications to the Microsoft-installed .tt generators for the DSL library. Please contact mcurland@live.com for instructions on how to do this. You will not need this unless you modify a .dsl file.