HtmlAgilityPack on html-jäsennin (parseri) eli se ottaa vastaan html:ää sisältävän merkkijonon ja muodostaa siitä puumaisen kokoelman html:n elementtejä kuvaavia olioita. Tuosta joukosta voi sitten etsiä elementtejä vaikkapa nimen tai attribuuttien perusteella. HtmlAgilityPack on omiaan crawlerissa tai vastaavassa botissa, jonka pitää etsiä websivulta olennaisia tietoja.

HtmlAgilityPackin käyttöönotto

• Lataa paketti osoitteesta http://htmlagilitypack.codeplex.com/ ja pura se
• Lisää projektiin referenssi tiedostoon HtmlAgilityPack.dll

Tietojen käsittelyyn käytetään pääasiassa kolmea luokkaa

Luokka	Kuvaus
HtmlDocument	Koko dokumentti (websivu).
HtmlNode	Yksi elementti (esim. Otsikko tai )
HtmlAttribute	Yksi attribuutti (nimi-arvopari elementissä esim. src="kuva.jpg" tai href="sivu.html"

Dokumentti

Ennen tietojen käsittelyä tulee luoda dokumentti ja ladata siihen sivun lähdekoodi. Lataamiseen on kaksi metodia: Load ja LoadHtml. LoadHtml ottaa lähdekoodin vastaan merkkijonona. Load-metodilla on useita versioita, jotka ottavat lähdekoodin vastaan joko polkuna tiedostoon, stream-objektina tai TextReader-objektina.

Lataaminen merkkijonosta LoadHtml-metodilla

// lähdekoodi merkkijonossa
string html = @"Teknisistä syistä johtuen en voinut tähän html:ää laittaa";

// luodaan dokumentti
HtmlDocument doc = new HtmlDocument();
// ladataan html dokumenttiin
doc.LoadHtml(html);

Lataaminen tiedostosta Load-metodilla

// polku tiedostoon
string path = "sivu.html";
// luodaan dokumentti
HtmlDocument doc = new HtmlDocument();
// ladataan tiedoston sisältö dokumenttiin
doc.Load(path);

Elementit

Elementit ovat tägien (<>) erottelemia html:n osia. Elementtiä kuvaa luokka HtmlNode. HtmlDocument:llä on ominaisuus DocumentNode, joka on juurielementti ja sisältää koko lähdekoodin. Varsinaiset html-elementit alkavat DocumentNode:n lapsielementistä.

Luokkien ja elementtien hierarkia on seuraavanlainen

Luokka/ominaisuus/					Kuvaus	Tyyppi
HtmlDocument					Dokumentti	HtmlDocument
	HtmlDocument.DocumentNode				Dokumentin juurielementti	HtmlNode
					Juurielementin lapsi	HtmlNode
					Html-elementin lapsi	HtmlNode
				<...>	Head-elementin lapset	HtmlNode
					Html-elementin lapsi	HtmlNode
				<...>	Body-elementin lapset	HtmlNode

Elementeillä on mm. ominaisuudet

Ominaisuus	Tyyppi	Kuvaus
Attributes	HtmlAttributeCollection	Attribuutit
ChildNodes	HtmlNodeCollection	Lapsielementit
FirstChild	HtmlNode	Ensimmäinen lapsielementti
HasAttributes	bool	Onko attribuutteja
HasChildNodes	bool	Onko lapsielementtejä
Id	string	Id-attribuutin arvo
InnerHtml	string	Tägien välissä oleva html
InnerText	string	Tägien välissä oleva teksti
LastChild	HtmlNode	Viimeinen lapsielementti
Line	int	Rivin numero lähdekoodissa
LinePosition	int	Sarakkeen numero lähdekoodissa
Name	string	(Tägin) nimi
NextSibling	HtmlNode	Seuraava (sisar)elementti
NodeType	HtmlNodeType	Elementin tyyppi
OriginalName	string	Alkuperäinen (tägin) nimi
OuterHtml	string	Tägit ja niiden välissä oleva html
OwnerDocument	HtmlDocument	Dokumentti, johon kuuluu
ParentNode	HtmlNode	Yläelementti (vanhempi)
PreviousSibling	HtmlNode	Edellinen (sisar)elementti
StreamPosition	int	Sijainti streamissa
XPath	string	Elementin XPath

Elementtiin liittyviä muita elementtejä voi etsiä metodeilla

Metodi	Kuvaus
Ancestors AncestorsAndSelf	Elementtihierarkia (vanhemmat) juureen asti
DescendantNodes DescendantNodesAndSelf DescendantNodes DescendantNodesAndSelf	Lapsielementit, niiden lapset jne.
Element	Ensimmäinen tietyn niminen lapsielementti
Element	Kaikki tietyn nimiset lapsielementit
SelectNodes	Kaikki lapsielementit xpath:n perusteella
SelectSingleNode	Ensimmäinen lapsielementti xpath:n perusteella

Elementtien etsiminen XPath:lla

Monipuolisimmat elementtien etsimismetodit ovat SelectNodes ja SelectSingleNode, jotka käyttävät XPath:ia.

Elementin etsiminen XPath:n avulla. Sovitaan, että html-muuttujassa on seuraava sisältö

	
	
        
Otsikko
        
Teksti
	

ja poimitaan otsikon (h1) arvo muuttujaan ``` csharp HtmlDocument doc = new HtmlDocument(); // ladataan ylläoleva setti doc.LoadHtml(html);

// poimitaan h1-elementti käyttäen xpath:ia HtmlNode titleH1 = doc.DocumentNode.SelectSingleNode("html/body/h1"); // ja h1-elementin teksti string title = titleH1.InnerText; // Otsikko

XPath:sta löytyy lisätietoa mm. <a title="XPath Tutorial" href="http://www.w3schools.com/xpath/default.asp">w3schoolsin XPath-oppaasta</a>
<h3 id="attribuutit">Attribuutit</h3>
Attribuutit ovat elementtien nimi-arvopareja. Esim. kuvalla on <strong>src</strong>-attribuutti (<img <strong>src="kuva.jpg"</strong> />) ja linkillä <strong>href</strong>-attribuutti (<a <strong>href="sivu.html"</strong>>Sivu</a>). Attribuutteja kuvaa luokka <strong>HtmlAttribute</strong>, jolla on seuraavia ominaisuuksia
<table>
<thead>
<tr>
<th>Nimi</th>
<th>Tyyppi</th>
<th>Kuvaus</th>
</tr>
</thead>
<tbody>
<tr>
<td>Line</td>
<td>int</td>
<td>Rivinumero lähdekoodissa</td>
</tr>
<tr>
<td>LinePosition</td>
<td>int</td>
<td>Sarakenumero lähdekoodissa</td>
</tr>
<tr>
<td>Name</td>
<td>string</td>
<td>Nimi</td>
</tr>
<tr>
<td>OriginalName</td>
<td>string</td>
<td>Alkuperäinen nimi</td>
</tr>
<tr>
<td>OwnerDocument</td>
<td>HtmlDocument</td>
<td><a href="#dokumentti">Dokumentti</a>, johon kuuluu</td>
</tr>
<tr>
<td>OwnerNode</td>
<td>HtmlNode</td>
<td><a href="#elementit">Elementti</a>, johon kuuluu</td>
</tr>
<tr>
<td>StreamPosition</td>
<td>int</td>
<td>Sijainti streamissa</td>
</tr>
<tr>
<td>Value</td>
<td>string</td>
<td>Arvo</td>
</tr>
<tr>
<td>XPath</td>
<td>string</td>
<td>XPath</td>
</tr>
</tbody>
</table>