Connecting to a RavenDB data store
As we have seen, RavenDB can run in one of two modes: a client/server mode, where communication is made via HTTP; and an embedded mode, in which the client API makes direct calls against the Database API.
The recommended mode for RavenDB to run in is the server mode. We discuss the various deployment options for the server mode later in the documentation.
Since a document store instance is not cheap to create but is thread-safe, the general suggestion is to have one instance of it per-database per-application.
In either mode, when the application shuts down, the document store instance(s) used should be disposed to ensure proper cleanup.
Running in server mode
To run in a server mode, add a reference to Raven.Client.Lightweight.dll to your application, and after launching the server instance separately connect to it using the following code:
1
2
| documentStore.Initialize();
Where http://myravendb.mydomain.com/ is your the RavenDB server's address.This will instantiate a communication channel between your application and the RavenDB server instance in the network address you provided.
|
1
2
| var documentStore = new EmbeddableDocumentStore { DataDirectory = "path/to/database/directory" };documentStore.Initialize(); |
Silverlight support
If you are accessing a RavenDB instance from Silverlight, you are going to need the Silverlight folder from the build package, and add a reference to all the DLLs in it to your application.
Using Silverlight, you can only access an external RavenDB server; there's still no embedded RavenDB implementation for Silverlight available to public use. You initialize a document store in Silverlight using:
1
2
| documentStore.Initialize(); |
Where http://myravendb.mydomain.com/ is your the RavenDB server's address.
Using a connection string
To make things even simpler, the RavenDB Client API supports .NET's named connection strings. You can use that by setting the ConnectionStringName, and the RavenDB client will initialize automatically based on the connection string's parameters:
1
2
3
4
| new DocumentStore { ConnectionStringName = "MyRavenConStr"} |
You can then define the connection string in the app.config:
1
2
3
4
5
| <connectionStrings> <add name="Local" connectionString="DataDir = ~\Data"/> <add name="Server" connectionString="Url = http://localhost:8080"/> <add name="Secure" connectionString="Url = http://localhost:8080;user=beam;password=up;ResourceManagerId=d5723e19-92ad-4531-adad-8611e6e05c8a"/></connectionStrings> |
RavenDB connection string format is:
- DataDir - run in embedded mode, specify which directory to run from. This requires that you'll initialize anEmbeddableDocumentStore, not just DocumentStore.
- Url - for server mode only, specify where to locate the server.
- User / Password - for server mode only, the credentials to use when accessing the server.
- Enlist - whatever RavenDB should enlist in distributed transactions. Not applicable for Silverlight.
- ResourceManagerId - Optional, for server mode only, the Resource Manager Id that will be used by the Distributed Transaction Coordinator (DTC) service to identify Raven. A custom resource manager id will need to be configured for each Raven server instance when Raven is hosted more than once per machine. Not applicable for Silverlight.
- Database - for server mode only, use a specific database, not the default one. Using this will also ensure that the database exists.
The following are samples of a few RavenDB connection strings:
- Url=http://ravendb.mydomain.com - connect to a remote RavenDB instance at ravendb.mydomain.com, to the default database
- Url=http://ravendb.mydomain.com;Database=Northwind - connect to a remote RavenDB instance at ravendb.mydomain.com, to the Northwind database there
- Url=http://ravendb.mydomain.com;User=user;Password=secret- connect to a remote RavenDB instance at ravendb.mydomain.com, with the specified credentials
- DataDir=~\App_Data\RavenDB;Enslist=False - use embedded mode with the datbase located in the App_Data\RavenDB folder, without DTC support.
Configuration
Conventions
The RavenDB Client API uses several conventions to control how it works, these can be modified at the DocumentStore level.
- FindIdentityProperty - Tell the RavenDB Client API how to find the property serving as the id property (the one holding the document key). Defaults to property named Id.
- FindTypeTagName - Find the tag name for the entity, a tag name is the collection name in which an entity will be enrolled, as well as the default entity key namespace. Defaults to the plural of the entity type. (An entity of type Post would be Posts, an entity of type Person would be People, etc).
- GenerateDocumentKey - Allows you to control the generation of keys for new entities. The rules for returned values follow the Raven document key generation strategies. By default, RavenDB concatenate the type tag name with an increasing numeric id (posts/1, posts/2, post/3, etc).
- IdentityPartsSeparator - A string that allows you to customize part of the document key generation. By default, Raven uses "plural_entity_name/id", which some users don't like because it makes putting the document key in the URL harder in some cases. You can set this to another value (such as "-"), which would generate: "plural_entity_name-id". This is an alternative to replacing the whole document key generation process.
