-
Do you have a consistent .NET Solution Structure?
When developing a n-tiered software solution, we follow a standard solution structure.
We have incorporated unit testing components, which is an integral part of the Extreme
Programming development methodology, into our solution structure:
|
Project Type |
Project Name |
|
Note |
|
Application |
Northwind |
|
Namespace: |
SSW.Northwind |
|
Folder: |
SSW\Northwind\Northwind\ |
|
Output: |
Northwind.exe |
|
|
|
Class Library |
WindowsUI |
|
Namespace: |
SSW.Northwind.WindowsUI |
|
Folder: |
SSW\Northwind\WindowsUI\ |
|
Folder: |
SSW\Northwind\WindowsUI\Components |
|
Folder: |
SSW\Northwind\WindowsUI\UnitTests |
|
Output: |
WindowsUI.dll |
|
We put all the forms in a separate project so we can run Unit Tests on the UI using
reflection. |
|
Application |
ConsoleUI |
|
Namespace: |
SSW.Northwind.ConsoleUI |
|
Folder: |
SSW\Northwind\ConsoleUI\ |
|
Folder: |
SSW\Northwind\ConsoleUI\Components |
|
Folder: |
SSW\Northwind\ConsoleUI\UnitTests |
|
Output: |
NorthwindConsole.exe |
|
|
|
Application |
WebUI |
|
Namespace: |
SSW.Northwind.WebUI |
|
Folder: |
SSW\Northwind\WebUI\ |
|
Folder: |
SSW\Northwind\WebUI\Components |
|
Folder: |
SSW\Northwind\WebUI\UnitTests |
|
Output: |
SSW.Northwind.WebUI.dll |
|
|
|
|
|
|
Namespace: |
SSW.Northwind.WebUI.Reports |
|
Folder: |
SSW\Northwind\WebUI\Reports\ |
|
Manually-based reports - e.g. using the DataGrid |
|
|
|
|
Namespace: |
SSW.Northwind.WebUI.Components |
|
Folder: |
SSW\Northwind\WebUI\Components\ |
|
Part of WebUI. For .css and .ascx user controls |
|
Windows Service |
WindowsService |
|
Namespace: |
SSW.Northwind.WindowsService |
|
Folder: |
SSW\Northwind\WindowsService\Components |
|
Folder: |
SSW\Northwind\WindowsService\UnitTests |
|
Output: |
SSW.Northwind.WindowsService.dll |
|
|
|
RS Reports |
Reports |
|
Namespace: |
N/A |
|
Folder: |
SSW\Northwind\Reports |
|
Output: |
N/A |
|
Reporting Services |
|
Class Library |
IServices |
|
Namespace: |
SSW.Northwind.IServices |
|
Folder: |
SSW\Northwind\IServices |
|
Folder: |
SSW\Northwind\IServices\UnitTests |
|
Output: |
SSW.Northwind.IServices.dll |
|
WCF Services Interfaces |
|
Class Library |
Services |
|
Namespace: |
SSW.Northwind.Services |
|
Folder: |
SSW\Northwind\Services |
|
Folder: |
SSW\Northwind\Services\UnitTests |
|
Output: |
SSW.Northwind.Services.dll |
|
WCF Services Implementations |
|
Class Library |
Business |
|
Namespace: |
SSW.Northwind.Business |
|
Folder: |
SSW\Northwind\Business\ |
|
Folder: |
SSW\Northwind\Business\Components |
|
Folder: |
SSW\Northwind\Business\UnitTests |
|
Output: |
SSW.Northwind.Business.dll |
|
This can be code-generated |
|
Class Library |
Domain |
|
Namespace: |
SSW.Northwind.Domain |
|
Folder: |
SSW\Northwind\Domain |
|
Folder: |
SSW\Northwind\Domain\UnitTests |
|
Output: |
SSW.Northwind.Domain.dll |
|
LINQ DBML - this can be generated using SQL Metal |
|
Class Library |
DataSets |
|
Namespace: |
SSW.Northwind.DataSets |
|
Folder: |
SSW\Northwind\DataSets\ |
|
Folder: |
SSW\Northwind\DataSets\UnitTests |
|
Output: |
SSW.Northwind.DataSets.dll |
|
Strongly typed datasets - this can be code-generated |
|
Class Library |
DataAccess |
|
Namespace: |
SSW.Northwind.DataAccess |
|
Folder: |
SSW\Northwind\DataAccess\ |
|
Folder: |
SSW\Northwind\DataAccess\Components |
|
Folder: |
SSW\Northwind\DataAccess\UnitTests |
|
Output: |
SSW.Northwind.DataAccess.dll |
|
This project should contain all the code and SQL statements used to access data from your backend. This project can be code-generated |
|
Class Library |
UnitTests |
|
Namespace: |
SSW.Northwind.UnitTests |
|
Folder: |
SSW\Northwind\UnitTests\ |
|
Output: |
SSW.Northwind.UnitTests.dll |
|
Only need this project if you are not using reusable components and then you do
not need UnitTests folders above |
|
Wise Setup |
Northwind |
|
Folder: |
SSW\Northwind\Setup\ |
|
Output: |
SSWNorthwind_v1-11.exe |
|
Make an EXE in Wise intead of an MSI because it allows the application to be upgraded
|
We have included the unit tests with the project the test is designed for together
into one assembly for several reasons:
- It provides a logical association between the test and the class it is designed
to test, promoting consistency between the two.
- Ease of management - we don't need to match test assembly with the actual assembly
by file naming standards, the association is inherent.
- There are less projects to compile in a solution.
For common library project, project name should include the company prefix and solution
name, this is so other internal solution can include the common library's project.
This will help debugging and development processes.
|
Project Type |
Project Name |
|
Note |
|
Class Library |
SSWCommon Business |
|
Namespace: |
SSW.Common.Business |
|
Folder: |
..\SSW\Common\Business\ |
|
Output: |
SSW.Common.Business.dll |
|
No space in the Project Name |
For project documents, we should also add them into solution for later reference, and different document types should be put in different folder, e.g. Artworks' files should be in SSW\Documents\ArtWorks\
|
Project Type |
Project Name |
|
Note |
|
Documents |
Documents |
|
This is outside the solution trunk |
-
Do you name your startup form consistently?
In every Windows application project. We need to have a main form for a better structure
and design.
-
-
Bad example - The entry form is not immediately recognizable because of a non standard
name
-
-
Good example - The entry form follows the naming convention rule
|
We have a program called SSW Code
Auditor to check for this rule.
Note: In Code Auditor we check for Form named: Startup, MainService, MainForm and
WizardPage.
|
-
Do you have a structured Solution Folders
for your solution items?
All the DLL references and files needed to create a setup.exe should be included
in your solution. However, just including them as solution items isnt enough, they
will look very disordered (especially when you have a lot of solution items). And
from the screenshot below, you might be wondering what the _Instructions.txt is
used for...
-
-
Bad example - An unstructured solution folder
An ideal way is to create "sub-solution folders" for the solution items, the common
ones are "References" and "Setup". This feature is only available in Visual Studio
2005. This will make your solution items look neat and in order. Look at the screenshot
below, now it makes sense, we know that the _Instructions.txt contains the instructions
of what to do when creating a setup.exe.
-
-
Good example - A well structured solution folder has 2 folders - "References" and
"Setup"
-
Do you always say "Option Strict On"?
Fixing the Option Strict problem One of the most annoying aspects of the Visual
Basic development environment relates to Microsofts decision to allow late binding.
By turning Option Strict Off by default, many type-casting errors are not caught
until runtime. You can make VB work the same as other MS languages (which always
do strict type-checking at design time) by modifying these templates.
So, always set Option Strict On right from the beginning of the development.
Before you do this, you should first back up the entire VBWizards directory. If
you make a mistake, then the templates will not load in the VS environment. You
need to be able to restore the default templates if your updates cause problems.
To configure each template to default Option Strict to On rather than Off, load
each .vbproj template with VB source code into an editor like Notepad and then change
the XML that defines the template. For example, to do this for the Windows Application
template, load the file: Windows Application\Templates\1033\WindowsApplication.vbproj
under the VBWizards directory into Notepad and find the settings Element. You should
see something like this:
<VisualStudioProject>
<VisualBasic>
<Build>
<Config . . . .
Now, add the following lines under OutputType: OptionStrict = "On" OptionExplicit
= "On"
Or you go to Project property page as you can see the snapshot below and change
to Option Strict = "On", OptionExplicit = "On".
-
Technically, you do not have to add the Option Explicit directive, because this
is the default for VB; but I like to do it for consistency. Next, you must save
the file and close Notepad. Now, if you load a new Windows Application project in
the VS environment and examine Project Properties, you will see that Option Strict
has been turned on by default.
In order for this setting to take effect for all project types, you must update
each of the corresponding .vbproj templates. After making the changes on your system,
youll need to deploy the new templates to each of your developers' machines in order
for their new projects to derive from the updated templates.
However, sometimes we don't do this because of too much work. In some scenarios,
such as Wrappers around the COM code, and Outlook stuff with object model, there
is going to be lots of work to fix all the type-checking errors. Actually it is
necessary to use Object type as parameters or variables when you deal with COM components.
.NET Standards in ZDNet
-
Do you keep clean on Imports of Project Property?
When programming in a Dot Net environment it is a good practice to remove the default
imports that aren't used frequently in your code.
This is because IntelliSense lists will be harder to use and navigate with too many
imports. For example if in VB.NET, Microsoft.VisualBasic would be a good item to
have in the imports list, because it will be used in most areas of your application.
To remove all the default imports, load Project Property page and select Common
properties - Imports.
-
Using Aliases with the Imports Statement :
The Imports statement makes it easier to access methods of classes by eliminating
the need to explicitly type the fully qualified names of references. Aliases let
you assign a friendlier name to just one part of a namespace.
For example, the carriage return-line feed sequence that causes a single piece of
text to be displayed on multiple lines is part of the ControlChars class in the
Microsoft.VisualBasic namespace. To use this constant in a program without an alias,
you would need to type the following code:
-
MsgBox("Some text" & Microsoft.VisualBasic.ControlChars.crlf _ &
"Some more text")
Imports statements must always be the first lines immediately following any Option
statements in a module. The following code fragment shows how to import and assign
an alias to the Microsoft.VisualBasic.ControlChars namespace:
-
Imports CtrlChrs=Microsoft.VisualBasic.ControlChars
Future references to this namespace can be considerably shorter:
-
MsgBox("Some text" & CtrlChrs.crlf & "Some more text")
If an Imports statement does not include an alias name, elements defined within
the imported namespace can be used in the module without qualification. If the alias
name is specified, it must be used as a qualifier for names contained within that
namespace.
Figure: Using aliases with the Imports Statement
-
Do you add the necessary code so you can always sync the
web.config file?
The Web.config file should be your main source where you store your application
settings. These change, depending on which system you are working on, e.g. your
local machine or the website. That's why you have to keep two versions of the
Web.config file, one for your local machine and one for the website.
That's annoying, not really efficient and often the cause of problems.
In the following extract of a sample Web.config file you can see the problem. The
local machine "HIPPO" has, of course, another WebServiceURL than the Webserver
"SEAL". So you have to keep two versions of the Web.config file, one when
working on "HIPPO" and one when working on "SEAL".
<add key="SEAL_WebServiceURL" value="http://host.something.com:80/SomeDirectory/Filename.asmx"/>
<add key="HIPPO_WebServiceURL"value="http://name:80/SomeDirectory/Filename.asmx"/>
Figure: Sample Web.config file
There is a better solution:
Public Shared Function GetWebConfigString(ByVal StringName As String) As String
Dim strReturn As String = ""
Dim strComputerName As String = System.Net.Dns.GetHostName
Try
strReturn = ConfigurationSettings.AppSettings( strComputerName.ToUpper + "_"+ StringName)
Catch
strReturn = ConfigurationSettings.AppSettings(StringName)
End Try
Return strReturn
End Function
Figure: Sample Get WebConfigString Class
This class simply adds the name of the Computer on which it is running on to the
WebConfigString. In the former example, this would be "HIPPO_" or "SEAL_".
Instead of using the WebConfigString directly you can now transform it using this
function. With the help of this code, you always get the right value for the WebConfigString,
no matter on which machine the application runs and you don't have to care about
synchronizing the Web.config file any more.
Do you avoid periods (.) in directory names?
We've elected to not allow periods in directory name, primarily because it creates
problems with Windows' auto-complete intellisense.
|
C:\Bad.Example.With.Periods\
|
Figure: Bad example of directory name with periods (.)
|
C:\Good Example Without Periods\
|
Figure: Good example of directory name without periods (.)
-
Do you name your assemblies consistently (<CompanyName>.<ComponentName>)?
Assembly names should reflect the the functionality that it provides.
For example,
-
System.IO
contains all the classes that deal
with inputs and outputs. As a general rule of thumb your assemblies
should be named as follows:
<CompanyName>.<ComponentName> (e.g. SSW.Framework)
This allows a developer to know who developed the assembly and give the developer a general idea of what the assembly can be used for.
-
Do you use the designer for all visual elements?
The designer should be used for all GUI design. Controls should be
dragged and dropped onto the form and all properties should be set in the
designer, e.g.
- Labels, TextBoxes and other visual elements
- ErrorProviders
- DataSets (to allow data binding in the designer)
Things that do not belong in the designer:
- Connections
- Commands
- DataAdapters
However, and DataAdapter objects should not be dragged
onto forms, as they belong in the business tier. Strongly typed DataSet
objects should be in the designer as they are simply passed to the business
layer. Avoid writing code for properties that can be set in the designer.
-
- Bad example - Connection and Command objects in the Designer
-
- Good example - Only visual elements in the designer
-
Do you refer to images the correct way in ASP .NET?
There are many ways to reference images in ASP.NET. There are two different situations
commonly encountered by developers when working with images:
- Scenario #1: Images that are part of the content of a specific page eg. a picture
used only on one page
- Scenario #2:Images that are shared across on user controls which are shared across
different pages in a site eg. a shared logo used across the site (commonly in user
controls, or master pages)
Each of these situations requires a different referencing method.
Option #1:Absolute Paths (Root-Relative Paths)
Often developers reference all images by using an absolute path (prefixing the path
with a slash, which refers to the root of the site), as shown below.
<img src="/Images/spacer.gif" height="1" width="1">
- Bad example - Referencing images with absolute paths
This has the advantage that <img> tags can easily be copied between pages,
however it should not be used in either situation, because it requires that the
website have its own site IIS and be placed in the root (not just an application),
or that the entire site be in a subfolder on the production web server. For example,
the following combinations of URLs are possible with this approach:
|
Staging Server URL |
Production Server URL |
|
http://bee:81/ |
http://www.ssw.com.au/ |
|
http://bee/ssw/ |
http://www.ssw.com.au/ssw/ |
As shown above, this approach makes the URLs on the staging server hard to remember,
or increases the length of URLs on the production web server.
Verdict for Scenario #1:
Verdict for Scenario #2:
Option #2:Relative Paths
Images that are part of the content of a page should be referenced using relative
paths, e.g.
-
<img src="../Images/spacer.gif" height="1" width="1">
- Good example - Referencing images with absolute paths.
However, this approach is not possible with images on user controls, because the
relative paths will map to the wrong location if the user control is in a different
folder to the page.
Verdict for Scenario #1:
Verdict for Scenario #2:
Option #3:Application-Relative Paths
In order to simplify URLs, ASP.NET introduced a new feature, application relative
paths. By placing a tilde (~) in front of a path, a URL can refer to the root of
a site, not just the root of the web server. However, this only works on Server
Controls (controls with a runat="server" attribute).
To use this feature, you need either use ASP.NET Server controls or HTML Server
controls, as shown below.
-
<asp:Image ID="spacerImage" ImageUrl="~/Images/spacer.gif"
Runat="server" />
<img id="spacerImage" src="~/Images/spacer.gif" runat="server">
- Good example - Application-relative paths with an ASP.NET Server control
Using an HTML Server control creates less overhead than an ASP.NET Server control,
but the control does not dynamically adapt its rendering to the user's browser,
or provide such a rich set of server-side features.
Verdict for Scenario #1:
Verdict for Scenario #2:
Note:A variation on this approach involves calling the Page.ResolveUrl method with
inline code to place the correct path in a non-server tag.
-
<img src='<%# Page.ResolveUrl("~/Images/spacer.gif") %>'>
- Bad example - Page.ResolveUrl method with a non-server tag
This approach is not recommended, because the data binding will create overhead
and affect caching of the page. The inline code is also ugly and does not get compiled,
making it easy to accidentally introduce syntax errors.
-
Do you use Microsoft.VisualBasic.dll for Visual Basic.NET projects?
The Microsoft.VisualBasic library is provided to ease the implementation of the
VB.NET language itself. For VB.NET, it provides some methods familiar to the VB
developers and can be seen as a helper library. It is a core part of the .NET redistribution
and maps common VB syntax to framework equivalents, without it some of the code
may seem foreign to VB programmers.
|
Microsoft.VisualBasic |
.NET Framework |
|
CInt, CStr |
Convert.ToInt(...), ToString() |
|
vbCrLf |
Environment.NewLine, or "\r\n" |
|
MsgBox |
MessageBox.Show(...) |
-
Do you avoid Microsoft.VisualBasic.Compatibility.dll
for Visual Basic.NET projects?
This is where you should focus your efforts on eliminating whatever VB6 baggage
your programs or developer habits may carry forward into VB.NET. There are better
framework options for performing the same functions provided by the compatibility
library You should heed this warning from the VS.NET help file: Caution: It is
not recommended that you use the VisualBasic.Compatibility namespace for new development
in Visual Basic .NET. This namespace may not be supported in future versions of
Visual Basic. Use equivalent functions or objects from other .NET namespaces instead.?
ad.?
Avoid:
- InputBox
- ControlArray
- ADO support in Microsoft.VisualBasic.Compatibility.Data
-
Environment functions
- Font conversions
-
Do you have a build/integration machine for shared components?
There should be one compiled set of shared components.
-
Do you publish your components to Source Safe?
Incrementally as we do more and more .NET projects, we discover that we are re-doing
a lot of things we've done in other projects. How do I get a value from the
config file? How do I write it back? How do I handle all my uncaught exceptions
globally and what do I do with them?
Corresponding with Microsoft's release of their application blocks, we've
also started to build components and share them across projects.
Sharing a binary file with SourceSafe isn't a breeze to do, and here are the
steps you need to take. It can be a bit daunting at first.
As the component developer, there are four steps:
- In Visual Studio.NET, Switch to release build
-
Figure: Switch to release configuration
- In your project properties, make sure the release configuration goes to the bin\Release?
folder. While you are here, also make sure XML docs are generated. Use the same
name as your dll but change the extension to .xml (eg. for SSW.Framework.Configuration.dll
-> add SSW.Framework.Configuration.xml)
-
Figure: Project properties
Note: The following examples are considered being used for C#. Visual Basic, by
default, does not have \bin\Release and \bin\Debug which which means that the debug
and release builds will overwrite each other unless the default settings are changed
to match C# (recommended). VB does not support XML comments either, please wait
for the next release of Visual Studio (Whidbey).
-
Figure: Force change to match C#
- If this is the first time, include/check-in the release directory into your SourceSafe
Figure: Include the bin\Release directory into source safe
- Make sure everythings checked-in properly. When you build new versions, switch
to Release?mode and checkout the release dlls, overwrite them, and when you check
them back in they will be the new dll shared by other applications.
-
If the component is part of a set of components, located in a solution, with some
dependency between them. You need to check out ALL the bin\Release folders for all
projects in that solution and do a build. Then check in all of them. This will ensure
dependencies between these components don't conflict with projects that reference
this component set.
In other words, a set of components such as SSW.Framework.WindowsUI.xxx, increment
versions AS A WHOLE. One component in this set changes will cause the whole set
to re-establish internal references with each other.
-
Do you reference "most" .dlls by Project?
When you obtain a 3rd party .dll (in-house or external), you sometimes get the code
too. So should you:
- reference the Project (aka including the source) or
- reference the assembly?
When you face a bug, there are 2 types of emails you can send:
- Dan, I get this error calling your Registration.dll? or
- Dan, I get this
error calling your Registration.dll and I have investigated it. As per our conversation,
I have changed this xxx to this xxx.
The 2nd option is preferable.
The simple rule is:
If there are no bugs then reference the assembly, and
If there are bugs in the project (or any project it references [See note below])
then reference the project.
Since most applications have bugs, therefore most of the time you should be using
the second option.
If it is a well tested component and it is not changing constantly, then use the
first option.
- Add the project to solution (if it is not in the solution).
-
Figure: Add existing project
- Select the "References" folder of the project you want to add references to, right
click and select "Add Reference...".
Figure: Add reference
- Select the projects to add as references and click OK.
Figure: Select the projects to add as references
Note: We have run into a situation where we reference a stable project A, and an
unstable project B. Project A references project B. Each time project B is built,
project A needs to be rebuilt.
Now, if we reference stable project A by dll, and unstable project B by project
according to this standard, then we might face referencing issues, where Project
A will look for another version of Project B ?the one it is built to, rather than
the current build, which will cause Project A to fail.
To overcome this issue, we then reference by project rather than by assembly, even
though Project A is a stable project. This will mitigate any referencing errors.
-
Do you reference "very calm/stable" .dlls by Assembly?
If we lived in a happy world with no bugs, I would be recommending this approach
of using shared components from source safe. As per the prior rule, you can see
we like to reference "most" .dlls by project.
However if you do choose to reference a .dll without the source, then the important
thing is that if the .dll gets updated by another developer, then there is *nothing*
to do for all other developers ?they get the last version when they do your next
build. Therefore you need to follow this:
As the component user, there are six steps, but you only need to do them once:
- First, we need to get the folder and add it to our project, so in SourceSafe, right
click on your project and create a subfolder using the Create Project (yes, it
is very silly name) menu.
-
Figure: Create 'folder' in Visual Source Safe
Name it References-
Figure: 'References' folder
- Share the dll from the directory, so if I want SSW.Framework.Configuration, I go
to $/ssw/SSWFramework/Configuration/bin/Release/
I select both the dll and the dll.xml files, right-click and drag them into my $/ssw/zzRefs/References/
folder that I just created in step 1.-
Figure: Select the dlls that I want to use
-
Figure: Right drag, and select "Share"
- Still in SourceSafe, select the References folder, run get latest?to copy the latest
version onto your working directory.
-
Figure: Get Latest from Visual Source Safe
VSS may ask you if you want to create the folder, if it doesnt exist. Yes, we do.
- Back in VS.NET, select the project and click on the show-all files button in the
solution explorer, include the References folder into the project (or get-latest
if its already there)
-
Figure: Include the files into the current project
- IMPORTANT! If the files are checked-out to you when you include them into your project,
you MUST un-do checkout immediately.
You should never check in these files, they are for get-latest only.
-
Figure: Undo Checkout, when VS.NET checked them out for you...
- Add Reference?in VS.NET, browse to the References?subfolder and use the dll there.
- IMPORTANT! You need to keep your 'References' folder, and not check the
files directly into your bin directory. Otherwise when you 'get latest',
you won't be able to get the latest shared component.
All done. In the future, whenever you do get-latest?on the project, the any updated
dlls should come down and be linked the next time you compile. Also, if anyone checks
out your project from Source Safe, they will have the project linked and ready to
go.
-
Do you keep your Assembly Version Consistent?
It is important to keep Assembly version and Assembly file version consistent,
otherwise it can lead to support and maintenance nightmares.
By default these version values are defined in the AssemblyInfo file.
In the following examples, the first line is the version of the assembly and the second line is the actual version display in file properties.
-
[assembly: AssemblyVersion("2.0.*")]
[assembly: AssemblyFileVersionAttribute("1.0.0.3")]
- Bad example - the common assembly versioning method.
-
[assembly: AssemblyVersion("2.0.*")]
[assembly: AssemblyFileVersionAttribute("2.0.*")]
- Good example - the best way for Assembly versioning.
-
Do you use configuration management application
block?
How do you get a setting from a configuration file? What do you do when you want
to get a setting from a registry, or a database? Everyone faces these problems,
and most people come up with their own solution. We used to have a few different
standards, but when Microsoft released the Configuration Application Blocks, we
have found that working to extend it and use it in all our projects saves us a lot
of time! Use a a local configuration file for machine and/or user specific settings
(such as a connection string), and use a database for any shared values such as
Tax Rates.
See how we configured this reset default settings functionality with the Configuration
Block in the .NET Toolkit
-
Do you have a resetdefault() function in your configuration
management application block?
In almost every application we have a user settings file to store the state of the
application. We want to be able to reset the settings if anything goes wrong.
See how we configured this reset default settings functionality with the Configuration
Block in the .NET Toolkit
-
Do you hard code your ConnectionString?
We don't like hard coded string inside our programme. We are using model-driven
development, in which we create or reuse code, and perform changes in configuration
file rather the in-code changing. More information on implementing
our configuration.
-
connection.ConnectionString = "Provider=SQLOLEDB;
Data Source=server_name_or_address; Initial Catalog=database_name;
User ID=username; Password=password; ";
connection.Open();
- Bad code - use the lengthy connection string.
-
connection.ConnectionString = ConfigurationManager.Items["ConnectionString"];
connection.Open();
- Figure: Good Code - Use ConfigurationManager to handle the connection string.
-
You get an error message reported from a user like:
When I click the Save button on the product form it gives an error message about a missing field.
You try and reproduce it on your version in the office and everything works perfectly, you suspect that the customer probably has changed the schema. So you
start drafting an email to the user like:
Mary, I need you to send me your database schema as it might be different from what it should be. Can you:
- Open up Enterprise Manager (or SQL Management Studio)
- Open the first tree
- Open the second tree
- Select your server
- Open that tree
- Select Databases
- Open that tree
- Select the database called Northwind
- Right click on it and choose All Tasks, then Generate SQL Script
- Then select the options
- etc
- Then when I get this I will compare and I will make a script file for you to run and fix the problem
STOP! STOP! STOP!
It would be much better to just say:
Mary, click the "Reconcile" button and it will tell us what is wrong
Bottom line is the customers' database schema should always be correct and this should be managed automatically by the application.
Therefore, we always deliver an application with the buttons "Create", Upgrade" and "Reconcile", accessible via "Tools - Options"
and a "Database" tab. We do this by using SSW SQL Deploy and throwing on the inherited user-control from the SSW.SQLDeploy.Options
project.
For more information see
Best Tools for SQL Server
It looks like this
-
Figure: Showing the "Reconcile" which compares the current scripts with
the Clients database; and the "Upgrade" which will run the scripts that
have been most recently included in the latest version for the client.
On clicking "Select" another Dialog will open with the required functions
for creating a database or using an existing one as shown below:
-
Figure: Creating a New database for the client if there is no database to begin with.
-
It is good to store program settings in an .xml file. But developers rarely worry
about future schema changes and how they will inform the user it is an old schema.
What is wrong with this?
-
<?xml version="1.0" standalone="yes"?>
<NewDataSet>
<xs:schema id="NewDataSet" xmlns=""
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
<xs:element name=NewDataSet" msdata:IsDataSet="true" msdata:Locale="en-AU">
<xs:complexType>
<xs:choice maxOccurs="unbounded">
<xs:element name="Table1">
<xs:complexType>
<xs:sequence>
<xs:element name="DateUpdated" type="xs:dateTime" minOccurs="0" />
<xs:element name="NewDatabase" type="xs:boolean" minOccurs="0" />
<xs:element name="ConnectionString" type="xs:string" minOccurs="0" />
<xs:element name="SQLFilePath" type="xs:string" minOccurs="0" />
<xs:element name="TimeOut" type="xs:int" minOccurs="0" />
<xs:element name="TurnOnMSDE" type="xs:boolean" minOccurs="0" />
<xs:element name="KeepXMLRecords" type="xs:boolean" minOccurs="0" />
<xs:element name="UserMode" type="xs:boolean" minOccurs="0" />
<xs:element name="ReconcileScriptsMode" type="xs:boolean" minOccurs="0" />
<xs:element name="FolderPath" type="xs:string" minOccurs="0" /> />
<xs:element name="SelectedFile" type="xs:string" minOccurs="0" />
<xs:element name="UpdateVersionTable" type="xs:boolean" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:schema>
<Table1>
<DateUpdated>2004-05-17T10:04:06.9438192+10:00</DateUpdated>
<NewDatabase>true</NewDatabase>
<ConnectionString>Provider=SQLOLEDB.1;Integrated Security=SSPI;Persist Security Info=False;Data Source=(local);Initial Catalog=master</ConnectionString>
<SQLFilePath>ver0001.sql</SQLFilePath>
<TimeOut>5</TimeOut>
<TurnOnMSDE>false</TurnOnMSDE>
<KeepXMLRecords>false</KeepXMLRecords>
<UserMode>true</UserMode>
<ReconcileScriptsMode>true</ReconcileScriptsMode>
<FolderPath>C:\Program Files\SSW SQL Deploy\Samples\DatabaseSQLScripts\</FolderPath>
<SelectedFile />
<UpdateVersionTable>true</UpdateVersionTable>
</Table1>
</NewDataSet>
- Bad example - XML file without version control.
-
<?xml version="1.0" standalone="yes"?>
<NewDataSet>
<xs:schema id="NewDataSet" xmlns="" xmlns:xs="http:/www.w3.org/2001/XMLSchema"
xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
<xs:element name="NewDataSet" msdata:IsDataSet="true" msdata:Locale="en-AU">
<xs:complexType>
<xs:choice maxOccurs="unbounded">
<xs:element name="Table1">
<xs:complexType>
<xs:sequence>
<xs:element name="Version" type="xs:string" minOccurs="0" />
<xs:element name="DateUpdated" type="xs:dateTime" minOccurs="0" />
<xs:element name="NewDatabase" type="xs:boolean" minOccurs="0" />
<xs:element name="ConnectionString" type="xs:string" minOccurs="0" />
<xs:element name="SQLFilePath" type="xs:string" minOccurs="0" />
<xs:element name="TimeOut" type="xs:int" minOccurs="0" />
<xs:element name="TurnOnMSDE" type="xs:boolean" minOccurs="0" />
<xs:element name="KeepXMLRecords" type="xs:boolean" minOccurs="0" />
<xs:element name="UserMode" type="xs:boolean" minOccurs="0" />
<xs:element name="ReconcileScriptsMode" type="xs:boolean" minOccurs="0" />
<xs:element name="FolderPath" type="xs:string" minOccurs="0" />
<xs:element name="SelectedFile" type="xs:string" minOccurs="0" />
<xs:element name="UpdateVersionTable" type="xs:boolean" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:schema>
<Table1>
<Version>1.2</Version>
<DateUpdated>2004-05-17T10:04:06.9438192+10:00</DateUpdated>
<NewDatabase>true</NewDatabase>
<ConnectionString>Provider=SQLOLEDB;Integrated Security=SSPI;Data Source=(local);Initial Catalog=master</ConnectionString>
<SQLFilePath>ver0001.sql</SQLFilePath>
<TimeOut>5</TimeOut>
<TurnOnMSDE>false</TurnOnMSDE>
<KeepXMLRecords>false</KeepXMLRecords>
<UserMode>true</UserMode>
<ReconcileScriptsMode>true</ReconcileScriptsMode>
<FolderPath>C:\Program Files\SSW SQL Deploy\Samples\DatabaseSQLScripts\</FolderPath>
<SelectedFile />
<UpdateVersionTable>true</UpdateVersionTable>
</Table1>
</NewDataSet>
- Figure: XML file with version control
The version tags identifies what version the file is. This version should be hard
coded into the application. Every time you change the format of the file, you would
increment this number.
The code below shows how this would be implemented in your project.
-
Public Function IsXMLFileValid() As Boolean
Dim fileVersion As String = "not specified"
Dim dsSettings As New DataSet
Dim IsMalformed As Boolean = False ' Is the file malformed all together with possibly version
Try
dsSettings.ReadXml(mXMLFileInfo.FullName, XmlReadMode.ReadSchema)
Catch ex As Exception
IsMalformed = True
End Try
If (Not IsMalformed) Then
Dim strm As Stream = Asm.GetManifestResourceStream(Asm.GetName().Name + "." + "XMLFileSchema.xsd")
Dim sReader As New StreamReader(strm)
Dim dsXMLSchema As New DataSet
dsXMLSchema.ReadXmlSchema(sReader)
If dsSettings.Tables(0).Columns.Contains("Version") Then
fileVersion = dsSettings.Tables(0).Rows(0)("Version").ToString
End If
If fileVersion = "" Then
fileVersion = "not specified"
End If
If fileVersion = Global.XMLFileVersion AndAlso Not dsSettings.GetXmlSchema() = dsXMLSchema.GetXmlSchema() Then
Return False
End If
End If
If IsMalformed OrElse fileVersion <> Global.XMLFileVersion Then
If mShouldConvertFile Then
' Convert the file
ConvertToCurrentVersion(IsMalformed)
Else
Throw New XMLFileVersionException(fileVersion, Global.XMLFileVersion )
End If
End If
Return True
End Function
Figure: Code to illustrate how to check if the xml file is valid.
Note: to allow backward compatibility, you should give the user an option to convert
old xml files into the new version structure.
-
There are three types of settings files that we may need to use in .NET
- App.Config/Web.Config is the default .NET settings file, including any settings
for the Microsoft Application Blocks (eg. the Exception Management Block and the
Configuration Management Block). These are for settings that dont change from within
the application. In addition, System.Configuration classes dont allow writing to
this file.
- ToolsOptions.Config (an SSW standard) is the file to hold the users own settings,
that are users can change in the Tools - Options.
Eg. ConnectionString, EmailTo, EmailCC
Note: We read and write to this using Microsoft Configuration Application Block.
If we dont use this Block we would store it as a plain XML file and read and write
to it using System.XML classes. The idea is that if something does go wrong when
you are writing to this file, at least the App.Config would not be affected. Also,
this separates our settings (which are few) from the App.Config (which usually has
a lot of stuff that we really dont want a user to stuff around with).
- UserSession.Config (an SSW standard). These are for additional setting files that
the user can not change.
e.g. FormLocation, LastReportSelected
Note: This file is over writable (say during a re-installation) and it will not
affect the user if the file is deleted. &