{"id":2000,"date":"2015-10-27T20:51:14","date_gmt":"2015-10-27T20:51:14","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=2000"},"modified":"2025-06-13T23:54:01","modified_gmt":"2025-06-14T06:54:01","slug":"linq-n1ql-and-couchbase-oh-mai-linq2couchbase-ga","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/es\/linq-n1ql-and-couchbase-oh-mai-linq2couchbase-ga\/","title":{"rendered":"Couchbase LINQ Provider GA: LINQ, N1QL y Couchbase, \u00a1oh mai!"},"content":{"rendered":"

Hoy Couchbase se complace en anunciar el lanzamiento GA del proveedor oficial LINQ para Couchbase Server y el lenguaje de consulta de moda para documentos JSON, \u00a1N1QL! El objetivo del proveedor es proporcionar un ORM\/ODM simple y f\u00e1cil de usar que se acerque m\u00e1s a Linq2SQL que EntityFramework o NHibernate, que son verbosos y pueden ser complejos.<\/p>\n

Aunque la simplicidad es el objetivo, no subestimes el poder de Linq2Couchbase; \u00a1es una implementaci\u00f3n de Linq completamente funcional con soporte extendido para todas las incre\u00edbles caracter\u00edsticas de N1QL!<\/p>\n

En este post repasaremos lo b\u00e1sico para empezar con Linq2Couchbase, los principales actores de la API, y la integraci\u00f3n con ASP.NET y Owin\/Katana. \u00a1En posts posteriores entraremos en m\u00e1s detalle sobre los pormenores y detalles de Linq2Couchbase!<\/p>\n

Arquitectura<\/h2>\n

El proveedor es en realidad una capa m\u00e1s sobre el SDK; el proveedor se encarga del an\u00e1lisis sint\u00e1ctico y la generaci\u00f3n de consultas y el SDK se encarga de la solicitud y la asignaci\u00f3n de los resultados. El proveedor utiliza Re-linq<\/a> internamente para crear un \u00e1rbol de sintaxis abstracta (AST) a partir de la consulta Linq, que luego se utiliza para emitir la sentencia N1QL. Ten en cuenta que Re-linq es utilizado tanto por NHibernate como por EntityFramework, \u00a1as\u00ed que est\u00e1s en buenas manos!<\/p>\n

Primeros pasos<\/h2>\n

La fuente est\u00e1 disponible en Github<\/a> y el paquete est\u00e1 disponible en NuGet<\/a>Si utilizas el gestor de paquetes NuGet para instalar Linq2Couchbase, todas las dependencias, incluido el SDK de Couchbase.NET, ser\u00e1n gestionadas por ti.<\/p>\n

Para instalar Linq2Couchbase utilizando el gestor de paquetes NuGet (suponiendo que ya has creado un proyecto de Visual Studio) abre el gestor de paquetes haciendo clic con el bot\u00f3n derecho del rat\u00f3n en \"Manage Nuget Packages\" y buscando Linq2Couchbase o utilizando la l\u00ednea de comandos del gestor de paquetes:<\/p>\n

PM> Install-Package Linq2Couchbase \r\n<\/code><\/pre>\n
Una vez hecho esto el proyecto tendr\u00e1 todas las dependencias necesarias. A continuaci\u00f3n tendr\u00e1s que instalar Couchbase Server, ya sea localmente o a trav\u00e9s de m\u00e1quinas virtuales. El enlace de descarga de Couchbase Server es aqu\u00ed<\/a>. Para las m\u00e1quinas virtuales, utilice vagabundos<\/a> que utiliza Puppet y Vagrant para instalar un cluster de servidores Couchbase. \u00a1Aseg\u00farate de instalar Couchbase 4.0! Si est\u00e1s usando Vagrants, entonces aprovisiona el cluster:<\/p>\n
peep@ELJEFE-PC ~\/repos\/vagrants\/4.0.0\/debian7 (master)\r\n$ vagrant up\r\n<\/code><\/pre>\n
Una vez que tenga un Servidor o cluster Couchbase, configure el Servidor o Cluster y aseg\u00farese de que al menos un nodo es un nodo \u00cdndice y un nodo es un nodo Consulta<\/em><\/strong>. Esto lo har\u00e1 en el primer paso de la \"Configuraci\u00f3n del Servidor\" o cuando a\u00f1ada un servidor adicional a su cluster. Adem\u00e1s, a\u00f1ada el conjunto de datos \"muestra-cerveza\" al cl\u00faster durante la configuraci\u00f3n o desde la pesta\u00f1a Configuraci\u00f3n>Muestras despu\u00e9s de haber configurado el cl\u00faster o la instancia.<\/p>\n
Ahora que tu instancia o cluster de Couchbase est\u00e1 configurado, necesitar\u00e1s crear un \u00edndice primario en el bucket \"beer-sample\". Para ello, navega a C:Archivos de programaCouchbaseServerbin o si utiliza vagrants<\/code> (o linux) \/opts\/couchbase\/bin<\/code>utilizando un s\u00edmbolo del sistema. A continuaci\u00f3n, escriba cbq o .\/cbq (en linux) para iniciar la consulta CIL y luego:<\/p>\n
CREATE PRIMARY INDEX ON `beer-sample` USING GSI;\r\n<\/code><\/pre>\n
Esto crear\u00e1 un \u00edndice primario en el cubo beer-sample. F\u00edjese en las comillas \"`\", son necesarias para escapar el \"-\" de beer-sample. Ahora est\u00e1 listo para escribir algo de c\u00f3digo.<\/p>\n
Creaci\u00f3n del BucketContext<\/h2>\n
El objeto principal para trabajar con el bucket es el BucketContext. El BucketContext es an\u00e1logo al DataContext en Linq2Sql y al DbContext en EntityFramework. Su prop\u00f3sito principal es proporcionar una interfaz para construir consultas y enviarlas al servidor Couchbase.<\/p>\n
Puede utilizar BucketContext como un objeto independiente o puede derivar de \u00e9l y crear un objeto fuertemente tipado que asigne propiedades a los tipos de su modelo de dominio y cubo. En este ejemplo har\u00e9 esto \u00faltimo:<\/p>\n
\/\/\/\r\n\r\n\/\/\/ Un DbContext concreto para el cubo de ejemplo muestra-cerveza.\r\n\/\/\/ <\/code><\/pre>\n
public class CervezaMuestra : BucketContext { public CervezaMuestra() : this(ClusterHelper.GetBucket(\"cerveza-muestra\")) { } public CervezaMuestra(IBucket bucket) : base(bucket) { DocumentFilterManager.SetFilter(new BreweryFilter()); } public IQueryable Cervezas { get { return Query(); } } public IQueryable Cervecer\u00edas { get { return Consulta(); } } }<\/p>\n
El bucket de muestras de cerveza (un bucket es similar a una base de datos en un sistema RDBMS) contiene documentos que est\u00e1n \"tipados\" como \"cervecer\u00eda\" y \"cerveza\", este sistema de tipado informal permitir\u00e1 consultar el bucket y devolver documentos de cervecer\u00eda o documentos de cerveza mediante un predicado(WHERE type=\"beer\" por ejemplo). En el c\u00f3digo anterior hemos definido propiedades expl\u00edcitas que devuelven IQueryable<\/p>\n
Ejemplo de consulta<\/h2>\n
Ver\u00e1s que utilizar Linq2Couchbase es pr\u00e1cticamente id\u00e9ntico a Linq2SQL o al EF:<\/p>\n
var db = nueva BeerSample();\r\n\r\nvar query = from cerveza in db.Cervezas\r\n            join cervecer\u00eda in db.Cervecer\u00edas\r\n            on beer.BreweryId equals N1QlFunctions.Key(brewery)\r\n            select new { beer.Name, beer.Abv, BreweryName = brewery.Name };\r\n\r\nforeach (var beer in query)\r\n{\r\n    Console.WriteLine(cerveza.Nombre);\r\n}    \r\n<\/code><\/pre>\n
Una vez que tengas una referencia BucketContext todo lo que tienes que hacer es consultarlo como lo har\u00edas con cualquier otro proveedor Linq. Todas las palabras clave de Linq est\u00e1n soportadas, as\u00ed como las construcciones de N1QL como ON KEYS, NEST y UNNEST. En un post posterior, veremos todo esto con mucho m\u00e1s detalle.<\/p>\n
El modelo de documento<\/h2>\n
En el contexto BeerSample anterior, los objetos Beer y Brewery ser\u00e1n los objetivos de nuestras proyecciones Linq y corresponden o se asignan a documentos JSON equivalentes en nuestro bucket (beer-sample). He aqu\u00ed una lista de cada uno (tenga en cuenta que se trata de una lista parcial, las clases en su totalidad se puede encontrar aqu\u00ed<\/a>):<\/p>\n
[Filters.DocumentTypeFilter(\"beer\")]\r\npublic class BeerFiltered\r\n{\r\n    [JsonProperty(\"name\")]\r\n    public string Name { get; set; }\r\n\r\n    [JsonProperty(\"abv\")]\r\n    public decimal Abv { get; set; }\r\n\r\n    ...\r\n\r\n    [JsonProperty(\"category\")]\r\n    public string Category { get; set; }\r\n\r\n    [JsonProperty(\"updated\")]\r\n    public DateTime Updated { get; set; }\r\n}\r\n<\/code><\/pre>\n
Por supuesto, esto corresponde a los documentos \"cerveza\"; observe el atributo DocumentTypeFilter. Esto a\u00f1adir\u00e1 \"auto-m\u00e1gicamente\" un predicado o cl\u00e1usula WHERE que filtra por el tipo \"cerveza\" a cada consulta que tenga como objetivo ese documento. El atributo DocumentTypeFilter es una de las dos formas de aplicar un filtro, a menos que a\u00f1ada manualmente el predicado a cada consulta.<\/p>\n
public class Brewery\r\n{\r\n    [JsonProperty(\"name\")]\r\n    public string Name { get; set; }\r\n\r\n    [JsonProperty(\"city\")]\r\n    public string City { get; set; }\r\n\r\n    ...\r\n\r\n    [JsonProperty(\"geo\")]\r\n    public Geo Geo { get; set; }\r\n\r\n    [JsonProperty(\"beers\")]\r\n    public List Beers { get; set; }\r\n}\r\n<\/code><\/pre>\n
Este es el objeto al que se asignar\u00e1n los documentos \"cervecer\u00eda\". Observe que no hay ning\u00fan atributo DocumentTypeFilter definido expl\u00edcitamente; esto se debe a que el constructor para el contexto BeerSample a\u00f1adir\u00e1 el filtro al DocumentFilterManager. Esto es puramente una aproximaci\u00f3n diferente al mismo problema; a\u00f1adir un predicado a una consulta para filtrar por tipo.<\/p>\n
Integraci\u00f3n con ASP.NET u Owin\/Katana<\/h2>\n
Existe un patr\u00f3n muy definido para usar el SDK de Couchbase .NET en proyectos ASP.NET o Katana\/OWin. Dado que BucketContext utiliza el SDK de Couchbase .NET, tendr\u00e1s que seguir este patr\u00f3n para poder aprovechar la cach\u00e9 de objetos dentro del SDK y las conexiones TCP compartidas. Afortunadamente, es un patr\u00f3n muy simple:<\/p>\n
Uso de Global.asax en ASP.NET<\/h3>\n
En una aplicaci\u00f3n ASP.NET que utilice Global.asax, aprovechar\u00e1 los manejadores de eventos Application_Start y Application_End para crear y destruir los objetos Cluster y Bucket de los que depende BucketContext.<\/p>\n
public class MvcApplication : System.Web.HttpApplication\r\n{\r\n    protected async void Application_Start()\r\n    {\r\n        AreaRegistration.RegisterAllAreas();\r\n        FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);\r\n        RouteConfig.RegisterRoutes(RouteTable.Routes);\r\n        BundleConfig.RegisterBundles(BundleTable.Bundles);\r\n\r\n        var config = new ClientConfiguration\r\n        {\r\n            Servers = new List\r\n            {\r\n                new Uri(\"https:\/\/192.168.77.101:8091\/\")\r\n            }\r\n        };\r\n\r\n        ClusterHelper.Initialize(config);\r\n        var bucket = ClusterHelper.GetBucket(\"default\");\r\n    }\r\n\r\n    protected void Application_End()\r\n    {\r\n        ClusterHelper.Close();\r\n    }\r\n}\r\n<\/code><\/pre>\n
Aqu\u00ed estamos creando la configuraci\u00f3n (aunque tambi\u00e9n puede venir de App.Config) y luego inicializando el objeto ClusterHelper. Finalmente, cuando la aplicaci\u00f3n se cierra, destruimos los objetos Cluster y Bucket en el manejador Application_End. Este ser\u00e1 un cierre elegante y las construcciones a nivel de SO ser\u00e1n devueltas al SO de manera oportuna.<\/p>\n
Uso de Setup.cs en Owin\/Katana<\/h3>\n
En las aplicaciones alojadas en Owin\/Katana, seguimos un patr\u00f3n similar, s\u00f3lo que utilizamos un m\u00e9todo diferente, la clase Setup.cs.<\/p>\n
public partial class Startup\r\n{\r\n    public void Configuration(IAppBuilder app)\r\n    {\r\n        ConfigureAuth(app);\r\n\r\n        \/\/initialize the ClusterHelper\r\n        ClusterHelper.Initialize(new ClientConfiguration\r\n        {\r\n            Servers = new List\r\n            {\r\n                new Uri(\"https:\/\/localhost:8091\/\")\r\n            }\r\n        });\r\n\r\n        \/\/Register a callback that will dispose of the ClusterHelper on app shutdown\r\n        var properties = new AppProperties(app.Properties);\r\n        var token = properties.OnAppDisposing;\r\n        if (token != CancellationToken.None)\r\n        {\r\n            token.Register(() =>\r\n            {\r\n                ClusterHelper.Close();\r\n            });\r\n        }\r\n    }\r\n}\r\n<\/code><\/pre>\n
Aqu\u00ed creamos e inicializamos el ClusterHelper cuando el m\u00e9todo Configuration se ejecuta al inicio y luego registramos un delegado que se disparar\u00e1 cuando la aplicaci\u00f3n se cierre, cerrando nuestro ClusterHelper y liberando recursos.<\/p>\n
Inyecci\u00f3n en los controladores<\/h3>\n
El propio BucketContext adopta las caracter\u00edsticas del patr\u00f3n Unit of Work; puedes crear uno para cada petici\u00f3n y como el ClusterHelper gestiona las referencias (asumiendo que sigues los consejos anteriores) la instancia simplemente ser\u00e1 GC'd al final de la petici\u00f3n.<\/p>\n
La forma m\u00e1s sencilla de hacerlo es simplemente utilizando Inyecci\u00f3n de dependencia<\/a> (el patr\u00f3n) dentro de sus controladores para crear la instancia cuando se crea el controlador, por ejemplo:<\/p>\n
public class HomeController : Controller\r\n{\r\n    private BeerSample _context;\r\n\r\n    public HomeController()\r\n        : this(new BeerSample(ClusterHelper.GetBucket(\"beer-sample\")))\r\n    {\r\n    }\r\n\r\n    public HomeController(BeerSample context)\r\n    {\r\n        _context = context;\r\n    }\r\n\r\n    ...\r\n}\r\n<\/code><\/pre>\n
Ahora, s\u00f3lo tiene que utilizar el BucketContext dentro de sus m\u00e9todos de acci\u00f3n:<\/p>\n
public ActionResult \u00cdndice()\r\n{\r\n    var query = (from cerveza in db.Cervezas\r\n        join cervecer\u00eda in db.Cervecer\u00edas\r\n        on beer.BreweryId equals N1QlFunctions.Key(brewery)\r\n        select new {\r\n            cerveza.Nombre,\r\n            beer.Abv,\r\n            BreweryName = brewery.Name\r\n        }).Take(10);\r\n\r\n    return View(query.ToList());\r\n}\r\n<\/code><\/pre>\n
Una vez m\u00e1s, dado que el contexto es un objeto ligero de corta duraci\u00f3n, puedes extenderlo a la solicitud e inyectarlo all\u00ed reutiliz\u00e1ndolo para todos los controladores invocados dentro de esa solicitud.<\/p>\n
\u00bfQu\u00e9 se avecina?<\/h2>\n
Muy pronto, la siguiente caracter\u00edstica importante ser\u00e1 el seguimiento de cambios mediante proxies. Adem\u00e1s, \u00a1espera correcciones de errores, mejoras de rendimiento y otras caracter\u00edsticas destinadas a hacer de Linq2Couchbase un ODM\/ORM ligero y con todas las funciones!<\/p>\n
Si hay alguna funci\u00f3n que desee, una correcci\u00f3n de errores o tal vez quiera contribuir, agradecemos todo tipo de comentarios, tanto buenos como malos.<\/p>\n