Standards
dotnet development standards
STANDARDS
DOTNET DEVELOPMENT STANDARDS
Document type:
working
validation in progress
approved for distribution
Reference: ND_DotNetDevelopmentStandards.doc
Purpose of the document:
The purpose of this document is to describe the standards for developing an application using Microsoft's .NET technology at the CoE
This version of the document is provided as an example. The version applicable at the time of signing the contract shall be the reference.
NB: Any failure to comply with the standards or practices described in this document must be reported by the supplier prior to the start of works and validated by the Council of Europe (DIT).
This document is the property of the Council of Europe.
It may not be reproduced or communicated without the prior agreement of the author.
Contents
1.Introduction
1.1Purpose
1.2Warning signs used in this document
1.3Reference documentation
2.Choice of technology
2.1Programming language
2.2Development environment
3.Naming rules
3.1General rules
3.2Casing styles
3.3Casing of Different Development Elements
3.4Graphic controls
3.5Language Used in the Code
3.6Files
3.7Namespaces
3.8Source documentation
3.8.1General points
3.8.2Rules to follow
4.Structuring of Applications
4.1Organisation of Projects
4.1.1"Web" Projects
4.1.2"Library" Projects
4.2Organisation of the Solution
4.3Data access layer (Coe.MyProject.Dal)
4.3.1Using Entity Framework
4.3.2Using stored PROCEDURES
4.3.3Objects returned by the data access layer
4.4Business layer (Coe.MyProject.Bll)
4.5Presentation layer (Coe.MyProject.Web)
4.5.1Code factorisation
4.5.2Validation of data
4.6Localisation and globalisation
4.7Resource files
5.Parametering the application
5.1Connection strings
5.2SMTP Server
5.3Application parameters
5.3.1General points
5.3.2User manual
5.3.3Links external to the application
5.3.4Executables
6.Application robustness
6.1Optimisation
6.2Security
6.3Managing application logs
6.4Error processing
6.4.1
6.4.2
6.4.3Raising application exceptions
6.4.4Handling specific exceptions
6.4.5Handling exceptions at global level
6.4.6Error log
6.5Obsolete methods
7.ORGANIZATION OF SQL SCRIPTS
8.ORGANIZATION OF SSRS REPORTS
9.Tests and code review
9.1Setting up unit tests
9.2The Sanity Test page
10.Modules supplied by the CoE
10.1Web Service
10.1.1WS_FileManager
10.1.2WS_ADSearch
10.1.3WS_Authenticate
10.1.4Thunderstone Web Service
10.2Libraries
10.2.1Error Manager
10.3Other components
10.3.1CAS authentication module
10.3.2Access to the meta-directory via the database
11.Available resources
11.1Frameworks and Libraries
11.1.1Microsoft Ajax Library and Microsoft Ajax Toolkit
11.1.2Button preventing double clicks
11.1.3Enterprise Library
11.1.4WebService Enhancements
11.1.5Library for creating Excel documents
11.1.6Libraries for creating Pdf documents
11.1.7Library for compressing files in different Formats
11.1.8Library for creating mobile web applications running on all mobile devices, telephones etc
11.2Sample Application
1.Introduction
1.1Purpose
This document sets out the standards to be applied when developinga .Net application for the Council of Europe.
All the rules described in this document must be scrupulously complied with, and corresponding checks will be made on each delivery.
For the standards governing implementation of applications in general, please referto the document describing theCouncil of Europe information system standards enclosed with thedeveloper's toolkit.
Failure to comply with the standards andnorms of the Council of Europemay result in a delivery being rejected.
1.2Warning signs used in this document
The pictograms below are used throughout this document to emphasise importantpoints ornotions.
/ Important information/ Specific action
/ Action to be avoided
/ Mandatory action
1.3Reference documentation
/ It is imperative that the following documentation be taken into accountfor developments:JS/CSS/HTML documentation
SVN documentation
Graphic charter
2.Choice of technology
2.1Programming language
All the applications developed (Web Application, Windows Application, Web Services, Windows Service) must useC# language. All ASP.Net pages must useCode-behind technology.
2.2Development environment
Microsoft Visual Studio 2010, the .Net 4.0 framework andSQL Server 2008 R2are to be used fornew developments.
For evolutions of an existing project, the framework used will be the one used by the project, unless the Council of Europedecides to migrate to a morerecent version of the product.
For a SharePoint development, the framework to be used is the one recommended for thetarget SharePoint version.
3.Naming rules
3.1General rules
The naming convention recommended by Microsoft must be scrupulously followed:
3.2Casing styles
/ Three differentcasing stylesare used.Pascalcasing:
Thefirst letterof each word is capitalised.
Example: PascalCasing
Camelcasing:
The first word is in lowercase, and all the following words in Pascal casing
Example: camelCasing
Uppercase:
All thelettersare capitalised. By convention, it is used only for words or acronyms less than threecharacters long. However, an exception may be made forindicators used for the main Namespace.
Example: IO
3.3Casing ofDifferentDevelopmentElements
Development element / Casing / ExampleClass / Pascal / Public class FileStream
Interface / Pascal prefixedwith an uppercase I / Public interface IFacade
Attributes / Pascal with the suffixAttribute / [EntitySetAttribute("MyPersonalAttribute")]
Properties / Pascal / public bool NewProperty { get; set; }
Parametersand variables / Camel / String myVariable
Methods / Pascal / Public void GetUser()
Components / Camel / txtNom
Enumerations / Pascal / Public enum MyEnum
Events / Pascal / Public event MyEventHandler TriggerIt;
3.4Graphic controls
To make the source code easier to read, all the names ofgraphic controlsmust be prefixedby their type: [TYPE_CONTROL][NAME_CONTROL]
Control / Examplelabel / lblMyLabel
textBox / txtMyTextBox
drop-down list / ddlMyList
checkBox / cbMyCheckBox
panel / pnlMyPanel
update panel / upnlMyUpdatePanel
gridView / gvMyGridView
TreeView / tvMyTreeView
ListView / lvMyListView
link button / lnkMyLink
object data source / odsMyDataSource
radio button / rbMyRadioButton
required field validator / rfvMyValidator
regular expression validator / regvMyValidator
range validator / rngvMyValidator
hidden field / hidMyHiddenField
image / imgMyImage
User control / ucMyUserControl
Div / divMyDiv
Form / formMyForm
Example:
asp:LabelID="lblNom"runat="server"Text="Label"</asp:Labelasp:TextBoxID="txtNom"runat="server"</asp:TextBox
asp:GridViewID="gvDemands"runat="server"</asp:GridView
3.5Language Used in the Code
For the classes representing business objects and also for the rest of the code, one language only -English - must be used throughout the project, and the use ofaccents and other special characters must of course be excluded.
Clear, concise terms must be used to indicaterolesand actions consistently throughout the application.
The following list of verbs covers the most common actions:
Verb or Keyword / Meaning / ExampleGet / Retrieval of an object / getAgentsById()
Update / Updating of an object / updateAgent()
Create / Creationof an object / createAgent()
Delete / Deletion of an object / deleteAgent()
Is (Can, orsimilar prefix) / Boolean value (variable, function ormethod) / isUpToDate(), isAdministror(), canDeleteItem()
In general, care must be takento correctly compile the name of amethod:
- it always begins with a verb describing the action
- the verbis followed by one or more names of objects and/orpropertiesifnecessary
3.6Files
Pascal casing must be used for filenames. The filename must be consistent with the class name(example: fileUserService.csand classUserService).
For a substantially sized class, the code could be broken down into several files using the partial keyword.
Example: with our UserServiceclass
UserService.cs
UserService.AccessRights.cs
UserService.UserData.cs
3.7Namespaces
Namespaces are used to groupfunctionalitiesor applications with common features, in sets.
Approach taken forWeb projects (international standard):
- the namespaces root must contain the name"Coe"to clearly identifythe packages produced by or for theCouncil of Europe;
- the first suffix designates the application;
- the second suffix correspondsto the name of the project (domain, see section onstructuring of applications);
- the following suffixes areoptionalfordefining sub-categories; they usually correspond to the file's position in the project tree structure.
Examples:
Amodelin theHCMS application: Coe.Hcms.Business.Models
Aweb page in HCMS: Coe. Hcms.Web.WebForms
An encryption class in HCMS: Coe.Hcms.Utils.Security
Error management classdevelopedat the Coe:
Coe.WebModules.ErrorManager.ExceptionHandler
3.8Source documentation
3.8.1General points
The application source code must be accompanied by comments in French or English using the Visual Studioautomaticdocumentation tool. One of these 2 languages must be chosen andused throughout the application.
The comments associated with the code are important. It should be noted that the point of the comments is not to paraphrase the code or to reproduce it in pseudo-code, but to provide all the information needed for efficient maintenance and swift familiarisation.
It should be noted that if the structure and functionsof theapplication'sdifferent components are not clear from a quick read-through of thenames of classes, methodsand short descriptions, it may be a good idea to review the naming of those classes ormethodsrather than writing lengthy comments.
Where algorithms are used, it is important to specify the limits and/orconstraints associated with thealgorithm as well as thereferences (name of the algorithm, similar method etc) so that it may be swiftly appropriated.
3.8.2Rules to follow
- All the classes must be commented on using the"summary"tag. The comment must contain anexplicitdescription of the class:
///<summary>
///Product class used to
///</summary>
publicclassMaClasse
- All thefunctionsmust be commented on and theinput and outputparametersmust be indicated indetail;
- In the code-behind of the ASP.Netpages, the comments onfunctions corresponding to events (OnClick, PageLoad etc) areoptional. However, they are mandatory for allfunctionsadded bydevelopers;
- Any portion of complexcode must be commented on.
It is important to use .NET tools such asregions (#region … #endregion) to make thecode easier to read, but also to simplify maintenance. It is recommended, therefore, that the code be organised in the form of well differentiated logicregions.
4.Structuring of Applications
All the applications developed for the Council of Europe must implement ann-tier architecture, with each layer corresponding to aseparateproject of the solution.
4.1Organisation ofProjects
4.1.1"Web" Projects
/ "Web"projects must beWeb Applicationsand notWebsites.Thedifferentdirectoriesthat could be presentin a "Web" project are listed below:
Directory / DescriptionApp_Code / Directory containing theshared classes of the Web project
App_Data / Directory containing one ormore databases (used during the development, to be deleted beforeintegration)
App_GlobalResources / Directory containing theproject resource files
App_Themes / Directory containing theproject themesand stylesheets
App_WebReferences / Directory containing thereferencesto WebServices
Help / Directory containing thecontextual help files
Images / Directory containing the images used in theMMI
Js / Directory containing theJavascript scripts
WebForms / Directory containing the application'sASPX pages
UserControls / Directory containing theuser controls
Properties / Directory containing the assembly.cs file
References / Directory containing the projectreferences
/ It is imperative that thedifferentelementsof the application are organisedaccording to this structure: each Web project must contain a"Properties" directory containing an"AssemblyInfo.cs" file.
/ The JavaScript / CSS / HTMLdevelopment are described in a separate document and must be taken into account in the same way as thepresent document.
4.1.2"Library" Projects
Each "Library"project must contain a"Properties"directory containing an"AssemblyInfo.cs" file. Thelibrary version must be updatedupon each delivery.
Example:
[assembly: AssemblyTitle("Coe.Passport.BLL")]
[assembly: AssemblyDescription("")]
[assembly: AssemblyConfiguration("")]
[assembly: AssemblyCompany("Council of Europe")]
[assembly: AssemblyProduct("Coe.Passport.BLL")]
[assembly: AssemblyCopyright("Copyright © Council of Europe 2010")]
[assembly: AssemblyTrademark("")]
[assembly: AssemblyCulture("")]
[assembly: ComVisible(false)]
[assembly: Guid("03ac60a6-777d-482d-b00f-b0f61b828172")]
[assembly: AssemblyVersion("1.4.3.0")]
[assembly: AssemblyFileVersion("1.4.3.0")]
/ Theversions number will beautomatically updatedduring deployment,it is notnecessary to update4.2Organisation of theSolution
All the solutions developedfor the Council of Europemust be organised as follows:
- the solution file (.sln)must be located at the rootof the SVN repository(seeSVN documentation referencedin § 1.3) of the version (eg: 2.0.3.x) and this file will have the same name as the project (example: Coe.SiteManager.sln);
- one directory must be created per project in the root directory. Each directory will containa project file whose name will consist of the name of the project followed by theproject type extension (example: Coe.SiteManager.Dal).
Thedifferent project directories which might be created in the root directory are:
- Entitiesproject: containing the business objects (example: Customerobject, Product object, Supplier object etc);
- Dalproject: containing thedata access layer;
- Bllproject: containing thebusiness layer;
- Utilsproject: containing the classes of utilities;
- Webproject: containing theapplicationpresentationlayer.
Ifnecessary, other projects could be created, with the agreement of the Council of Europe architect.
Anexampleof project organisationis given below:
D:\sources\Coe.SiteManager\D:\sources\Coe.SiteManager\Coe.SiteManager.sln
D:\sources\Coe.SiteManager\Coe.SiteManager.Web\
D:\sources\Coe.SiteManager\Coe.SiteManager.Web\Coe.SiteManager.Web.csproj
D:\sources\Coe.SiteManager\Coe.SiteManager.Bll\
D:\sources\Coe.SiteManager\Coe.SiteManager.Bll\ Coe.SiteManager.Bll.csproj
D:\sources\Coe.SiteManager\Coe.SiteManager.Dal\
D:\sources\Coe.SiteManager\Coe.SiteManager.Dal\ Coe.SiteManager.Dal.csproj
NB: Theelementsin bold are directories, and the otherelements correspond to files.
4.3Data access layer (Coe.MyProject.Dal)
For data access, either Entity Framework or a more classic data accesslayer based on the use ofstoredprocedureswill be used.
4.3.1Using Entity Framework
.NET LINQ query language may be used, with Entity Framework recommended for managing the data access layer.
TheEDMXmodelwill have to be kept up to date from the database.
/ On the other hand, LINQ to SQLis to be avoided. Any use of LINQ to SQL will have to bejustifiedand expressly validated(example: database without anyconstraint).4.3.2Usingstored PROCEDURES
In this case, it is imperative for thedata access layer tousethe "Data Access Application Block"libraries of"Enterprise Library 5"supplied by Microsoft (available from the following link):
/ Alldatabase accessmust be via storedprocedures./ No query must appear in thesource code.
4.3.3Objects returned by the data access layer
The data access layermust return onlybusiness objects ortypedDataSets to the upper layers.
4.4Business layer (Coe.MyProject.Bll)
This corresponds to thefunctionalpartof the application, which implements the logic and describes theoperationsperformed by the application on data in response to users' queries, forwarded by thepresentation layer.
The different rules for managing andcontrolling thesystemare implemented in this layer.
The business layerprovides application and businessservices to thepresentation layer. To provide those services, it relies, where applicable, on thesystem data, accessible through the services of the lower layer, and then sendsthe results it has computed to the presentation layer.
Depending on the application architecture, this layer could be broken down into several projects (for example: a project for services, a project forinterface contractsanda project for business objects).
4.5Presentation layer (Coe.MyProject.Web)
In addition to the imperative need to take account of thedifferent points detailed in this section for the implementation of thepresentation layer, it is imperative that the service provider refersto thegraphicchartersupplied by the CoE in the developer's toolkit.
4.5.1Code factorisation
The code must be factorised as much as possible: for this, we recommendusing MasterPages and usercontrols.
You are also advised not to make direct use of System.Web.UI.Page and System.Web.UI.Control classes, but to go throughintermediate classes specificto the project (CoE.xxxx.Web.BasePage & CoE.xxx.Web.BaseControl for example), which themselves inherit from System.Web.UI.Page and System.Web.UI.Control respectively.
4.5.2Validation of data
Thevaluesinput must be checked on both the client side and the server side, to maximise application security.
Client side
Checks must be run on all input fields.
- either throughvalidation components supplied by the framework:
- RequiredFieldValidator: check on thepresence of required data;
- CompareValidator: comparisonof theinput value with thereference value;
- RangeValidator: theinput value is within a given range ofvalues;
- RegularExpressionValidator: validation of data through aregular expression;
- CustomValidator: validation of data through afunction.
Each page containing a validator check must also containa "ValidationSummary"component to alert the user toerrorsduring validation.
- or through the"Validation"jQueryplug-in (cf. JavaScript/CSS/HTMLdevelopment standards).
Server side
Each of thevaluesinput by the user must be validated on theserver side. These checks should preferably be run in the business layer, with clear management ofanyerrors reported to thepresentation layer.
4.6Localisation and globalisation
All applications developed for the Council of Europemust provide for multilingual management (which will mostly entail creating the application in English and French, but it must be possible to add new languages easilyeven if only one language is initially envisaged).
The application'susers must be able to change theinterface language when more than one language isdefined.
Their choice of language must be memorisedand updated, for both authenticated users and anonymous users, in a"coe_language"cookiewith a lifespan of one year.
This cookie must coverthe coe.intdomain, meaning that it will be the same for allCoE applications. It must be used as a priority whenthe applicationis accessedtodetermine the userinterface language. Whenever the user logs in, the cookie will be updated for a fresh duration of one year. Thevalueof this cookie must correspond to alocalesupported by theCultureInfoclass (
If this cookie is not present, the application mustdetermine the language to be used in the light of thelanguage preferencesset at the level of the browser. If none of those languages are listed at the level of the browser, English will beselected bydefault.
To facilitate the translation of applications, global resourcefilesmust be used, and not local resource files. In the project, there must be only one resource file per language, except for a veryhigh-volume application for which the resources could be split between 2 and 10 files maximum, organised on a logical basis (one file for help, one for error messages etc).
4.7Resource files
The informationdisplayed in the MMI must come from a resource file, and must not be hard-coded in the application.
To facilitate the translation of applications, global resource files must be used, and not local resource files. In the project, there must be only one resource file per language, except for a very high-volume application for which the resources could be split between 2 and 10 files maximum, organised on a logical basis (one file for help, one for error messages etc).
The resource files must be named using the following nomenclature: resources.language_code.resx
Example:
- resources.en.resx
- resources.fr.resx
5.Parametering the application
5.1Connection strings
/ Allconnection stringsmustbe in aconfiguration file called"connectionString.config" in the project rootWEB. Thisfilewill be referencedin the web.config filelike describe bellow/ Onlyaccounts withdb_datawriter or db_datareader rightsare allowed forapplications
web.config
...<connectionStringsconfigSource="connectionString.config" />
...
connectionString.config
connectionStrings
addname="SampleDB"
connectionString="server=servername;uid=user;pwd=xxxxxx;database=Database_Name;"
providerName="System.Data.SqlClient"/>
</connectionStrings
5.2SMTPServer