CsQuery

Not Actively Maintained

Note from the author: CsQuery is not being actively maintained. I no longer use it in my day-to-day work, and indeed don't even work in .NET much these day! Therefore it is difficult for me to spend any time addressing problems or questions. If you post issues, I may not be able to respond to them, and it's very unlikely I will be able to make bug fixes.

While the current release on NuGet (1.3.4) is stable, there are a couple known bugs (see issues) and there are many changes since the last release in the repository. However, I am not going to publish any more official releases, since I don't have time to validate the current code base and address the known issues, or support any unforseen problems that may arise from a new release.

I would welcome any community involvement in making this project active again. If you use CsQuery and are interested in being a collaborator on the project please contact me directly.

You should also consider using AngleSharp, which is a newer project that is being actively maintained. It's not a drop in replacement, but provides similar capabilities.

CsQuery - .C# jQuery Port for .NET 4

CsQuery is a jQuery port for .NET 4. It implements all CSS2 & CSS3 selectors, all the DOM manipulation methods of jQuery, and some of the utility methods. The majority of the jQuery test suite (as of 1.6.2) has been ported to C#.

Why CsQuery?

CSS selectors and jQuery make it really easy to access and manipulate HTML on the client. There's no reason it should be any more difficult to do the same thing with some arbitrary HTML on the server. It's a simple as that. Use it in web projects to do post-processing on HTML pages before they're served, for web scraping, parsing templates, and more.

Standards Compliant HTML parsing

CsQuery uses a C# port of the validator.nu HTML parser. This is the same code used in the Gecko browser engine. CsQuery will create an identical DOM from the same source as any Gecko-based browser. You should expect excellent results for handling both valid and invalid markup.

CSS3 Selectors and jQuery methods

CsQuery implements all CSS2 and CSS3 selectors and filters, and a comprehensive DOM model. You can use all the same jQuery (and DOM element) methods you're familiar with to traverse and manipulate the DOM.

Fast, indexed CSS selectors

The CSS selector engine fully indexes each document on tag name, id, class, and attribute. The index is subselect-capable, meaning that complex selectors will still be able to take advantage of the index (for any part of the selector that's indexed). Performance of selectors compared to other existing C# HTML parsing libraries is orders of magnitude faster.

What's more, the entire test suite from Sizzle (the jQuery CSS selector engine) and jQuery (1.6.2) has been ported from Javascript to C# to cover this project.

It's incredibly easy

Pretty much everything you need is in the CQ object, which is designed to work like a jQuery object. Assigning a string to a CQ object parses it. The property indexer ['...'] runs a CSS selector, and returns new CQ object, like $('...') using jQuery. Finally, the Render method writes the DOM back to a string. From a CQ object, you have access to the complete jQuery API to traverse and manipulate your document, as well as an extensive browser DOM model.

Here's a basic example of parsing HTML, selecting something, altering it, and rendering it back to a string.

CQ dom = "<div>Hello world! <b>I am feeling bold!</b> What about <b>you?</b></div>";


CQ bold = dom["b"];               /// find all "b" nodes (there are two in this example)

  > bold.ToList()
  > Count = 2
  > [0]: {<b>...</b>}
  > [1]: {<b>...</b>}

  > bold.First().RenderSelection()
  > "<b>I am feeling bold!</b>"
   
string boldText = bold.Text();        /// jQuery text method;

  > boldText
  > "I am feeling bold! you?"

bold.Remove();                        /// jQuery Remove method

string html = dom.Render();           

  > html
  > "<div>Hello world!  What about </div>"

There are other ways to create CQ objects, run selectors, and change the DOM. You can also use the property indexer like an array indexer, e.g. dom[0] returns the first element in your selection. If there is one, that is! Using the LINQ method dom.FirstOrDefault() might be a better choice for many situations. In javascript, you'd often test the Length property of a selection to see if there were any results. The CQ object exposes an IEnumerable<IDomObject> interface, so you can use LINQ to simplify many operations. But you still have all the tools that you're used to from jQuery, too.

Like in jQuery, each CQ object is made up of DOM elements. In CsQuery, the basic node is an IDomObject and is analagous to an HTML element or other node (like a text node or comment node). Most of the typical HTML element methods are available. So, using these alternatives, to obtain only the first bolded item from the example above:

use CSS to choose first node only

string bold = dom["div > b:first-child"].Text();

use jQuery CSS filter extensions to return the first item in the selection

string bold = dom["b:first"].Text();

use LINQ First to get the first item, and the DOM node "InnerText" method

string bold = dom["b"].First().InnerText;

use indexer to get the first item, and "Select" instead of the indexer to make it more readable

string bold = dom.Select("b")[0].InnerText;

Use jQuery "contents" method to return the text node children, the indexer to get the first, and the DOM node "nodeValue" method to get the contents of a text node

string bold = dom["b"].Contents()[0].NodeValue

Each of these returns the same thing: "I am feeling bold!"

Installation

Latest release: Version 1.3.4 (February 5, 2013)

To install the latest release from NuGet package manager:

PM> Install-Package CsQuery

To install manually, add a reference to CsQuery.DLL. There are no external dependencies.

Compiling from Source

This repository contains a submodule for HtmlParserSharp. This configuration has been chosen to allow the HTML parser project to be completely independent of CsQuery, while still allowing CsQuery to include it directly and compile to a single DLL.

To clone the repostory with the submodule, you need to take an extra step. First create a clone as usual:

git clone https://github.com/jamietre/CsQuery.git csquery

Next change to the repo folder, and initialize and clone the submodule.

cd csquery
git submodule update --init -f

You should be able to compile everything now. If you have any trouble initializing the submodule, just delete the submodule folder ../source/CsQuery/HtmlParserSharp and run the submodule init command again.

Release Notes

The current release is 1.3.4. This is a bug fix release:

• Handle out-of-bounds character set changes
• Allow changing character set via meta tag outside of HEAD
• Allow non-alpha ID selectors

See the change log for details.

The last major release is 1.3.0. This release implements a new HTML5-compliant parser.

• Release notes for 1.3: Read details on the new features and other changes. You can also see all CsQuery release notes at once.
• Detailed change log: see more more detail about specific changes, or notes on changes made to the source since the last release.

Documentation

Documentation is being moved from here to the documentation folder in the repository. There is detailed documentation for these topics:

• Create: Creating a new DOM from HTML in memory, a file, a stream, or a URL
• Render: Rendering your DOM back to HTML
• CreateFromUrl: Creating CsQuery objects from a remote source
• Promises: An overview of the CsQuery Promise API, which is useful for managing asynchronous events. This is useful when loading content from remote URLs without blocking execution while you're waiting for the response.
• How CsQuery handles character set encoding: Explanation of the different ways a character set encoding can be specified in an HTML document, and how CsQuery detects and prioritizes them.

Everything else will be found here in the readme. It covers most common uses for reading HTML documents from files and URLS, and using it like jQuery.

I also post about CsQuery on my blog from time to time. Here are a few tutorials from there:

• Using the CsQuery MVC framework from the 1.2 release notes
• Implementing a custom filter selector from the 1.1.3 release notes
• Creating documents from the 1.1.2 release notes
• Loading content from the web asynchronously using promises

For methods ported from the jQuery API, in almost all cases it will function exactly as it does in jQuery. There are exceptions related to differences in the languages, but this should generally be obvious. You can also look through the unit tests, which cover pretty much everything at some level, for straightforward examples of use.

Also be sure to look at the example applications under CsQuery.Examples.

Contents

• Roadmap
• Usage
  • Creating a new DOM
  • Manipulate the DOM with jQuery methods
  • Accessing DOM elements directly
  • Output as HTML
• CsQuery vs. jQuery
  • Creating a new DOM
  • C# objects vs. Javascript objects
  • Important nonstandard methods
  • Utility methods
• Options
  • Rendering Options
  • HTTP request options
• The CsQuery Object Model
  • Overview
  • Creating a CQ object from HTML
• The DOM (Document Object Model) *