Documentarea – Scrierea de fişiere Help.

 

In .NET sunt doua tipuri mari de fişiere Help
: Cele care produc Help pentru utilizatorul final si cele care sunt
auto-generate din comentarii la cod.

 

Avem nevoie de următoarele:

1.Html Help Workshop – e free si puteţi
sa îl downloadati de aici

http://www.microsoft.com/downloads/details.aspx?familyid=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en.
Adiţional puteţi downloada si fişiere css stil Office de aici

http://www.microsoft.com/downloads/details.aspx?FamilyId=A6A76073-0E0A-49BB-8E21-318B798B4CF6&displaylang=en

 

 

2. Pentru documentaţia codului
exista înainte NDoc – dar din păcate dezvoltatorul nu mai face dezvoltarea
pentru .Net 2.0( vezi http://johnsbraindump.blogspot.com/2006/07/ndoc-20-is-dead.html)

Alternativa este SandCastle (http://www.sandcastledocs.com) din
care ultimul CTP este aici
(http://www.microsoft.com/downloads/details.aspx?FamilyID=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en).

 

3.De asemenea, pentru ca SandCastle e greu de
utilizat din command line, exista mai multe GUI-uri pentru el – intre care vom
lucra cu SandCastle Help File Builder de pe CodePlex (http://www.codeplex.com/Wiki/View.aspx?ProjectName=SHFB).
O sa lucram cu ultimul release ,1.3.3.1 PROD aflat aici

http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=1209

si as downloada chiar sursele …

 

Începem cu documentarea codului pentru
BookObjects, urmând sa trecem la generarea de Help pentru proiectul Windows.

 

Comentariile in C# se fac scriind trei
slash-uri deasupra clasei/metodei/cimpului pe care vreţi sa le documentaţi:

/// <summary>

/// Aceasta clasa tine toti publisher-ii

/// Mod de utilizare : folositi Load

/// </summary>

public class ColPublisher
: System.Collections.ObjectModel.KeyedCollection<string,Publisher>

{

 

/// <summary>

/// varianta interna de generat cheie unica pentru un
Publisher

/// </summary>

/// <param
name=”item”>publisher-ul</param>

/// <returns></returns>

protected override string
GetKeyForItem(Publisher item)

{

Continuaţi cu toate metodele sau
downloadati ultima varianta de proiect de aici:

http://serviciipeweb.ro/iafblog/content/binary/part12/book.zip

 

In plus, trebuie sa mai setaţi faptul ca
trebuie generata documentaţia XML din proprietatile proiectului:

 

 

Acum in folder-ul C:\Book\BookObjects\bin\Debug
aveţi generata documentaţia XML. Pornim SandCastle Help File Builder care
arata cam asa:

 

 

Apăsam pe Add si ne ducem in C:\Book\BookObjects\bin\Debug.
Acolo indicam dll-ul generat iar programul o sa „observe” si fişierul XML. Apăsam
pe iconiţa de compilare si … eroare…

Error: Unresolved assembly reference: System.Configuration
(System.Configuration, Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a) required by BookObjects

Last step completed in 00:00:02.403

 

 

După descriere vedem că ii lipseşte o referinţa
la System.Configuration. Acest dll se afla in GAC (Global Assembly Cache) si o vom adăuga. In Project Properties , la Build=>Dependencies apăsaţi pe butonul cu cele 3 puncte.

Acum in ecranul următor exista un buton cu
imaginea de folder si cu o icoana de o cheie care iese, iar la tooltip scrie
„Add GAC dependencies”

 

 

Apăsaţi pe el si căutaţi System.Configuration,
Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a in lista care
urmează.

 

Acum spune ca ii lipseşte un XSL(Error:
The transform file ‘C:\Program
Files\Sandcastle\ProductionTransforms\AddOverloads.xsl’ could not be loaded.
The error is: Could not find file ‘C:\Program
Files\Sandcastle\ProductionTransforms\AddOverloads.xsl’.). Pentru
asta fie downloadati un CTP de SandCastle mai vechi sau Visual Studio 2005 SDK
Version 4.0 de la adresa http://www.microsoft.com/downloads/details.aspx?FamilyID=51a5c65b-c020-4e08-8ac0-3eb9c06996f4&DisplayLang=en
si copiaţi XSL-ul cu pricina in folder-ul <Program Files>\ Sandcastle\ProductionTransforms,
alături de celelalte.

 

Acum rulati din nou si ceea ce se va genera
este un document chm , numit Documentation.chm aflat in C:\Book\BookObjects\bin\Debug\Help:

 

 

Putem personaliza ceea ce se generează destul
de uşor, modificând setările de aici:

 

 

E clar acum ca aceasta documentaţie se poate
regenera la cerere.

 

Sa generam acum documentaţia pentru Windows
Forms.

Ar trebui pentru fiecare forma sa avem cate un
Help – aşa ca o sa cream 3 fişiere HTML care o sa tina List, Add si Update.

 

Vom crea un nou folder, numit HelpWindows, in
C:\book\Help si vom pune in el cele 3 fişiere : add.htm,list.htm,update.htm.

Pornim HTML Help Workshop, File=>New
=>Project si daţi next. Adaugati fişierele htm si apăsati pe Contents.
Acceptaţi creerea unui nou fişier si apăsând pe iconiţa din stânga cu aspect de
fişier adăugat la conţinut cele 3 fisiere, dindu-le numele corespunzătoare.
Acum, după compilare, s-a generat un fişier chm. Haideţi sa îl integram cu aplicaţia
Windows.

 

 

Sarcina de a copia fişierul chm lângă
executabil o las cititorului, având in vedere ca am mai făcut aşa
ceva(Project=>Properties=>Build Events). Sa mergem la forma de list si sa
adaugam din ToolBox un control HelpProvider. LA proprietati la HelpNameSpace
puneti numele chm-ului. Acum pe forma, gasiti HelpKeyword on… (setati
valoarea la list.htm) si HelpNavigator on…( setat la topic). Rulati, apasati
F1 si iata fisierul de help!

 

Puteti downloada ultimele surse de aici

http://serviciipeweb.ro/iafblog/content/binary/part12/book.zip

 

Lecturi utile:

GAC http://www.codeproject.com/dotnet/DemystifyGAC.asp

MSHelp 2.0 http://www.helpware.net/mshelp2/h20.htm

 

 

 

 

 

 

 

De ce ar trebui sa faceti teste automate ?

Din mai multe
motive :

1.     
Pentru ca e o modalitate usoara de a releva
functionalitatile mari ale aplicatiei

2.     
Pentru ca la orice modificare la care nu sunteti
sigur daca dauneaza cumva logicii aplicatiei puteti rula testele vechi si
vedeti daca ati stricat ceva sau nu(Nota : ar trebui sa adaugati un nou test
pentru cei care vin dupa voi )

3.     
E mai usor de fixat bug-urile daca, pe deasupra,
rulati testele in fiecare noapte – si a doua zi dimineata vedeti ceva
stricat…

4.     
 

Hai sa trecem la treaba:

 

Mai intii downloadati NUnit de la http://www.nunit.org/index.php?p=download
( eu am folosit versiunea 2.2.8 )Exista si surse si setup de instalare. Eu as
sfatui sa luati sursele sa le compilati.

Apoi la solutia noastra Book.sln adaugam un
nou proiect de tipul Class Library , numit BookTest , adaugam o referinta la nunit.framework.dll
, aflat in NUnit-2.2.8-src\src\NUnitFramework\framework\bin\Debug2005,
modificam class1.cs in TestPublisher.cs si incepem sa scriem testul.Testul cel
mai simplu este unul de CRUD – create , read, update, delete.

Avem nevoie de obiectele Publisher respective,
precum si de setari in fisierul App.Config pentru a recunoaste Baza de date,
precum si de Baza de date.

Pentru Publisher, adaugam o referinta la
BookObject in tab-ul „Projects” de la Add Reference.

Pentru App.Config, adaugam un fisier de tipul
application configuration file si copiem de la BookDos partile relevante,
astfel incit fisierul arata astfel :

 

<?xml version=“1.0“ encoding=“utf-8“ ?>

<configuration>

<appSettings>

<add key=“DatabaseUsed“ value=“MDB“/>

<!–
possible values : MDB, SQLServer–>

</appSettings>

<connectionStrings>

<add name=“MDB“ connectionString=“Provider=Microsoft.Jet.OLEDB.4.0;Data
Source=|DataDirectory|\book.mdb;User Id=admin;Password=;“/>

<!– TODO :
add for asp.net application the connection string with SQL Server–>

</connectionStrings>

</configuration>

 

Pentru baza de date, e simplu : in Build
Events, la Post Build Command Line adaugam

copy $(ProjectDir)..\BookData\*.mdb $(TargetDir)

Acum putem incepe sa scriem testul :

 

 

using System;

using System.Collections.Generic;

using System.Text;

using NUnit.Framework;

using BookObjects;

namespace BookTest

{

[TestFixture]
//arata ca e o clasa care contine teste

public class TestPublisher

{

[Test]
//arata ca metoda care urmeaza este un test

[Category(“CRUD”)] //categoria
-de obicei, testele de CRUD ar trebui puse impreuna

public
void CRUD()

{

Publisher
p = new Publisher();

p.Name = “Amazon”;

p.Save();

 

//sa il
gasim

ColPublisher
cp = new ColPublisher();

cp.Load();

bool
bFound= false;

foreach
(Publisher pLoop in
cp)

{

if
(pLoop.Name == p.Name)

{

bFound = true;

break;

}

}

//daca
acea conditie(bFound) nu e true, atunci se afiseaza mesajul de eroare

Assert.IsTrue(bFound,
“Nu s-a gasit publisher cu numele “
+ p.Name + ” dupa insert”);

//sa il
modificam

p.Name = “O’Reilly”;

p.Update();

 

//sa il
gasim din nou

cp = new
ColPublisher();

cp.Load();

bFound = false;

foreach
(Publisher pLoop in
cp)

{

if
(pLoop.Name == p.Name)

{

bFound = true;

break;

}

}

//daca
acea conditie(bFound) nu e true, atunci se afiseaza mesajul de eroare

Assert.IsTrue(bFound,
“Nu s-a gasit publisher cu numele “
+ p.Name + ” dupa update”);

 

//acum
sa il stergem

p.Delete();

 

//si sa
vedem ca nu a fost gasit

cp = new
ColPublisher();

cp.Load();

bFound = false;

foreach
(Publisher pLoop in
cp)

{

if
(pLoop.Name == p.Name)

{

bFound = true;

break;

}

}

 

//daca
acea conditie(bFound) nu e false, atunci se afiseaza mesajul de eroare

Assert.IsFalse(bFound,
“S-a gasit publisher cu numele “ +
p.Name + ” dupa delete”);

 

 

 

}

}

}

 

 

Il compilam si sa rulam testul. Gasiti in
folderul NUnit-2.2.8-src\src\GuiRunner\nunit-gui-exe\bin\Debug2005 un nunit-gui.exe
si porniti-l.Apasati File=> Open si mergeti in C:\Book\BookTest\bin\Debug si
incarcati BookTest.dll . Ar trebui sa apara figura urmatoare

 

Apasati pe RUN si primul lucru pe care il
vedeti este:

 

 

Se vede clar ca e ceva prost… ne uitam in TestPublisher.cs
si vedem ca la linia 37 este

p.Update();

Ceva a mers prost la update … sa vedem linia
107 din Publisher.cs

strSQL
+= “‘” + this.Site.Replace(“‘”, “””)
+ “‘”;

Acum e clar ce s-a intimplat … Cind am facut
testul, nu am initializat Site-ul cu nimic… si atunci este null , ceea ce
inseamna ca .Replace nu poate fi aplicat

Sa modificam codul din Publisher.cs ca sa ia
in seama si acest lucru :

if
(this.Site == null)

strSQL += ” NULL “;

else

strSQL += “‘” + this.Site.Replace(“‘”,
“””) + “‘”;

 

Acum apare alta eroare :

 

Este destul de clar ca aplicatia nu a updatat
numele …

De ce ?Ne dam seama imediat : in momentul in
care aplicatia a adaugat un nou Publisher , nu a regasit ID-ul inserat … iar
cind a facut update, IDPublisher este 0 , ceea ce inseamna ca nu
a putut fi facut update corect.

Cum modificam acest lucru ? Pentru access ,
putem sa selectam maxim de ID,iar pentru SQL Server putem crea o procedura
stocata … sau sa intoarcem @@Identity

Hai sa facem pentru Access , modificand Publisher.cs,
procedura Save, adaugind la final:

if(Settings.TheDatabase == Settings.DatabaseUsed.MDB)

{

 

strSQL = “select max(IDPublisher) as nr from Publisher”;

using
(DbConnection dc = Settings.TheConnection)

{

dc.Open();

using(DbCommand dco =Settings.TheCommand)

{

dco.CommandType =
System.Data.CommandType.Text;

dco.CommandText =
strSQL;

dco.Connection = dc;

object o = dco.ExecuteScalar();

this.IDPublisher = int.Parse(o.ToString());

}

}

}

Acum rulam din nou testul si totul e verde ,
ceea ce e de bine :

 

 

E clar ca exemplu a fost mai degraba simplut,
iar ceea ce conteaza, de fapt, sunt regulile de business si de validare – ca
de exemplu, validarea CNP