The following is cross posted from Mark Rodseth’s blog (he also posted a follow up post with more details).

Mark is a .Net Technical Architect at a digital agency named Fortune Cookie in London. I would like to take the opportunity and thank Mark both for the grand experiment about which you are about to read and for the permission to post this in the company blog.

Please note: Mark or Fortune Cookie are not affiliated with either Hibernating Rhinos or RavenDB in any way.

When a colleague mentioned  RavenDB  to me I had a poke around and discovered that it was one of the more popular open source NoSQL technologies on the market. Not only that but it was bundled with Lucene.Net Search making it Document Database coupled with Lucene search capabilities.  With an interest in NoSQL technology and a grudge match that hadn’t been settled with Lucene.Net, I set myself the challenge to swap out our SQL Search implementation with RavenDB and then do a like for like load test against the two search technologies.
These are my findings from both a programmatic and performance perspective.

Installing RavenDB
There isnt much to installing Raven and its pretty much a case of downloading the latest build and running the Server application.
The server comes with a nice Silverlight management interface which allows you to manage all aspects of Raven Db from databases to data to indexes. All tasks have a programmatic equivalent but a decent GUI is an essential tool for noobs like myself.

Storing the Data
My first development task was to write an import routine which parsed the property data in SQL and then add it into a Raven Database. This was fairly easy and all I needed to do was to create a POCO, plug it with data from SQL and save it using the C# Raven API. The POCO serialised into JSON data and saved as a new document in the  RavenDB.

The main challenge here was changing my thinking from relational modelling to domain driven modelling - a paradigm shift required when moving to NoSQL - which includes concepts like aggregate roots, entities and value types. Journeying into this did get a bit metaphysical at times but here is my understanding of this new fangled schism.

Entity - An entity is something that has a unique identity and meaning in both the business and system context. In the property web site example, a flat or a bungalow or an office match these criteria.

Value Type - Part of the entity which does not require its own identity and has no domain or system relevance on its own. For example, a bedroom or a toilet.

Aggregate Root - Is an master entity with special rules and access permissions that relate to a grouping of similar entities. For example, a property is an aggregate of flats, bungalows and offices. This is the best description of these terms I found.

Hibernating Rhinos note: With RavenDB, we usually consider the Entity and Aggregate Root to be synonyms to a Document. There isn’t a distinction in RavenDB between the two, and they map to a RavenDB document.

In this example, I created one Aggregate Root Entity to store all property types.

C# Property POCO

Indexing the Data
Once the Data was stored it needed to be indexed for fast search. To achieve this I had to get to grips with map reduce functions which I had seen around but avoided like the sad and lonely looking bloke** at a FUN party.
The documentation is pretty spartan on the  RavenDB web site but after hacking away I finally created an index that worked on documents with nested types and allowed for spatial queries.
RavenDB allows you to create indexes using Map Reduce functions in LINQ. What this allows you to do is create a Lucene index from a large, tree like structure of data. Map reduce functions give you the same capability as SQL using joins and group by statements. To create a spatial index which allowed me to search properties by type and sector (nested value types) I created an index using the following Map Reduce function.

Index created using the Raven DB Admin GUI

Hibernating Rhinos note: a more efficient index would likely be something like:

from r in docs.AssetDetailPocos
select new
{
  sectorname = r.Sectors,
  prnlname = r.AddressPnrls,

  r.AssetId,
  r.AskingPrice,
  r.NumberOfBedrooms,
  r.NumberOfBathRooms,
  
  
  _ = SpatialIndex.Generate(r.AssetLatitude, r.AssetLongitude)
}

This would reduce the number of index entries and make the index smaller and faster to generate.

Querying the data

Now that I had data that was indexed, the final development challenge was querying it. RavenDB has a basic search API and a Lucene Query API for more complex queries. Both allow you to write queries in LINQ. To create the kind if complex queries you would require in a property searching web site, the API was a bit lacking. To work around this I had to construct my own native Lucene queries. Fortunately the API allowed me to do so.

Performance Testing

All the pawns were now in place for my load test.

• The entire property SQL database was mirrored to  RavenDB.
• The Search Interface now had both a SQL and a  RavenDB implementation.
• I created a crude Web Page which allowed switching the search from SQL to  RavenDB via query string parameters and output the results using paging.To ensure maximum thrashing the load tests passed in random geo locations for proximity search and keywords for attribute search. 
• A VM was setup and ready to face the wrath of BrowserMob.

I created a ramp test scaling from 0 to 1000 concurrent users firing a single get request with no think time at the Web Page and ran it in isolation against the SQL Implementation and then in isolation against the  RavenDB Implementation. The test ran for 30 minutes.
And for those of you on the edge of you seat the results where a resounding victory for  RavenDB. Some details of the load test are below but the headline is SQL choked at 250 concurrent users whereas with  RavenDB even with 1000 concurrent users the response time was below 12 seconds.

SQL Load Test

Transactions: 111,014 (Transaction = Single Get Request)
Failures: 110,286 (Any 500 or timeout)

SQL Data Throughput - Flatlines at around 250 concurrent users.

RavenDB Load Test

Transactions: 145,554 (Transaction = Single Get Request)
Failures: 0 (Any 500 or timeout)

RavenDB Data Throughput - What the graph should look like

Final thoughts

RavenDB is a great document database with fairly powerful search capabilities. It has a lot of pluses and a few negative which are listed for you viewing pleasure below.
Positives

• The documentation although spartan does cover the fundamentals making it easy to get started. On some instances I did have to sniff through the source code to fathom how some things worked but that is the beauty of open source I guess. 
• The Silverlight Admin interface is pretty sweet 
• The Raven community (a google group) is very active and the couple of queries I posted were responded to almost immediately.
• Although the API did present some challenges it both allowed you to bypass its limitations and even contribute yourself to the project.
• The commercial licence for  RavenDB is pretty cheap at a $600 once off payment

Negatives

• The web site documentation and content could do with an a facelift. (Saying that, I just checked the web site and it seems to have been be revamped)
• I came a cross a bug in the Lucene.Net related to granular spatial queries which has yet to be resolved.   Not  RavenDB's fault but a dependence on third party libraries can cause issues. 
• I struggled to find really impressive commercial reference sites. There are some testimonials but they give little information away. 
• Sharding scares me.

I look forward to following the progress of  RavenDB and hopefully one day using it in a commercial project. I'm not at the comfort level yet for proposing it but with some more investigation and perhaps some good reference sites this could change very quickly.

* Starry Eyed groupies sadly didn't exist, nor have they ever.
** Not me.

http://ravendb.net

This is a guest post by Chris, a RavenDB user, originally posted on the RavenDB group.

Background

I’ve been fiddling with document databases for a while trying to find a way to aggregate our logs without having to demoralize everything. I started with CouchDB and because of the odd status of the project with the founder abandoning it and since I work in a Windows world, going with Raven ultimately seemed like a wholly better solution – all the goods of Couch plus a .Net API.

I built a data model in C# and used a CSV library to push a few hundred thousand records into Raven. The goal is to allow support engineers to query this log information with some simple PowerShell one-liners.

I thought parsing 100megs of CSV and jamming in the thousands of corresponding documents would be the difficult part to figure out and the one-liners would be a couple hours of work at most.

The Problem

Yes, it was a bit challenging to build an efficient importer, but most of that was due to my limited knowledge of C#. I thought it was still not working when I started to build my Posh one-liners and some queries were returning invalid JSON. The PowerShell 3 CTP introduce some new cmdlets for handling JSON and one specifically for executing HTTP Rest API calls – Invoke-RestMethod (alias irm). IRM is 100 times more user friendly than CURL and it even goes a step above and beyond by automatically deserializing the content returned. So, it’s extremely easy to consume JSON via a REST API, but I kept running into an issue where Posh would throw an error that there was no Results (the deserialized JSON) property on the object. I must have been pushing in bad data – garbage in equals garbage out.

I thought the HTML in some of the log values was invalidating the JSON string. I deleted all the documents, added a call to HTTPEncode on all strings before Storing it to Raven, then I reloaded the records. I ended up with the same results; or, lack of Results property in this case.

The Invoke-RestMethod cmdlet did return what looked like a valid JSON string, so I dropped it into Notepad++ and turned on JavaScript syntax highlighting and went through the string. I found the culprit.

"SkippedResults:0,

There was a missing quote around a key name. I almost posted this as a RavenDB bug, but I checked the raw HTTP response in Fiddler and found that the quote existed.

What do to about it

I am working with a Technology Preview release of Powershell 3, so I checked Connect and found a similar report of missing characters in content deserialization.

“It seems that the last byte of the second HTTP response packet is being dropped by powershell. This only seems to happen when the second response packet is smaller than the first.”

Microsoft closed this issue as “Won’t Fix” and suggested using Invoke-WebRequest instead. Invoke-WebRequest removes all the magic of Invoke-RestMethod and just gets raw HTTP content. I piped the Content parameter to the, also new to Powershell 3, cmdlet ConvertFrom-Json and got proper deserializedJSON.

$c = Invoke-WebRequest "http://localhost:8080/indexes/vovici/Logs/process?query=customer:blah"
$r = $c.content | convertfrom-json

So, it’s an extra step, but if you want to reliably access RavenDB’s HTTP API via PowerShell 3 that seems to be the way to do it.

This is a guest post by Samuel Jack, who had done a lot of work on the new UI for RavenDB.

Three weeks ago Ayende put out a request for help in turning an ugly duckling into a beautiful swan, and I, rather nervously, signed up for the job. The ugly duckling in question was Raven Studio, the Silverlight-based management UI for Raven Db. The nerves were a result of doubting that my limited graphic design skills were up to the job. But when Ayende assured me that he had a proto-type swan in the form of a Photoshop design, drawn up by a bona-fide, turtle-neck-wearing designer, they were calmed. Marginally.

Because the design Ayende had was for the new-look RavenDb website.

He wanted me to take the look and feel and transfer it to the Silverlight Raven Studio application. Which, when he handed it over to me, looked like this:

Ahh! Where to start?

Photoshop for Developer Dummies

To ease myself in, I got started by simply trying to imitate parts of the Photoshop design in XAML, beginning with the header bar at the very top of the page. Not being a designer myself, I’m rather like a duck out of water when it comes to Photoshop, but I’ve at least got the basics sussed.

The thing to understand is that designers construct Photoshop images like onions, layer upon layer, sometimes eye-watering in complexity, and to reproduce the design, you have to peel down through the layers.

First go to Photoshop’s Layers pane, and make sure all the layers are unlocked. This allows the Move Layer tool to come into play, not to move layers, but identify layers by selecting them in the Layers pane when you click the corresponding part of the image. Once you’ve identified a layer, Alt-Click it, and all other layers in the image will be hidden, allowing you to figure out exactly how the thing should look.

Mostly when I’m paring down Photoshop layers I’m looking to isolate them so that I can figure out the colour gradients they use. You could, of course, navigate your way through Photoshop’s dialogs to read off the exact RGB values. Or, if you can get the layer on its lonesome, you can use Expression Blend’s Gradient Dropper tool.

This is a brilliant little timesaver. In the Blend Property pane, select the Brush property of your choice, put it into Gradient mode, click the Gradient Dropper tool, then drag over any area on screen, and Blend will reproduce the gradient under the cursor in XAML form.

After all that, I have the first feather of the new swan: a header bar matching the Photoshop design. Well, the background of the header bar. It needs fleshing out with some buttons.

Let it Live: Control Templates and Visual States

Silverlight, following WPF, has the concept of look-less controls. That is, the Controls (take Button as an example) manage their behaviour (Buttons respond to mouse clicks by executing commands) but don’t define how they are rendered on screen. That is left to the control’s Style, and specifically its ControlTemplate. The ControlTemplate defines the visual tree of all the UI elements needed to present the control and make it look snazzy. With a little patience, some assistance from Expression Blend, and plenty of application of the Gradient Dropper tool, it’s possible to take the built-in controls and make them look and feel just how the designer ordered.

I wanted Buttons that look like those in the header bar of the Photoshop design, but when the corresponding page is selected, they should change to have a background gradient with colours like the RavenDb logo.

When restyling a Control, it’s best to start by modifying the existing style. This way you can be sure you won’t miss an aspect of the control’s behaviour that you might otherwise forget. Blend makes this easy by giving you the option of editing a copy of the Control’s current ControlTemplate (right-click on it in the Objects and Timeline View, then select Edit Template > Edit a Copy). There are occasions when that little trick has failed, and I’ve ended up with an empty control template. But MSDN has come through for me then: it has a whole section containing the default Styles and Control Templates for all the built-in controls, like this one for Button.

Part of the ControlTemplate defines how the control looks in its various states, when the mouse is over it, when it has focus, or when it is selected, for example. The Control itself is responsible for indicating when it has entered each state. As a designer, it’s your job to specify Storyboards that are activated each time particular states are entered. Each Storyboard can animate whichever properties it likes to achieve the desired effect – in my Buttons, for example, I animate the opacity property of a Border element to fade in a coloured background indicating that it is selected. All this is overseen by the VisualStateManager, of which, more here. Naturally, Expression Blend has great editing support for visual states. Read John Papa’s tutorial to learn more.

So now I have a header bar with buttons that change colour when the corresponding page is selected. Where next?

Textured Backgrounds

Well, that page background could do with spicing up. The Photoshop design has a nice textured background, which I extracted to a PNG file that Silverlight would understand by hiding every layer except the background, then using Photoshop’s “Save for Web & Devices” feature.

The thing about textured backgrounds is that you do want them to cover the whole of the page background, which means tiling the texture to fill all the space. WPF makes this easy with its ImageBrush, which has a TileMode property, which, when set to a value other than None, automatically repeats the image over the whole area to be painted by the brush. Silverlight has ImageBrushes, but they don’t support tiling out of the box. Fortunately, Phil Middlemiss has supplied what is lacking in the form of the TiledBGControl which does exactly what I need – you should take a look: it makes clever use of Silverlight’s pixel shader effects.

This is what we’ve got so far.

The Index Editor Page, Before and After

Here are a couple of other pages I’ve beautified. First, the Index Editor page, as it was before:

And now:

Again, it was a challenge knowing where to apply my beautician’s brush first. I settled on adding the header bar at the top, and I then realised it could double up as a toolbar. Originally the page had no header at all, but by having a bread-crumb bar in the header it helps to give the user a bit more context when they’re looking at the page, as well as making it easier to navigate around.

Inspiration and Icons

Since my graphic-design skills are so underdeveloped, I borrow ideas shamelessly wherever I find something that fits. You may recognise the styling of the toolbar buttons in the Index page header bar as being remarkably similar to the ones on the Google Chrome toolbar. Yes – Expression Blend’s Gradient dropper does work on live applications too! Two places to check out if you find yourself short on inspiration are Quince and Pattern Tab which both catalogue examples of user interface and user experience design from across the web. Pattern Tab especially has myriad examples of beautiful UIs.

In the past I’ve struggled to find icons for my projects, but I’ve recently discovered two great sources: IconFinder.com and IconArchive.com. Both have excellent search facilities (which is often what’s missing from the commercial collections you buy and download to your machine in a whacking great zip file), and are careful to call out the license attached to each icon. A surprisingly large number are licensed so that they can be used without charge in commercial products.

A XAML Tip

The nice thing about styling an application is that it gets easier with every page you complete. Once you’ve settled on a look for a particular kind of element, you can repeat that look on every page. Silverlight’s support for Styles and Resources makes this very easy. And I have a tip that can make it easier still.

I put all my styles into a single resource dictionary, Styles.xaml which I merge into my App.xaml resource dictionary. I then name all my Styles, Brushes, etc. using a hierarchical naming convention. So Styles all begin with “Style_”, Styles for Buttons would all begin “Style_Button”, and then would come the styles for different purposes: “Style_Button_Toolbar”, “Style_Button_Hero” (for those big red buttons in your app that the hero uses to save the world), etc.. The pay-off for using this convention comes when you’re hand-editing XAML and making use of Resharper’s XAML intellisense. Type “{StaticResource Style_[ControlType]” and Resharper instantly presents you with a list of all the styles that might apply.

A Parting Screenshot

To finish, here’s one more before and after comparison, this time of the Edit Document page. Before:

And after:

You can begin to sense the benefit of using a consistent set of styles, as it brings a harmonious feel to the whole application.

I hope you’ve enjoyed this whistle-stop tour of the Raven Studio beautification process. Remember that all the code is available on GitHub. We’d love to hear what you think.

This is a guest post by Samuel Jack, who had done a lot of work on the new UI for RavenDB.

Three weeks ago Ayende put out a request for help in turning an ugly duckling into a beautiful swan, and I, rather nervously, signed up for the job. The ugly duckling in question was Raven Studio, the Silverlight-based management UI for Raven Db. The nerves were a result of doubting that my limited graphic design skills were up to the job. But when Ayende assured me that he had a proto-type swan in the form of a Photoshop design, drawn up by a bona-fide, turtle-neck-wearing designer, they were calmed. Marginally.

Because the design Ayende had was for the new-look RavenDb website.

He wanted me to take the look and feel and transfer it to the Silverlight Raven Studio application. Which, when he handed it over to me, looked like this:

Ahh! Where to start?

Photoshop for Developer Dummies

To ease myself in, I got started by simply trying to imitate parts of the Photoshop design in XAML, beginning with the header bar at the very top of the page. Not being a designer myself, I’m rather like a duck out of water when it comes to Photoshop, but I’ve at least got the basics sussed.

The thing to understand is that designers construct Photoshop images like onions, layer upon layer, sometimes eye-watering in complexity, and to reproduce the design, you have to peel down through the layers.

First go to Photoshop’s Layers pane, and make sure all the layers are unlocked. This allows the Move Layer tool to come into play, not to move layers, but identify layers by selecting them in the Layers pane when you click the corresponding part of the image. Once you’ve identified a layer, Alt-Click it, and all other layers in the image will be hidden, allowing you to figure out exactly how the thing should look.

Mostly when I’m paring down Photoshop layers I’m looking to isolate them so that I can figure out the colour gradients they use. You could, of course, navigate your way through Photoshop’s dialogs to read off the exact RGB values. Or, if you can get the layer on its lonesome, you can use Expression Blend’s Gradient Dropper tool.

This is a brilliant little timesaver. In the Blend Property pane, select the Brush property of your choice, put it into Gradient mode, click the Gradient Dropper tool, then drag over any area on screen, and Blend will reproduce the gradient under the cursor in XAML form.

After all that, I have the first feather of the new swan: a header bar matching the Photoshop design. Well, the background of the header bar. It needs fleshing out with some buttons.

Let it Live: Control Templates and Visual States

Silverlight, following WPF, has the concept of look-less controls. That is, the Controls (take Button as an example) manage their behaviour (Buttons respond to mouse clicks by executing commands) but don’t define how they are rendered on screen. That is left to the control’s Style, and specifically its ControlTemplate. The ControlTemplate defines the visual tree of all the UI elements needed to present the control and make it look snazzy. With a little patience, some assistance from Expression Blend, and plenty of application of the Gradient Dropper tool, it’s possible to take the built-in controls and make them look and feel just how the designer ordered.

I wanted Buttons that look like those in the header bar of the Photoshop design, but when the corresponding page is selected, they should change to have a background gradient with colours like the RavenDb logo.

When restyling a Control, it’s best to start by modifying the existing style. This way you can be sure you won’t miss an aspect of the control’s behaviour that you might otherwise forget. Blend makes this easy by giving you the option of editing a copy of the Control’s current ControlTemplate (right-click on it in the Objects and Timeline View, then select Edit Template > Edit a Copy). There are occasions when that little trick has failed, and I’ve ended up with an empty control template. But MSDN has come through for me then: it has a whole section containing the default Styles and Control Templates for all the built-in controls, like this one for Button.

Part of the ControlTemplate defines how the control looks in its various states, when the mouse is over it, when it has focus, or when it is selected, for example. The Control itself is responsible for indicating when it has entered each state. As a designer, it’s your job to specify Storyboards that are activated each time particular states are entered. Each Storyboard can animate whichever properties it likes to achieve the desired effect – in my Buttons, for example, I animate the opacity property of a Border element to fade in a coloured background indicating that it is selected. All this is overseen by the VisualStateManager, of which, more here. Naturally, Expression Blend has great editing support for visual states. Read John Papa’s tutorial to learn more.

So now I have a header bar with buttons that change colour when the corresponding page is selected. Where next?

Textured Backgrounds

Well, that page background could do with spicing up. The Photoshop design has a nice textured background, which I extracted to a PNG file that Silverlight would understand by hiding every layer except the background, then using Photoshop’s “Save for Web & Devices” feature.

The thing about textured backgrounds is that you do want them to cover the whole of the page background, which means tiling the texture to fill all the space. WPF makes this easy with its ImageBrush, which has a TileMode property, which, when set to a value other than None, automatically repeats the image over the whole area to be painted by the brush. Silverlight has ImageBrushes, but they don’t support tiling out of the box. Fortunately, Phil Middlemiss has supplied what is lacking in the form of the TiledBGControl which does exactly what I need – you should take a look: it makes clever use of Silverlight’s pixel shader effects.

This is what we’ve got so far.

The Index Editor Page, Before and After

Here are a couple of other pages I’ve beautified. First, the Index Editor page, as it was before:

And now:

Again, it was a challenge knowing where to apply my beautician’s brush first. I settled on adding the header bar at the top, and I then realised it could double up as a toolbar. Originally the page had no header at all, but by having a bread-crumb bar in the header it helps to give the user a bit more context when they’re looking at the page, as well as making it easier to navigate around.

Inspiration and Icons

Since my graphic-design skills are so underdeveloped, I borrow ideas shamelessly wherever I find something that fits. You may recognise the styling of the toolbar buttons in the Index page header bar as being remarkably similar to the ones on the Google Chrome toolbar. Yes – Expression Blend’s Gradient dropper does work on live applications too! Two places to check out if you find yourself short on inspiration are Quince and Pattern Tab which both catalogue examples of user interface and user experience design from across the web. Pattern Tab especially has myriad examples of beautiful UIs.

In the past I’ve struggled to find icons for my projects, but I’ve recently discovered two great sources: IconFinder.com and IconArchive.com. Both have excellent search facilities (which is often what’s missing from the commercial collections you buy and download to your machine in a whacking great zip file), and are careful to call out the license attached to each icon. A surprisingly large number are licensed so that they can be used without charge in commercial products.

A XAML Tip

The nice thing about styling an application is that it gets easier with every page you complete. Once you’ve settled on a look for a particular kind of element, you can repeat that look on every page. Silverlight’s support for Styles and Resources makes this very easy. And I have a tip that can make it easier still.

I put all my styles into a single resource dictionary, Styles.xaml which I merge into my App.xaml resource dictionary. I then name all my Styles, Brushes, etc. using a hierarchical naming convention. So Styles all begin with “Style_”, Styles for Buttons would all begin “Style_Button”, and then would come the styles for different purposes: “Style_Button_Toolbar”, “Style_Button_Hero” (for those big red buttons in your app that the hero uses to save the world), etc.. The pay-off for using this convention comes when you’re hand-editing XAML and making use of Resharper’s XAML intellisense. Type “{StaticResource Style_[ControlType]” and Resharper instantly presents you with a list of all the styles that might apply.

A Parting Screenshot

To finish, here’s one more before and after comparison, this time of the Edit Document page. Before:

And after:

You can begin to sense the benefit of using a consistent set of styles, as it brings a harmonious feel to the whole application.

I hope you’ve enjoyed this whistle-stop tour of the Raven Studio beautification process. Remember that all the code is available on GitHub. We’d love to hear what you think.

This is a guest post by Samuel Jack, who had done a lot of work on the new UI for RavenDB.

Three weeks ago Ayende put out a request for help in turning an ugly duckling into a beautiful swan, and I, rather nervously, signed up for the job. The ugly duckling in question was Raven Studio, the Silverlight-based management UI for Raven Db. The nerves were a result of doubting that my limited graphic design skills were up to the job. But when Ayende assured me that he had a proto-type swan in the form of a Photoshop design, drawn up by a bona-fide, turtle-neck-wearing designer, they were calmed. Marginally.

Because the design Ayende had was for the new-look RavenDb website.

He wanted me to take the look and feel and transfer it to the Silverlight Raven Studio application. Which, when he handed it over to me, looked like this:

Ahh! Where to start?

Photoshop for Developer Dummies

To ease myself in, I got started by simply trying to imitate parts of the Photoshop design in XAML, beginning with the header bar at the very top of the page. Not being a designer myself, I’m rather like a duck out of water when it comes to Photoshop, but I’ve at least got the basics sussed.

The thing to understand is that designers construct Photoshop images like onions, layer upon layer, sometimes eye-watering in complexity, and to reproduce the design, you have to peel down through the layers.

First go to Photoshop’s Layers pane, and make sure all the layers are unlocked. This allows the Move Layer tool to come into play, not to move layers, but identify layers by selecting them in the Layers pane when you click the corresponding part of the image. Once you’ve identified a layer, Alt-Click it, and all other layers in the image will be hidden, allowing you to figure out exactly how the thing should look.

Mostly when I’m paring down Photoshop layers I’m looking to isolate them so that I can figure out the colour gradients they use. You could, of course, navigate your way through Photoshop’s dialogs to read off the exact RGB values. Or, if you can get the layer on its lonesome, you can use Expression Blend’s Gradient Dropper tool.

This is a brilliant little timesaver. In the Blend Property pane, select the Brush property of your choice, put it into Gradient mode, click the Gradient Dropper tool, then drag over any area on screen, and Blend will reproduce the gradient under the cursor in XAML form.

After all that, I have the first feather of the new swan: a header bar matching the Photoshop design. Well, the background of the header bar. It needs fleshing out with some buttons.

Let it Live: Control Templates and Visual States

Silverlight, following WPF, has the concept of look-less controls. That is, the Controls (take Button as an example) manage their behaviour (Buttons respond to mouse clicks by executing commands) but don’t define how they are rendered on screen. That is left to the control’s Style, and specifically its ControlTemplate. The ControlTemplate defines the visual tree of all the UI elements needed to present the control and make it look snazzy. With a little patience, some assistance from Expression Blend, and plenty of application of the Gradient Dropper tool, it’s possible to take the built-in controls and make them look and feel just how the designer ordered.

I wanted Buttons that look like those in the header bar of the Photoshop design, but when the corresponding page is selected, they should change to have a background gradient with colours like the RavenDb logo.

When restyling a Control, it’s best to start by modifying the existing style. This way you can be sure you won’t miss an aspect of the control’s behaviour that you might otherwise forget. Blend makes this easy by giving you the option of editing a copy of the Control’s current ControlTemplate (right-click on it in the Objects and Timeline View, then select Edit Template > Edit a Copy). There are occasions when that little trick has failed, and I’ve ended up with an empty control template. But MSDN has come through for me then: it has a whole section containing the default Styles and Control Templates for all the built-in controls, like this one for Button.

Part of the ControlTemplate defines how the control looks in its various states, when the mouse is over it, when it has focus, or when it is selected, for example. The Control itself is responsible for indicating when it has entered each state. As a designer, it’s your job to specify Storyboards that are activated each time particular states are entered. Each Storyboard can animate whichever properties it likes to achieve the desired effect – in my Buttons, for example, I animate the opacity property of a Border element to fade in a coloured background indicating that it is selected. All this is overseen by the VisualStateManager, of which, more here. Naturally, Expression Blend has great editing support for visual states. Read John Papa’s tutorial to learn more.

So now I have a header bar with buttons that change colour when the corresponding page is selected. Where next?

Textured Backgrounds

Well, that page background could do with spicing up. The Photoshop design has a nice textured background, which I extracted to a PNG file that Silverlight would understand by hiding every layer except the background, then using Photoshop’s “Save for Web & Devices” feature.

The thing about textured backgrounds is that you do want them to cover the whole of the page background, which means tiling the texture to fill all the space. WPF makes this easy with its ImageBrush, which has a TileMode property, which, when set to a value other than None, automatically repeats the image over the whole area to be painted by the brush. Silverlight has ImageBrushes, but they don’t support tiling out of the box. Fortunately, Phil Middlemiss has supplied what is lacking in the form of the TiledBGControl which does exactly what I need – you should take a look: it makes clever use of Silverlight’s pixel shader effects.

This is what we’ve got so far.

The Index Editor Page, Before and After

Here are a couple of other pages I’ve beautified. First, the Index Editor page, as it was before:

And now:

Again, it was a challenge knowing where to apply my beautician’s brush first. I settled on adding the header bar at the top, and I then realised it could double up as a toolbar. Originally the page had no header at all, but by having a bread-crumb bar in the header it helps to give the user a bit more context when they’re looking at the page, as well as making it easier to navigate around.

Inspiration and Icons

Since my graphic-design skills are so underdeveloped, I borrow ideas shamelessly wherever I find something that fits. You may recognise the styling of the toolbar buttons in the Index page header bar as being remarkably similar to the ones on the Google Chrome toolbar. Yes – Expression Blend’s Gradient dropper does work on live applications too! Two places to check out if you find yourself short on inspiration are Quince and Pattern Tab which both catalogue examples of user interface and user experience design from across the web. Pattern Tab especially has myriad examples of beautiful UIs.

In the past I’ve struggled to find icons for my projects, but I’ve recently discovered two great sources: IconFinder.com and IconArchive.com. Both have excellent search facilities (which is often what’s missing from the commercial collections you buy and download to your machine in a whacking great zip file), and are careful to call out the license attached to each icon. A surprisingly large number are licensed so that they can be used without charge in commercial products.

A XAML Tip

The nice thing about styling an application is that it gets easier with every page you complete. Once you’ve settled on a look for a particular kind of element, you can repeat that look on every page. Silverlight’s support for Styles and Resources makes this very easy. And I have a tip that can make it easier still.

I put all my styles into a single resource dictionary, Styles.xaml which I merge into my App.xaml resource dictionary. I then name all my Styles, Brushes, etc. using a hierarchical naming convention. So Styles all begin with “Style_”, Styles for Buttons would all begin “Style_Button”, and then would come the styles for different purposes: “Style_Button_Toolbar”, “Style_Button_Hero” (for those big red buttons in your app that the hero uses to save the world), etc.. The pay-off for using this convention comes when you’re hand-editing XAML and making use of Resharper’s XAML intellisense. Type “{StaticResource Style_[ControlType]” and Resharper instantly presents you with a list of all the styles that might apply.

A Parting Screenshot

To finish, here’s one more before and after comparison, this time of the Edit Document page. Before:

And after:

You can begin to sense the benefit of using a consistent set of styles, as it brings a harmonious feel to the whole application.

I hope you’ve enjoyed this whistle-stop tour of the Raven Studio beautification process. Remember that all the code is available on GitHub. We’d love to hear what you think.

This is a guest post by Samuel Jack, who had done a lot of work on the new UI for RavenDB.

Three weeks ago Ayende put out a request for help in turning an ugly duckling into a beautiful swan, and I, rather nervously, signed up for the job. The ugly duckling in question was Raven Studio, the Silverlight-based management UI for Raven Db. The nerves were a result of doubting that my limited graphic design skills were up to the job. But when Ayende assured me that he had a proto-type swan in the form of a Photoshop design, drawn up by a bona-fide, turtle-neck-wearing designer, they were calmed. Marginally.

Because the design Ayende had was for the new-look RavenDb website.

He wanted me to take the look and feel and transfer it to the Silverlight Raven Studio application. Which, when he handed it over to me, looked like this:

Ahh! Where to start?

Photoshop for Developer Dummies

To ease myself in, I got started by simply trying to imitate parts of the Photoshop design in XAML, beginning with the header bar at the very top of the page. Not being a designer myself, I’m rather like a duck out of water when it comes to Photoshop, but I’ve at least got the basics sussed.

The thing to understand is that designers construct Photoshop images like onions, layer upon layer, sometimes eye-watering in complexity, and to reproduce the design, you have to peel down through the layers.

First go to Photoshop’s Layers pane, and make sure all the layers are unlocked. This allows the Move Layer tool to come into play, not to move layers, but identify layers by selecting them in the Layers pane when you click the corresponding part of the image. Once you’ve identified a layer, Alt-Click it, and all other layers in the image will be hidden, allowing you to figure out exactly how the thing should look.

Mostly when I’m paring down Photoshop layers I’m looking to isolate them so that I can figure out the colour gradients they use. You could, of course, navigate your way through Photoshop’s dialogs to read off the exact RGB values. Or, if you can get the layer on its lonesome, you can use Expression Blend’s Gradient Dropper tool.

This is a brilliant little timesaver. In the Blend Property pane, select the Brush property of your choice, put it into Gradient mode, click the Gradient Dropper tool, then drag over any area on screen, and Blend will reproduce the gradient under the cursor in XAML form.

After all that, I have the first feather of the new swan: a header bar matching the Photoshop design. Well, the background of the header bar. It needs fleshing out with some buttons.

Let it Live: Control Templates and Visual States

Silverlight, following WPF, has the concept of look-less controls. That is, the Controls (take Button as an example) manage their behaviour (Buttons respond to mouse clicks by executing commands) but don’t define how they are rendered on screen. That is left to the control’s Style, and specifically its ControlTemplate. The ControlTemplate defines the visual tree of all the UI elements needed to present the control and make it look snazzy. With a little patience, some assistance from Expression Blend, and plenty of application of the Gradient Dropper tool, it’s possible to take the built-in controls and make them look and feel just how the designer ordered.

I wanted Buttons that look like those in the header bar of the Photoshop design, but when the corresponding page is selected, they should change to have a background gradient with colours like the RavenDb logo.

When restyling a Control, it’s best to start by modifying the existing style. This way you can be sure you won’t miss an aspect of the control’s behaviour that you might otherwise forget. Blend makes this easy by giving you the option of editing a copy of the Control’s current ControlTemplate (right-click on it in the Objects and Timeline View, then select Edit Template > Edit a Copy). There are occasions when that little trick has failed, and I’ve ended up with an empty control template. But MSDN has come through for me then: it has a whole section containing the default Styles and Control Templates for all the built-in controls, like this one for Button.

Part of the ControlTemplate defines how the control looks in its various states, when the mouse is over it, when it has focus, or when it is selected, for example. The Control itself is responsible for indicating when it has entered each state. As a designer, it’s your job to specify Storyboards that are activated each time particular states are entered. Each Storyboard can animate whichever properties it likes to achieve the desired effect – in my Buttons, for example, I animate the opacity property of a Border element to fade in a coloured background indicating that it is selected. All this is overseen by the VisualStateManager, of which, more here. Naturally, Expression Blend has great editing support for visual states. Read John Papa’s tutorial to learn more.

So now I have a header bar with buttons that change colour when the corresponding page is selected. Where next?

Textured Backgrounds

Well, that page background could do with spicing up. The Photoshop design has a nice textured background, which I extracted to a PNG file that Silverlight would understand by hiding every layer except the background, then using Photoshop’s “Save for Web & Devices” feature.

The thing about textured backgrounds is that you do want them to cover the whole of the page background, which means tiling the texture to fill all the space. WPF makes this easy with its ImageBrush, which has a TileMode property, which, when set to a value other than None, automatically repeats the image over the whole area to be painted by the brush. Silverlight has ImageBrushes, but they don’t support tiling out of the box. Fortunately, Phil Middlemiss has supplied what is lacking in the form of the TiledBGControl which does exactly what I need – you should take a look: it makes clever use of Silverlight’s pixel shader effects.

This is what we’ve got so far.

The Index Editor Page, Before and After

Here are a couple of other pages I’ve beautified. First, the Index Editor page, as it was before:

And now:

Again, it was a challenge knowing where to apply my beautician’s brush first. I settled on adding the header bar at the top, and I then realised it could double up as a toolbar. Originally the page had no header at all, but by having a bread-crumb bar in the header it helps to give the user a bit more context when they’re looking at the page, as well as making it easier to navigate around.

Inspiration and Icons

Since my graphic-design skills are so underdeveloped, I borrow ideas shamelessly wherever I find something that fits. You may recognise the styling of the toolbar buttons in the Index page header bar as being remarkably similar to the ones on the Google Chrome toolbar. Yes – Expression Blend’s Gradient dropper does work on live applications too! Two places to check out if you find yourself short on inspiration are Quince and Pattern Tab which both catalogue examples of user interface and user experience design from across the web. Pattern Tab especially has myriad examples of beautiful UIs.

In the past I’ve struggled to find icons for my projects, but I’ve recently discovered two great sources: IconFinder.com and IconArchive.com. Both have excellent search facilities (which is often what’s missing from the commercial collections you buy and download to your machine in a whacking great zip file), and are careful to call out the license attached to each icon. A surprisingly large number are licensed so that they can be used without charge in commercial products.

A XAML Tip

The nice thing about styling an application is that it gets easier with every page you complete. Once you’ve settled on a look for a particular kind of element, you can repeat that look on every page. Silverlight’s support for Styles and Resources makes this very easy. And I have a tip that can make it easier still.

I put all my styles into a single resource dictionary, Styles.xaml which I merge into my App.xaml resource dictionary. I then name all my Styles, Brushes, etc. using a hierarchical naming convention. So Styles all begin with “Style_”, Styles for Buttons would all begin “Style_Button”, and then would come the styles for different purposes: “Style_Button_Toolbar”, “Style_Button_Hero” (for those big red buttons in your app that the hero uses to save the world), etc.. The pay-off for using this convention comes when you’re hand-editing XAML and making use of Resharper’s XAML intellisense. Type “{StaticResource Style_[ControlType]” and Resharper instantly presents you with a list of all the styles that might apply.

A Parting Screenshot

To finish, here’s one more before and after comparison, this time of the Edit Document page. Before:

And after:

You can begin to sense the benefit of using a consistent set of styles, as it brings a harmonious feel to the whole application.

I hope you’ve enjoyed this whistle-stop tour of the Raven Studio beautification process. Remember that all the code is available on GitHub. We’d love to hear what you think.

This is a guest post by Samuel Jack, who had done a lot of work on the new UI for RavenDB.

Three weeks ago Ayende put out a request for help in turning an ugly duckling into a beautiful swan, and I, rather nervously, signed up for the job. The ugly duckling in question was Raven Studio, the Silverlight-based management UI for Raven Db. The nerves were a result of doubting that my limited graphic design skills were up to the job. But when Ayende assured me that he had a proto-type swan in the form of a Photoshop design, drawn up by a bona-fide, turtle-neck-wearing designer, they were calmed. Marginally.

Because the design Ayende had was for the new-look RavenDb website.

He wanted me to take the look and feel and transfer it to the Silverlight Raven Studio application. Which, when he handed it over to me, looked like this:

Ahh! Where to start?

Photoshop for Developer Dummies

To ease myself in, I got started by simply trying to imitate parts of the Photoshop design in XAML, beginning with the header bar at the very top of the page. Not being a designer myself, I’m rather like a duck out of water when it comes to Photoshop, but I’ve at least got the basics sussed.

The thing to understand is that designers construct Photoshop images like onions, layer upon layer, sometimes eye-watering in complexity, and to reproduce the design, you have to peel down through the layers.

First go to Photoshop’s Layers pane, and make sure all the layers are unlocked. This allows the Move Layer tool to come into play, not to move layers, but identify layers by selecting them in the Layers pane when you click the corresponding part of the image. Once you’ve identified a layer, Alt-Click it, and all other layers in the image will be hidden, allowing you to figure out exactly how the thing should look.

Mostly when I’m paring down Photoshop layers I’m looking to isolate them so that I can figure out the colour gradients they use. You could, of course, navigate your way through Photoshop’s dialogs to read off the exact RGB values. Or, if you can get the layer on its lonesome, you can use Expression Blend’s Gradient Dropper tool.

This is a brilliant little timesaver. In the Blend Property pane, select the Brush property of your choice, put it into Gradient mode, click the Gradient Dropper tool, then drag over any area on screen, and Blend will reproduce the gradient under the cursor in XAML form.

After all that, I have the first feather of the new swan: a header bar matching the Photoshop design. Well, the background of the header bar. It needs fleshing out with some buttons.

Let it Live: Control Templates and Visual States

Silverlight, following WPF, has the concept of look-less controls. That is, the Controls (take Button as an example) manage their behaviour (Buttons respond to mouse clicks by executing commands) but don’t define how they are rendered on screen. That is left to the control’s Style, and specifically its ControlTemplate. The ControlTemplate defines the visual tree of all the UI elements needed to present the control and make it look snazzy. With a little patience, some assistance from Expression Blend, and plenty of application of the Gradient Dropper tool, it’s possible to take the built-in controls and make them look and feel just how the designer ordered.

I wanted Buttons that look like those in the header bar of the Photoshop design, but when the corresponding page is selected, they should change to have a background gradient with colours like the RavenDb logo.

When restyling a Control, it’s best to start by modifying the existing style. This way you can be sure you won’t miss an aspect of the control’s behaviour that you might otherwise forget. Blend makes this easy by giving you the option of editing a copy of the Control’s current ControlTemplate (right-click on it in the Objects and Timeline View, then select Edit Template > Edit a Copy). There are occasions when that little trick has failed, and I’ve ended up with an empty control template. But MSDN has come through for me then: it has a whole section containing the default Styles and Control Templates for all the built-in controls, like this one for Button.

Part of the ControlTemplate defines how the control looks in its various states, when the mouse is over it, when it has focus, or when it is selected, for example. The Control itself is responsible for indicating when it has entered each state. As a designer, it’s your job to specify Storyboards that are activated each time particular states are entered. Each Storyboard can animate whichever properties it likes to achieve the desired effect – in my Buttons, for example, I animate the opacity property of a Border element to fade in a coloured background indicating that it is selected. All this is overseen by the VisualStateManager, of which, more here. Naturally, Expression Blend has great editing support for visual states. Read John Papa’s tutorial to learn more.

So now I have a header bar with buttons that change colour when the corresponding page is selected. Where next?

Textured Backgrounds

Well, that page background could do with spicing up. The Photoshop design has a nice textured background, which I extracted to a PNG file that Silverlight would understand by hiding every layer except the background, then using Photoshop’s “Save for Web & Devices” feature.

The thing about textured backgrounds is that you do want them to cover the whole of the page background, which means tiling the texture to fill all the space. WPF makes this easy with its ImageBrush, which has a TileMode property, which, when set to a value other than None, automatically repeats the image over the whole area to be painted by the brush. Silverlight has ImageBrushes, but they don’t support tiling out of the box. Fortunately, Phil Middlemiss has supplied what is lacking in the form of the TiledBGControl which does exactly what I need – you should take a look: it makes clever use of Silverlight’s pixel shader effects.

This is what we’ve got so far.

The Index Editor Page, Before and After

Here are a couple of other pages I’ve beautified. First, the Index Editor page, as it was before:

And now:

Again, it was a challenge knowing where to apply my beautician’s brush first. I settled on adding the header bar at the top, and I then realised it could double up as a toolbar. Originally the page had no header at all, but by having a bread-crumb bar in the header it helps to give the user a bit more context when they’re looking at the page, as well as making it easier to navigate around.

Inspiration and Icons

Since my graphic-design skills are so underdeveloped, I borrow ideas shamelessly wherever I find something that fits. You may recognise the styling of the toolbar buttons in the Index page header bar as being remarkably similar to the ones on the Google Chrome toolbar. Yes – Expression Blend’s Gradient dropper does work on live applications too! Two places to check out if you find yourself short on inspiration are Quince and Pattern Tab which both catalogue examples of user interface and user experience design from across the web. Pattern Tab especially has myriad examples of beautiful UIs.

In the past I’ve struggled to find icons for my projects, but I’ve recently discovered two great sources: IconFinder.com and IconArchive.com. Both have excellent search facilities (which is often what’s missing from the commercial collections you buy and download to your machine in a whacking great zip file), and are careful to call out the license attached to each icon. A surprisingly large number are licensed so that they can be used without charge in commercial products.

A XAML Tip

The nice thing about styling an application is that it gets easier with every page you complete. Once you’ve settled on a look for a particular kind of element, you can repeat that look on every page. Silverlight’s support for Styles and Resources makes this very easy. And I have a tip that can make it easier still.

I put all my styles into a single resource dictionary, Styles.xaml which I merge into my App.xaml resource dictionary. I then name all my Styles, Brushes, etc. using a hierarchical naming convention. So Styles all begin with “Style_”, Styles for Buttons would all begin “Style_Button”, and then would come the styles for different purposes: “Style_Button_Toolbar”, “Style_Button_Hero” (for those big red buttons in your app that the hero uses to save the world), etc.. The pay-off for using this convention comes when you’re hand-editing XAML and making use of Resharper’s XAML intellisense. Type “{StaticResource Style_[ControlType]” and Resharper instantly presents you with a list of all the styles that might apply.

A Parting Screenshot

To finish, here’s one more before and after comparison, this time of the Edit Document page. Before:

And after:

You can begin to sense the benefit of using a consistent set of styles, as it brings a harmonious feel to the whole application.

I hope you’ve enjoyed this whistle-stop tour of the Raven Studio beautification process. Remember that all the code is available on GitHub. We’d love to hear what you think.

The first ever RavenDB webinar aired last week, Thursday the 8th, and it was a great success. We announced it only about 12 hours in advance, yet 260+ people registered. Unfortunately the software we were using only allowed 100 people in – our apologies for all of you who wanted to participate but couldn’t get in, or heard of it too late.

We have now uploaded the recording to our YouTube channel here, and you can watch it from there. Embedded here is the first part:

The other parts are available from our YouTube channel: www.youtube.com/user/HibernatingRhinos.

We had a second webinar last Friday, and had a very good Q&A session during it. Unfortunately _someone_ forgot to press the “Record” button, and there we are all left with no recording…

RavenDB webinars are here to stay. We are still formulating our plans for future webcasts – both in terms of a format and topics. The general idea is that whenever there will be enough demand, we will do a webcast on a specific topic, or just a Q&A session. Ideally we would like to have a bi-weekly session, and by the time we settle on a format you can expect many more spontaneous sessions like we had last week…

This is why we would really like to hear back from you. What are you looking for to have, when, in what format. Any other feedback – here or in the RavenDB mailing list – is definitely welcome.

See you all in our next webinars…

The first ever RavenDB webinar aired last week, Thursday the 8th, and it was a great success. We announced it only about 12 hours in advance, yet 260+ people registered. Unfortunately the software we were using only allowed 100 people in – our apologies for all of you who wanted to participate but couldn’t get in, or heard of it too late.

We have now uploaded the recording to our YouTube channel here, and you can watch it from there. Embedded here is the first part:

The other parts are available from our YouTube channel: www.youtube.com/user/HibernatingRhinos.

We had a second webinar last Friday, and had a very good Q&A session during it. Unfortunately _someone_ forgot to press the “Record” button, and there we are all left with no recording…

RavenDB webinars are here to stay. We are still formulating our plans for future webcasts – both in terms of a format and topics. The general idea is that whenever there will be enough demand, we will do a webcast on a specific topic, or just a Q&A session. Ideally we would like to have a bi-weekly session, and by the time we settle on a format you can expect many more spontaneous sessions like we had last week…

This is why we would really like to hear back from you. What are you looking for to have, when, in what format. Any other feedback – here or in the RavenDB mailing list – is definitely welcome.

See you all in our next webinars…

Our mailing list is probably the most responsive one around. Nevertheless, we thought having an IRC channel could come in handy, so the community would have a place to hang around in, and perhaps also get questions answered quicker once the channel gets big enough.

Come visit us at #RavenDB on Freenode!

BTW - There are quite a few free web UIs available if you don't want to install any software, see http://webchat.freenode.net/ for example

Our mailing list is probably the most responsive one around. Nevertheless, we thought having an IRC channel could come in handy, so the community would have a place to hang around in, and perhaps also get questions answered quicker once the channel gets big enough.

Come visit us at #RavenDB on Freenode!

BTW - There are quite a few free web UIs available if you don't want to install any software, see http://webchat.freenode.net/ for example

RavenDB is already a very mature product: the official release was over a year ago, and it is already being used in production by several companies, some for about a year now. Before the official release, RavenDB has been in development for about 2.5 years, totaling more than 3.5 years of active, daily development now. Today we are mainly working on performance improvements, and on perfecting what’s already there.

So much effort has been put into development, that proper documentation was consistently lagging behind. We worked very hard on creating the most awesome document-oriented database around, that we hardly put any thought on visibility, and on spreading the word.

Now that the API has stabilized, and the product is definitely in a very good shape to say the least, it is time to redirect some efforts for making the documentation more comprehensive and up-to-date, and for letting people know how awesome RavenDB is.

The first step for doing this is giving RavenDB a face, a logo, something that people would recognize. After a few weeks of work and polls, we now have a final logo:

We are already hard at work on the next steps – redesigning the website, and creating better user experience with it. Documentation is also catching up quite nicely, and we will soon be blogging about this separately (there’s much to tell…).

You can now also follow the RavenDB project on Twitter: @RavenDB . Starting today, we will be posting updates there as well.

Stay tuned while we work on making RavenDB even more awesome!

RavenDB is already a very mature product: the official release was over a year ago, and it is already being used in production by several companies, some for about a year now. Before the official release, RavenDB has been in development for about 2.5 years, totaling more than 3.5 years of active, daily development now. Today we are mainly working on performance improvements, and on perfecting what’s already there.

So much effort has been put into development, that proper documentation was consistently lagging behind. We worked very hard on creating the most awesome document-oriented database around, that we hardly put any thought on visibility, and on spreading the word.

Now that the API has stabilized, and the product is definitely in a very good shape to say the least, it is time to redirect some efforts for making the documentation more comprehensive and up-to-date, and for letting people know how awesome RavenDB is.

The first step for doing this is giving RavenDB a face, a logo, something that people would recognize. After a few weeks of work and polls, we now have a final logo:

We are already hard at work on the next steps – redesigning the website, and creating better user experience with it. Documentation is also catching up quite nicely, and we will soon be blogging about this separately (there’s much to tell…).

You can now also follow the RavenDB project on Twitter: @RavenDB . Starting today, we will be posting updates there as well.

Stay tuned while we work on making RavenDB even more awesome!

When we built the RavenDB profiling support, we intentionally built it in such a way that you can have multiple ways of accessing it.

Out of the box, we come with a VS debugger visualizer and an MVC Profiler for your websites. The VS Debugger Visualizer is pretty ugly (fully functional, of course, just not that pretty), but we are very proud of the MVC Profiler support and how it looks:

The real fun part is that we aren’t the only ones that can access those API, the screen shot below was taken from a Glimpse extension that adds RavenDB Profiling support:

That is quite impressive, even if I say so myself, and it shows what happen when you aren’t overly fond of the internal keyword.

When we built the RavenDB profiling support, we intentionally built it in such a way that you can have multiple ways of accessing it.

Out of the box, we come with a VS debugger visualizer and an MVC Profiler for your websites. The VS Debugger Visualizer is pretty ugly (fully functional, of course, just not that pretty), but we are very proud of the MVC Profiler support and how it looks:

The real fun part is that we aren’t the only ones that can access those API, the screen shot below was taken from a Glimpse extension that adds RavenDB Profiling support:

That is quite impressive, even if I say so myself, and it shows what happen when you aren’t overly fond of the internal keyword.

This series is about how to start using RavenDB without any prior knowledge about Document Databases. There is assumption that you’re familiar with Relational Databases like Sql Server, though.

In the introduction post of this series I briefly examined what is a Document Database, what is a document and how RavenDB Management Studio looks like. Now it’s time to show you how to actually use RavenDB in your applications. So let’s talk about the client API.

The target of this post is to show you how to use the client API: we’ll start by creating a basic model entity, than we’re going to store an instance of this entity in RavenDB database, then load a entity and update it. Finally, I’m going to show you how to do some more complex queries.

You can use RavenDB from any language or platform (more on that in a future blog post). In this blog post we’re going to use the .NET client API which let you consume RavenDB from any .NET application very easily.

Let’s create an empty ASP.NET MVC application and add the following the RavenDB NuGet package to it:

After the RavenDB NuGet package has been installed you’re ready to start use RavenDB from the MVC application that we created. But we need first need to make sure that we have a RavenDB database to connect to. In order to that, run the RavenDB console application as we did in the previous post, and edit the connection string in the web.config to point to the correct server URL:

  <connectionStrings>
    <add name="RavenDB" connectionString="Url=http://localhost:8080" />
  </connectionStrings>

Now that we have RavenDB and the Client API set up, it’s time to do something interesting with it. In order to start interacting with RavenDB with the Client API you’ll need to create an instance of the IDocumentSession and the IDocumentStore. The session is define the boundaries of your Unit Of Work, which will be in a typical web application the entire web request, and the IDocumentStore lets you create sessions. It’s a good practice to create one instance of IDocumentStore per application and one session per unit of work.

Showing how to effectively managing the session in a web application is out of the scope of this blog post (which require us talking us to talk about IoC patterns), but you can take a look on the RaccoonBlog project in order to see one simple approach to achieve this. The RaccoonBlog project was created specifically for demonstration purposes in this blog posts series and it’s now the blog engine that we use to run this blog).

For this demonstration we’re going to create the session and the document store directly in the controller. As specified in the above paragraph, in real applications you’ll typically want to manage the session out of the controller.

public class ProductController : Controller
{
    private static readonly IDocumentStore documentStore;
    private IDocumentSession _session;

    static ProductController()
    {
        documentStore = new DocumentStore
                            {
                                ConnectionStringName = "RavenDB"
                            }.Initialize();

    }

    protected override void OnActionExecuting(ActionExecutingContext filterContext)
    {
        _session = documentStore.OpenSession();
    }

    protected override void OnActionExecuted(ActionExecutedContext filterContext)
    {
        _session.SaveChanges();
        _session.Dispose();
    }
}

Now that we have the session in place, we can start using it to do CRUD operations on the database. Consider the following Product entity which we’re going to use in this blog post:

public class Product
{
    public string Id { get; set; }
    public string CategoryId { get; set; }
    public string SupplierId { get; set; }

    public string Name { get; set; }
    public string Code { get; set; }
    public decimal StandardCost { get; set; }
    public decimal ListPrice { get; set; }
    public int UnitsOnStock { get; set; }
    public int UnitsOnOrder { get; set; }
    public bool Discontinued { get; set; }

    public string PhotoFile { get; set; }
    public DateTime CreatedAt { get; set; }
}

Let’s create an instance of this entity and store it into the database:

public ActionResult StoreSomeProductInDatabase()
{
    var product = new Product
                    {
                        Name = "Product Name",
                        CategoryId = "category/1024",
                        SupplierId = "supplier/16",
                        Code = "H11050",
                        CreatedAt = DateTime.Now,
                        StandardCost = 250,
                        ListPrice = 189,
                        FilePhoto = "path to picture.jpg",
                    };
    _session.Store(product);
    _session.SaveChanges();

    return Content(product.Id);
}

First we’re creating a product and storing it in the session. I said we’re storing it in the session because when you call the _session.Store(product) method it wouldn’t send the product to the database yet. In order to actually save the product in the database you’ll need to call the _session.SaveChanges(). Note that after you call the _session.SaveChanges() method we can use the product.Id, which will be “products/1”. We didn’t assign that Id manually but let the client API assigns it to us automatically. If you’ll look on the RavenDB console application you’ll see the following log output:

Raven is ready to process requests. Build 385, Version 1.0.0.0 / 64f1188
Server started in 2,519 ms
Data directory: C:\Users\Fitzchak\Downloads\RavenDB-Unstable-Build-385\Server\Data
HostName: <any> Port: 8080, Storage: Esent
Server Url: http://fitzchak-pc:8080/
Press <enter> to stop or 'cls' and <enter> to clear the log
Request #   1: GET     -    26 ms - <default>  - 404 - /docs/Raven/Replication/Destinations
Request #   2: GET     -     0 ms - <default>  - 404 - /docs/Raven/Hilo/products
Request #   3: PUT     -   241 ms - <default>  - 201 - /docs/Raven/Hilo/products
Request #   4: POST    -    44 ms - <default>  - 200 - /bulk_docs
        PUT products/1

At request #4 we can see the actual post request which will store the products/1 document. We got response status #200 which means that the document is successfully stored in the database. In addition you can see that we do not need to query the database and ask what was the generated id for our product (which is a typically case with auto increase field implementation in relational databases), because the Id is generated by the client API (which use the HiLo algorithm to generate it). This “magic” happens in request #2 and #3 which we’ll be covered in the upcoming posts.

You can look on the RavenDB Management Studio in order to see the documents that we just stored:

We could have also store a lot of products in the session and than call the SaveChanges which will insert all of them to the database with just one call:

public ActionResult InsertSomeMoreProducts()
{
    for (int i = 0; i < 50; i++)
    {
        var product = new Product
        {
            Name = "Product Name " + i,
            CategoryId = "category/1024",
            SupplierId = "supplier/16",
            Code = "H11050" + i,
            CreatedAt = DateTime.Now,
            StandardCost = 250 + (i * 10),
            ListPrice = 189 + (i * 10),
        };
        _session.Store(product);
    }
            
    _session.SaveChanges();

    return Content("Products successfully created");
}

This will create 50 documents in the database with just one call to the database, as you can see in the RavenDB console output (I substitute some of the log output with … for space reasons):

Request #   5: POST    -    17 ms - <default>  - 200 - /bulk_docs
        PUT products/2
        PUT products/3
        PUT products/4
        PUT products/5
        ...
        PUT products/49
        PUT products/50
        PUT products/51

This how it’s looks like on the Management Studio:

Now that we have a few documents in the database it’s time to see how we can load one of them. In order to load the entire document you can use the Load method:

Product product = _session.Load<Product>("products/5");
Product product2 = _session.Load<Product>("5");

The above lines are equivalent, they return the same product. The second line is a handy shortcut that RavenDB Client API provides us, which can come in handy when you expose the int part of the ID as a web parameter like in the following code:

public ActionResult GetProduct(int id)
{
    Product product = _session.Load<Product>(id);
    return Content(product.Name);
}

In the above code we used a number in order to get the document instead of having you use the actual full ID (“products/” + id). Now it’s time to modify the product and save it to the database:

public ActionResult LoadAndUpdateProduct()
{
    Product product = _session.Load<Product>("products/5");
    product.ListPrice -= 10;
    _session.SaveChanges();
    return Content("Product 5 successfully updated");
}

As you can see, updating a document is as simple as loading the document, changing its properties and calling the _session.SaveChanges method. This can be happening because that the session keeps track of each of the loaded entities. This lets the session determine which of the documents has been updated and send just them to the database.

What is left is to delete a document. Consider the following code which will do exactly that:

public ActionResult DeleteProduct(int id)
{
    Product product = _session.Load<Product>(id);
    if (product == null)
        return HttpNotFound("Product {0} does not exist");
    _session.Delete(product);
    _session.SaveChanges();
    return Content(string.Format("Product {0} successfully deleted", id));
}

One interesting thing that we do here is to check if product is null. This is very important step after loading a document because that _session.Load method will return null if there is no document with the corresponding specified id in the database.

Until now we did plain CRUD operations. Now it’s time to create some more complex queries... Raven Client API comes with a great support for Linq so we can use this in order to create more complex queries. Here in an example of how we can get all the products that are available for sale (discontinued equal to false) ordered by the product’s list price:

public ActionResult GetDiscontinuedProducts()
{
    var products = from product in _session.Query<Product>()
                   where product.Discontinued == false
                   orderby product.ListPrice
                   select product;

    return View(products.ToList());
}

As you can see, RavenDB Client API gives you what you’ll expect from a modern database client API to support. It has great LINQ provider that you’ll let you do almost anything you can do with a regular LINQ queries.

In this post I demonstrated how easy is to use the RavenDB .NET Client API in order to store some documents in the database, load them, update and remove them. Than we saw that we can use LINQ powered queries in order to actually query the database with some criteria and order by statement.

In the future blog posts I’m going to talk about the following topics:

• Introduce the RaccoonBlog project and blog about the interesting parts of it.
• Talk about modeling entities in a way that suits documents database.

If you have any feedback / questions / suggestions regards this blog posts I’ll be more than happy to hear it.

This series is about how to start using RavenDB without any prior knowledge about Document Databases. There is assumption that you’re familiar with Relational Databases like Sql Server, though.

In the introduction post of this series I briefly examined what is a Document Database, what is a document and how RavenDB Management Studio looks like. Now it’s time to show you how to actually use RavenDB in your applications. So let’s talk about the client API.

The target of this post is to show you how to use the client API: we’ll start by creating a basic model entity, than we’re going to store an instance of this entity in RavenDB database, then load a entity and update it. Finally, I’m going to show you how to do some more complex queries.

You can use RavenDB from any language or platform (more on that in a future blog post). In this blog post we’re going to use the .NET client API which let you consume RavenDB from any .NET application very easily.

Let’s create an empty ASP.NET MVC application and add the following the RavenDB NuGet package to it:

After the RavenDB NuGet package has been installed you’re ready to start use RavenDB from the MVC application that we created. But we need first need to make sure that we have a RavenDB database to connect to. In order to that, run the RavenDB console application as we did in the previous post, and edit the connection string in the web.config to point to the correct server URL:

  <connectionStrings>
    <add name="RavenDB" connectionString="Url=http://localhost:8080" />
  </connectionStrings>

Now that we have RavenDB and the Client API set up, it’s time to do something interesting with it. In order to start interacting with RavenDB with the Client API you’ll need to create an instance of the IDocumentSession and the IDocumentStore. The session is define the boundaries of your Unit Of Work, which will be in a typical web application the entire web request, and the IDocumentStore lets you create sessions. It’s a good practice to create one instance of IDocumentStore per application and one session per unit of work.

Showing how to effectively managing the session in a web application is out of the scope of this blog post (which require us talking us to talk about IoC patterns), but you can take a look on the RaccoonBlog project in order to see one simple approach to achieve this. The RaccoonBlog project was created specifically for demonstration purposes in this blog posts series and it’s now the blog engine that we use to run this blog).

For this demonstration we’re going to create the session and the document store directly in the controller. As specified in the above paragraph, in real applications you’ll typically want to manage the session out of the controller.

public class ProductController : Controller
{
    private static readonly IDocumentStore documentStore;
    private IDocumentSession _session;

    static ProductController()
    {
        documentStore = new DocumentStore
                            {
                                ConnectionStringName = "RavenDB"
                            }.Initialize();

    }

    protected override void OnActionExecuting(ActionExecutingContext filterContext)
    {
        _session = documentStore.OpenSession();
    }

    protected override void OnActionExecuted(ActionExecutedContext filterContext)
    {
        _session.SaveChanges();
        _session.Dispose();
    }
}

Now that we have the session in place, we can start using it to do CRUD operations on the database. Consider the following Product entity which we’re going to use in this blog post:

public class Product
{
    public string Id { get; set; }
    public string CategoryId { get; set; }
    public string SupplierId { get; set; }

    public string Name { get; set; }
    public string Code { get; set; }
    public decimal StandardCost { get; set; }
    public decimal ListPrice { get; set; }
    public int UnitsOnStock { get; set; }
    public int UnitsOnOrder { get; set; }
    public bool Discontinued { get; set; }

    public string PhotoFile { get; set; }
    public DateTime CreatedAt { get; set; }
}

Let’s create an instance of this entity and store it into the database:

public ActionResult StoreSomeProductInDatabase()
{
    var product = new Product
                    {
                        Name = "Product Name",
                        CategoryId = "category/1024",
                        SupplierId = "supplier/16",
                        Code = "H11050",
                        CreatedAt = DateTime.Now,
                        StandardCost = 250,
                        ListPrice = 189,
                        FilePhoto = "path to picture.jpg",
                    };
    _session.Store(product);
    _session.SaveChanges();

    return Content(product.Id);
}

First we’re creating a product and storing it in the session. I said we’re storing it in the session because when you call the _session.Store(product) method it wouldn’t send the product to the database yet. In order to actually save the product in the database you’ll need to call the _session.SaveChanges(). Note that after you call the _session.SaveChanges() method we can use the product.Id, which will be “products/1”. We didn’t assign that Id manually but let the client API assigns it to us automatically. If you’ll look on the RavenDB console application you’ll see the following log output:

Raven is ready to process requests. Build 385, Version 1.0.0.0 / 64f1188
Server started in 2,519 ms
Data directory: C:\Users\Fitzchak\Downloads\RavenDB-Unstable-Build-385\Server\Data
HostName: <any> Port: 8080, Storage: Esent
Server Url: http://fitzchak-pc:8080/
Press <enter> to stop or 'cls' and <enter> to clear the log
Request #   1: GET     -    26 ms - <default>  - 404 - /docs/Raven/Replication/Destinations
Request #   2: GET     -     0 ms - <default>  - 404 - /docs/Raven/Hilo/products
Request #   3: PUT     -   241 ms - <default>  - 201 - /docs/Raven/Hilo/products
Request #   4: POST    -    44 ms - <default>  - 200 - /bulk_docs
        PUT products/1

At request #4 we can see the actual post request which will store the products/1 document. We got response status #200 which means that the document is successfully stored in the database. In addition you can see that we do not need to query the database and ask what was the generated id for our product (which is a typically case with auto increase field implementation in relational databases), because the Id is generated by the client API (which use the HiLo algorithm to generate it). This “magic” happens in request #2 and #3 which we’ll be covered in the upcoming posts.

You can look on the RavenDB Management Studio in order to see the documents that we just stored:

We could have also store a lot of products in the session and than call the SaveChanges which will insert all of them to the database with just one call:

public ActionResult InsertSomeMoreProducts()
{
    for (int i = 0; i < 50; i++)
    {
        var product = new Product
        {
            Name = "Product Name " + i,
            CategoryId = "category/1024",
            SupplierId = "supplier/16",
            Code = "H11050" + i,
            CreatedAt = DateTime.Now,
            StandardCost = 250 + (i * 10),
            ListPrice = 189 + (i * 10),
        };
        _session.Store(product);
    }
            
    _session.SaveChanges();

    return Content("Products successfully created");
}

This will create 50 documents in the database with just one call to the database, as you can see in the RavenDB console output (I substitute some of the log output with … for space reasons):

Request #   5: POST    -    17 ms - <default>  - 200 - /bulk_docs
        PUT products/2
        PUT products/3
        PUT products/4
        PUT products/5
        ...
        PUT products/49
        PUT products/50
        PUT products/51

This how it’s looks like on the Management Studio:

Now that we have a few documents in the database it’s time to see how we can load one of them. In order to load the entire document you can use the Load method:

Product product = _session.Load<Product>("products/5");
Product product2 = _session.Load<Product>("5");

The above lines are equivalent, they return the same product. The second line is a handy shortcut that RavenDB Client API provides us, which can come in handy when you expose the int part of the ID as a web parameter like in the following code:

public ActionResult GetProduct(int id)
{
    Product product = _session.Load<Product>(id);
    return Content(product.Name);
}

In the above code we used a number in order to get the document instead of having you use the actual full ID (“products/” + id). Now it’s time to modify the product and save it to the database:

public ActionResult LoadAndUpdateProduct()
{
    Product product = _session.Load<Product>("products/5");
    product.ListPrice -= 10;
    _session.SaveChanges();
    return Content("Product 5 successfully updated");
}

As you can see, updating a document is as simple as loading the document, changing its properties and calling the _session.SaveChanges method. This can be happening because that the session keeps track of each of the loaded entities. This lets the session determine which of the documents has been updated and send just them to the database.

What is left is to delete a document. Consider the following code which will do exactly that:

public ActionResult DeleteProduct(int id)
{
    Product product = _session.Load<Product>(id);
    if (product == null)
        return HttpNotFound("Product {0} does not exist");
    _session.Delete(product);
    _session.SaveChanges();
    return Content(string.Format("Product {0} successfully deleted", id));
}

One interesting thing that we do here is to check if product is null. This is very important step after loading a document because that _session.Load method will return null if there is no document with the corresponding specified id in the database.

Until now we did plain CRUD operations. Now it’s time to create some more complex queries... Raven Client API comes with a great support for Linq so we can use this in order to create more complex queries. Here in an example of how we can get all the products that are available for sale (discontinued equal to false) ordered by the product’s list price:

public ActionResult GetDiscontinuedProducts()
{
    var products = from product in _session.Query<Product>()
                   where product.Discontinued == false
                   orderby product.ListPrice
                   select product;

    return View(products.ToList());
}

As you can see, RavenDB Client API gives you what you’ll expect from a modern database client API to support. It has great LINQ provider that you’ll let you do almost anything you can do with a regular LINQ queries.

In this post I demonstrated how easy is to use the RavenDB .NET Client API in order to store some documents in the database, load them, update and remove them. Than we saw that we can use LINQ powered queries in order to actually query the database with some criteria and order by statement.

In the future blog posts I’m going to talk about the following topics:

• Introduce the RaccoonBlog project and blog about the interesting parts of it.
• Talk about modeling entities in a way that suits documents database.

If you have any feedback / questions / suggestions regards this blog posts I’ll be more than happy to hear it.

Recently I started to learn how to use RavenDB. I never used RavenDB or any other document database before, and when I was thinking on a database it was mainly on the relational form of it. What this means is that for me, a database must have tables, rows and columns in order to be considered as something that I want to use. Well, now that I see what RavenDB can give me, I think that this is all going to change.

As I’m currently learning how to use RavenDB, I’m going to write a series of blog posts that will demonstrate how to use RavenDB without any prior knowledge of it required. This will be an “in practice” demonstration, which means that I’m going to demonstrate how to use RavenDB in practice rather than talk on the ideas that behind it.

Why would I want to use a Document Database?

Using a document database like RavenDB will give you the following benefits:

• Better performance in your application
• Faster development time
• Better maintenance experience

If you want to see more information of those benefits, take a look in the RavenDB documentation.

What is a document database and what is RavenDB?

RavenDB is a document database, which stores each document in JSON format. In a document database any entity can be stored as a document. You don’t have to define in advance the schema of your data in order to store it, all you have to do is to give RavenDB an object and RavenDB will store it. Later in this post, I’ll show you what does a document looks like.

Start using RavenDB

Let’s start to see how to use RavenDB. Go to RavenDB website (http://ravendb.net/download) and download RavenDB. After extracting the .zip file to a folder, you’ll see the following folder structure:

This folder contains both the RavenDB database server and the client’s API binaries. We’ll start with the server first, then I’m going to show you how to manage this server from RavenDB management studio.

You can start RavenDB by simply double clicking on the Start.cmd file.

You have 4 options how to run the server:

1. A console application that runs on your computer and listen to incoming HTTP requests. In order to use this option, just run the Raven.Server.exe from the Server folder or double click the Start.cmd script from the root directory. This is mostly suitable for debugging and experimentation.
2. As a Windows Service, which you can install by executing “Raven.Server.exe /install” command.
3. An IIS website that have the files under the Web directory in the root folder of the website. This option seems to be more suitable for production.
4. You can run RavenDB in an embedded mode, which will run the database inside your client application process.

In this post we’re going to run the server using the first option. In the RavenDB folder, double click the Start.cmd script. After you have done this, you’ll see this output in the console application:

That is it. The server is running and ready to process any requests. As you can see, in this case the server is listening on port 8080, which is the default port.

You also see here the path of the Data Directory. This is the directory where RavenDB stores your data. If you lose this directory you’ll lose your data. (We’ll talk on backup plans in later blog posts). On the other end, if you close the server, delete this folder and then re-run the server again, you get an empty server. This is great for my case that I want to test things out and then revert back to the beginning.

After that the server is running, we can start to use RavenDB management studio which will let you to manage a various aspects of the database. The Start.cmd script has already done that for us, and you can see the RavenDB Management Studio open inside your browser. The Management Studio is a Silverlight application which you can start using it by browsing the URL that RavenDB is listed to. In our case, the server is listening on port 8080, so we can access it from the following URL:  http://localhost:8080. This is how the Management Studio looks like when you look on a freshly installed database:

As you can see, all we got right now is a default database that was automatically created for us without any data in it. The screen says: There are no documents and no collections yet. You may be wondering what is a document and what is a collection but the first thing that we’re going to touch is what a database is.

In the top-left of the screen there is a back button and a home button. Click on the home button and you’ll see the following screen:

In this screen you can create a new database by clicking on the Create New Database button, or navigate to an existing database by choosing the name of the database from the left list of databases.

For now we’re going to make a use of the default database, so click on “use this database” and the screen will navigate to the database main screen. You can also get to the database screen by clicking on the Back button as this was our previous screen.

Currently we have an empty database. In order to see how the data is look in the document database, you can click on the “Create sample data” button which will generate a sample data for you. When I clicked on the “Create sample data” button I got the following screen:

Be default RavenDB allow anonymous access only for read requests (HTTP GET), and since we creating data, we need to specify a username and password. You can control this by changing the AnonymousAccess setting in the server configuration file.

Enter your username and password of your Windows account and a sample data will be generated for you. This how the database screen looks like now:

As you can see, the sample data contains: 256 documents, 2 collections and 6 indexes. You may be wondering what those things are, so I’m going to start explain them one by one. (I’ll explain what is index in later blog post).

What is a document?

A document is any JSON object. Compared to a relational database, you can think on a document as a row in a table. But unlike a row in relational database, a document contains the entire graph of your object (entity).

Let’s click on the documents item in the left sidebar menu in order to see all the documents that we have right now:

Let’s double-click on one of the documents, and see what a document is:

As you can see a document contains a key, data and metadata. The data is your entire object represented in JOSN. In addition to that each document has a document key which is in this case “albums/410”. You can think of the document key as the primary key in a relational database. Each document contains also some metadata that is automatically generated for us by the client API. The “Raven-Clr-Type” metadata represents the .Net object type that this document is mapped to.

What is a collection?

A collection is list of documents with the same Raven-Entity-Name metadata value. You can think on a collection as a list of documents with the same type. In our example we have two types of documents which are represented by two collections: Albums and Genres.

Summery

In this blog post I showed you how to run RavenDB server as a console application. Then, we looked on the server with the RavenDB management studio. We created a sample application, and I explained what a document is and what a collection is.

My roadmap for the next blog posts:

• Take an existing data and import it to RavenDB.
• Show how to model the entities in a way that fits more a document database.
• Build a client application that will make a use of this data.

Any feedback / suggestion will be appreciated.

Posted By: Fitzchak Yitzchaki

Recently I started to learn how to use RavenDB. I never used RavenDB or any other document database before, and when I was thinking on a database it was mainly on the relational form of it. What this means is that for me, a database must have tables, rows and columns in order to be considered as something that I want to use. Well, now that I see what RavenDB can give me, I think that this is all going to change.

As I’m currently learning how to use RavenDB, I’m going to write a series of blog posts that will demonstrate how to use RavenDB without any prior knowledge of it required. This will be an “in practice” demonstration, which means that I’m going to demonstrate how to use RavenDB in practice rather than talk on the ideas that behind it.

Why would I want to use a Document Database?

Using a document database like RavenDB will give you the following benefits:

• Better performance in your application
• Faster development time
• Better maintenance experience

If you want to see more information of those benefits, take a look in the RavenDB documentation.

What is a document database and what is RavenDB?

RavenDB is a document database, which stores each document in JSON format. In a document database any entity can be stored as a document. You don’t have to define in advance the schema of your data in order to store it, all you have to do is to give RavenDB an object and RavenDB will store it. Later in this post, I’ll show you what does a document looks like.

Start using RavenDB

Let’s start to see how to use RavenDB. Go to RavenDB website (http://ravendb.net/download) and download RavenDB. After extracting the .zip file to a folder, you’ll see the following folder structure:

This folder contains both the RavenDB database server and the client’s API binaries. We’ll start with the server first, then I’m going to show you how to manage this server from RavenDB management studio.

You can start RavenDB by simply double clicking on the Start.cmd file.

You have 4 options how to run the server:

1. A console application that runs on your computer and listen to incoming HTTP requests. In order to use this option, just run the Raven.Server.exe from the Server folder or double click the Start.cmd script from the root directory. This is mostly suitable for debugging and experimentation.
2. As a Windows Service, which you can install by executing “Raven.Server.exe /install” command.
3. An IIS website that have the files under the Web directory in the root folder of the website. This option seems to be more suitable for production.
4. You can run RavenDB in an embedded mode, which will run the database inside your client application process.

In this post we’re going to run the server using the first option. In the RavenDB folder, double click the Start.cmd script. After you have done this, you’ll see this output in the console application:

That is it. The server is running and ready to process any requests. As you can see, in this case the server is listening on port 8080, which is the default port.

You also see here the path of the Data Directory. This is the directory where RavenDB stores your data. If you lose this directory you’ll lose your data. (We’ll talk on backup plans in later blog posts). On the other end, if you close the server, delete this folder and then re-run the server again, you get an empty server. This is great for my case that I want to test things out and then revert back to the beginning.

After that the server is running, we can start to use RavenDB management studio which will let you to manage a various aspects of the database. The Start.cmd script has already done that for us, and you can see the RavenDB Management Studio open inside your browser. The Management Studio is a Silverlight application which you can start using it by browsing the URL that RavenDB is listed to. In our case, the server is listening on port 8080, so we can access it from the following URL:  http://localhost:8080. This is how the Management Studio looks like when you look on a freshly installed database:

As you can see, all we got right now is a default database that was automatically created for us without any data in it. The screen says: There are no documents and no collections yet. You may be wondering what is a document and what is a collection but the first thing that we’re going to touch is what a database is.

In the top-left of the screen there is a back button and a home button. Click on the home button and you’ll see the following screen:

In this screen you can create a new database by clicking on the Create New Database button, or navigate to an existing database by choosing the name of the database from the left list of databases.

For now we’re going to make a use of the default database, so click on “use this database” and the screen will navigate to the database main screen. You can also get to the database screen by clicking on the Back button as this was our previous screen.

Currently we have an empty database. In order to see how the data is look in the document database, you can click on the “Create sample data” button which will generate a sample data for you. When I clicked on the “Create sample data” button I got the following screen:

Be default RavenDB allow anonymous access only for read requests (HTTP GET), and since we creating data, we need to specify a username and password. You can control this by changing the AnonymousAccess setting in the server configuration file.

Enter your username and password of your Windows account and a sample data will be generated for you. This how the database screen looks like now:

As you can see, the sample data contains: 256 documents, 2 collections and 6 indexes. You may be wondering what those things are, so I’m going to start explain them one by one. (I’ll explain what is index in later blog post).

What is a document?

A document is any JSON object. Compared to a relational database, you can think on a document as a row in a table. But unlike a row in relational database, a document contains the entire graph of your object (entity).

Let’s click on the documents item in the left sidebar menu in order to see all the documents that we have right now:

Let’s double-click on one of the documents, and see what a document is:

As you can see a document contains a key, data and metadata. The data is your entire object represented in JOSN. In addition to that each document has a document key which is in this case “albums/410”. You can think of the document key as the primary key in a relational database. Each document contains also some metadata that is automatically generated for us by the client API. The “Raven-Clr-Type” metadata represents the .Net object type that this document is mapped to.

What is a collection?

A collection is list of documents with the same Raven-Entity-Name metadata value. You can think on a collection as a list of documents with the same type. In our example we have two types of documents which are represented by two collections: Albums and Genres.

Summery

In this blog post I showed you how to run RavenDB server as a console application. Then, we looked on the server with the RavenDB management studio. We created a sample application, and I explained what a document is and what a collection is.

My roadmap for the next blog posts:

• Take an existing data and import it to RavenDB.
• Show how to model the entities in a way that fits more a document database.
• Build a client application that will make a use of this data.

Any feedback / suggestion will be appreciated.

Posted By: Fitzchak Yitzchaki