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
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