This Visual Studio Add-in integrates SubSonic with Visual Studio 2005. You can now generate your DAL directly in your solution with a simple click. The Add-in can generate one single file or multiple files from a SubSonic .abp file. It can also generate multiple files from a tables/views/sps selection for one or multiple providers. Finally, the Add-in works for any kind of project, be it a Web Application project, EXE or DLL.

Which Tool to Use?
A few tools can be used to generate code with SubSonic.ASP.NET Build Provider: generates code in memory for Web projects only; use it if you don’t need to have concrete code files.

SubSonic Add-in: this is a Visual Studio Add-in and the best way to integrate SubSonic in Visual Studio for non-Web projects or for VS 2003-like Web Application projects.
SubSonic Custom Tool: alternative to the Add-in if you want to generate your DAL in a single file.
SubSonic Macros: the macros were developed before the Add-in and provide the same features, but from the Macro Explorer.

Sonic.exe: this is a command-line tool that integrates nicely with Web projects (not VS 2003-like Web Application projects). It doesn’t support Enterprise Library.

Breaking Changes from v1.0.6 to v2.0
SubSonic has changed a lot since the 1.0.6 version. The migration procedures can be found on the SubSonic web site or in the forums.

Most important changes:
o Configuration
• Most of the attributes in the .config file have been moved from the SubSonicService element to each individual provider.• SubSonic.config (for DLL) has changed; we now use the .NET ‘configSource’ attribute (see the installation section for more information).
o .abp file
• The content of the .abp file is now ignored; we now use the includeTableList and excludeTableList configuration attributes.
o Templates
• SubSonic uses brand new templates; they are compiled at generation time.

Installation
1. Close all instances of Visual Studio 2005.
2. If you previously installed the SubSonic Custom Tool or the SubSonic Macros, it is recommended to uninstall them by removing the SubSonic files from:
\Program Files\Microsoft Visual Studio 8\Common7\IDE\PublicAssemblies
Proceed with care, because some of these files may be used by other public assemblies.
Usually, these files are:• SubSonic.dll
• SubSonicCustomTool.dll
• SubSonicEnvDTE.dll
• SubSonicHost.dll
• Microsoft.Practices.EnterpriseLibrary.Common.dll
• Microsoft.Practices.EnterpriseLibrary.Data.dll
• Microsoft.Practices.ObjectBuilder.dll
• Microsoft.VisualStudio.BaseCodeGeneratorWithSite.dll
• Microsoft.VisualStudio.BaseCodeGeneratorWithSite.tlb• MySql.Data.dll
3. Run the SubSonicAddInSetup.msi file.
You can then unload/reload the Add-in in Visual Studio from Tools\Add-in Manager.

Configuration
Configuring the Tool for a Web Project

This section assumes you are already familiar with SubSonic configuration.
o The only difference from using SubSonic with the ASP.NET Build Provider is that you must remove it from in the Web.config.
Configuring the Tool for an EXE (WinForms, etc.)
This section assumes you are already familiar with SubSonic configuration.
o The only difference from using SubSonic in Web Applications is that you put the content of the Web.config in the App.config of your EXE instead. You only need to use the configSections, connectionStrings and SubSonicService sections; system.web won’t be used by the Tool.Configuring the Tool for a DLL
This section assumes you are already familiar with SubSonic configuration.
o The only difference from using SubSonic in Web Applications is that you put the content of the Web.config in the App.config of your DLL instead. You only need to use the configSections, connectionStrings and SubSonicService sections; system.web won’t be used by the Tool.
Then, when you use your DAL DLL in another project, you copy the content of the App.config file to the new project configuration file.
o Configuration alternative: since your DAL DLL may be used by many applications, it could be handy to have a way to deploy SubSonic configuration without having to copy the content of the DLL App.config file in every application. This can be achieved by using the .NET ‘configSource’ attribute:




After that, you can set your specific .config files ‘Copy to the Output Directory’ property to ‘Copy if newer’. This will copy your files alongside your DAL DLL when you reference it in another project. Then, in your new application configuration file, you reference the packaged configuration files the same way you did in the DLL App.config file. From now on, all changes you make to the SubSonic configuration will be deployed automatically at compile time.
Note that some project types may not automatically copy the file and you may have to resort to post-build events to automate this.
Running the SubSonic Add-in for Visual Studio
This section assumes you are already familiar with SubSonic .abp files and configuration.
There’re currently 3 actions you can take. You must right-click on a folder, an .abp file or a project in the Solution Explorer. Then select the SubSonic action you want to take.


Generate Single File
Generates the DAL in one file as a sub-item of a folder or a sub-file of an .abp file for non-web projects; for web projects, it will put the file in the same folder as the .abp file (Visual Studio doesn’t support sub-items in web projects). This action is not available at the project item level.

Generate Multiple Files
Generates the DAL in multiple files as sub-items of a folder/project or as sub-files of an .abp file for non-web projects; for web projects, it will put the files in the same folder as the .abp file (Visual Studio doesn’t support sub-items in web projects).




Generate From Selection
This is the coolest action! It opens up the following dialog, which enables you to select the providers, tables, views and optionally the stored procedures you want to generate.





The dialog will generate the DAL in multiple files as sub-items of a folder/project or as sub-files of an .abp file for non-web projects; for web projects, it will put the files in the same folder as the .abp file (Visual Studio doesn’t support sub-items in web projects).

How this works
There’re a few things to keep in mind when using the Add-in.
o For web application projects and when the DAL is generated from a selection (that is, when the generated files are not sub-items of a SubSonic .abp file), the Add-in uses a file-based algorithm to detect files that must be deleted or renamed. The algorithm uses the file prefix to detect related files (in the sample image above, it would be “DAL”). It is then recommended that you do not manually create files with the same prefix in the folder of the generated files. Either way, the macros always asks you before deleting or renaming files.
o Renaming events are not handled for .abp files of web application projects.
o Renaming events are not handled if the project is itself renamed and the DAL was generated from the project.
o DAL must be regenerated manually if the configuration file is modified.
About the SubSonic Code Templates
This section assumes you are already familiar with SubSonic code templates.
o You can use a relative path in the configuration file to specify the template directory; the path must start with "." or ".\". Moving up the parent hierarchy is not allowed.
o By default, the Tool generates insert and update code that uses System.Web.HttpContext.Current.User.Identity.Name and System.Threading.Thread.CurrentPrincipal.Identity.Name. Some generated methods may also make use of System.Web classes. If you don’t want to have to add a reference to System.Web in your project, you will have to provide your own templates.
Using your DAL
It is recommended to reference the SubSonic.dll that comes with the Tool in the projects where you use your DAL, since the Tool was build using that specific version of SubSonic.