Creating and deploying transformers

Special abstract class has been created for strongly-typed transformer creation called AbstractTransformerCreationTask.

There are certain benefits of using it:

• strongly-typed syntax
• ability to deploy it easily
• ability to deploy it using assembly scanner (more about that later)
• ability to pass transformer as a generic type in various methods without having to hardcode string-based names

By default the transformer's names are auto-generated from the type name. You can change that if you really want to (override the TransformerName property), but this option is used rarely. More details later in this article.

This approach limits you to following the strongly typed rules, while server transformers aren't limited by them. However, it is rarely an issue, unless you write a transformer to cover multiple types without a common ancestor.

Naming conventions

Actually there is only one naming convention: each _ in class name will be translated to / in transformer name. If you want to customize the transformer's name, you can do it by overriding the TransformerName property.

e.g.

In the Northwind samples, there is a transformer called Orders/Company. To get such a name for a transformer, we need to create a class called Orders_Company.

public class Orders_Company : AbstractTransformerCreationTask<Order>
{
	// ...
}

Sending to server

Since transformers are server-side projections, they must be stored on a server. To do so, we need to create instance of our class that inherits from AbstractTransformerCreationTask, and use one of the deployment methods: Execute or ExecuteAsync for asynchronous call.

// deploy transformer to `DefaultDatabase` for given `DocumentStore`
// using store `Conventions`
new Orders_Company().Execute(store);

// deploy asynchronously transformer to `DefaultDatabase` for given `DocumentStore`
// using store `Conventions`
await new Orders_Company().ExecuteAsync(store);

// deploy transformer to `Northwind` database
// using store `Conventions`
new Orders_Company().Execute(store.DatabaseCommands.ForDatabase("Northwind"), store.Conventions);

Using assembly scanner

All classes that inherit from AbstractTransformerCreationTask can be deployed at once with one of IndexCreation.CreateIndexes method overloads.

// deploy all transformers (and indexes) 
// from assembly where `Orders_Company` is found
// to `DefaultDatabase` for given `DocumentStore`
IndexCreation.CreateIndexes(typeof(Orders_Company).Assembly, store);

Underneath, the IndexCreation will call Execute methods for each of the transformers (and indexes) found.

Example

public class Orders_Company : AbstractTransformerCreationTask<Order>
{
	public Orders_Company()
	{
		TransformResults = results => from result in results select result.Company;
	}
}

public static void Main(string[] args)
{
	using (var store = new DocumentStore
	{
		Url = "http://localhost:8080",
		DefaultDatabase = "Northwind"
	})
	{
		store.Initialize();

		new Orders_Company().Execute(store);

		using (var session = store.OpenSession())
		{
			IList<string> companies = session.Query<Order>()
				.Where(x => x.Freight > 100) // remember to add `Raven.Client.Linq` namespace
				.TransformWith<Orders_Company, string>()
				.ToList();
		}
	}
}

Another way to create a transformer is to use low-level PutTransformer command from DatabaseCommands. API reference for this command can be found here.

The advantage of this approach is defining transformer's name as you feel fit, yet at the same time you loose all other possibilities when the AbstractTransformerCreationTask is used.

store
	.DatabaseCommands
	.PutTransformer("ComboBox/Results", new TransformerDefinition
	{
		TransformResults = "from doc in results select new { doc.Id, doc.Name }"
	});

This approach lacks any strongly-typed definition guarantees, but the advantage is that we aren't limited by the system type. In this case, we can execute this transformer on any type with a Name property. Note that in practice, you can use any transformer on any type. They execute on the server and have no concept of your user defined types. However, it is usually easier to look at untyped transformers and see that they can operate on all types, than to look at a typed transformer and understand that it can operate on types other than what it is defined for.

TransformerDefinition can also be partially addressed by creating TransformerDefinition from class that implements AbstractTransformerCreationTask by invoking CreateTransformerDefinition method.

TransformerDefinition definition = new Orders_Company().CreateTransformerDefinition();
store
	.DatabaseCommands
	.PutTransformer("Orders/Company", definition);