{"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\/pt\/linq-n1ql-and-couchbase-oh-mai-linq2couchbase-ga\/","title":{"rendered":"GA do provedor LINQ do Couchbase: LINQ, N1QL e Couchbase, oh mai!"},"content":{"rendered":"

Hoje, a Couchbase tem o prazer de anunciar o lan\u00e7amento da vers\u00e3o GA do provedor oficial de LINQ para o Couchbase Server e a linguagem de consulta quente para documentos JSON, N1QL! O objetivo do provedor \u00e9 fornecer um ORM\/ODM simples e f\u00e1cil de usar que seja mais pr\u00f3ximo do Linq2SQL do que o EntityFramework ou o NHibernate, que s\u00e3o detalhados e podem ser complexos.<\/p>\n

Embora o objetivo seja a simplicidade, n\u00e3o subestime o poder do Linq2Couchbase; ele \u00e9 uma implementa\u00e7\u00e3o totalmente funcional do Linq com suporte estendido para todos os recursos incr\u00edveis do N1QL!<\/p>\n

Nesta postagem, abordaremos os conceitos b\u00e1sicos para come\u00e7ar a usar o Linq2Couchbase, os principais atores da API e a integra\u00e7\u00e3o com o ASP.NET e o Owin\/Katana. Em postagens posteriores, entraremos em mais detalhes sobre as especificidades e os detalhes do Linq2Couchbase!<\/p>\n

A arquitetura<\/h2>\n

O provedor \u00e9, na verdade, apenas outra camada sobre o SDK; o provedor lida com a an\u00e1lise e a gera\u00e7\u00e3o de consultas e o SDK lida com a solicita\u00e7\u00e3o e o mapeamento dos resultados. O provedor usa Re-linq<\/a> internamente para criar uma \u00e1rvore de sintaxe abstrata (AST) a partir da consulta Linq, que \u00e9 ent\u00e3o usada para emitir a instru\u00e7\u00e3o N1QL. Observe que o Re-linq \u00e9 usado tanto pelo NHibernate quanto pelo EntityFramework, portanto, voc\u00ea est\u00e1 em boas m\u00e3os!<\/p>\n

Primeiros passos<\/h2>\n

A fonte est\u00e1 dispon\u00edvel em Github<\/a> e o pacote est\u00e1 dispon\u00edvel em NuGet<\/a>Se voc\u00ea usar o gerenciador de pacotes NuGet para instalar o Linq2Couchbase, todas as depend\u00eancias, inclusive o Couchbase.NET SDK, ser\u00e3o tratadas para voc\u00ea.<\/p>\n

Para instalar o Linq2Couchbase usando o gerenciador de pacotes NuGet (supondo que voc\u00ea j\u00e1 tenha criado um projeto do Visual Studio), abra o gerenciador de pacotes clicando com o bot\u00e3o direito do mouse em \"Manage Nuget Packages\" e procurando por Linq2Couchbase ou usando a linha de comando do gerenciador de pacotes:<\/p>\n

PM> Install-Package Linq2Couchbase \r\n<\/code><\/pre>\n
Depois de fazer isso, o projeto ter\u00e1 todas as depend\u00eancias necess\u00e1rias. Em seguida, voc\u00ea precisar\u00e1 instalar o Couchbase Server localmente ou por meio de uma VM. O link para download do Couchbase Server \u00e9 aqui<\/a>. Para as VMs, use vagabundos<\/a> que usa o Puppet e o Vagrant para instalar um cluster de servidores Couchbase. Certifique-se de instalar o Couchbase 4.0! Se estiver usando Vagrants, provisione o cluster:<\/p>\n
peep@ELJEFE-PC ~\/repos\/vagrants\/4.0.0\/debian7 (master)\r\n$ vagrant up\r\n<\/code><\/pre>\n
Quando voc\u00ea tiver um servidor ou cluster do Couchbase, configure o servidor ou cluster e certifique-se de que pelo menos um n\u00f3 seja um n\u00f3 de \u00edndice e um n\u00f3 seja um n\u00f3 de consulta<\/em><\/strong>. Isso ser\u00e1 feito na primeira etapa da \"Configura\u00e7\u00e3o do servidor\" ou quando voc\u00ea adicionar um servidor adicional ao cluster. Al\u00e9m disso, adicione o conjunto de dados \"beer-sample\" ao cluster durante a configura\u00e7\u00e3o ou na guia Settings>Samples (Configura\u00e7\u00f5es>Amostras) depois de configurar o cluster ou a inst\u00e2ncia.<\/p>\n
Agora que sua inst\u00e2ncia ou cluster do Couchbase est\u00e1 configurado, voc\u00ea precisar\u00e1 criar um \u00edndice prim\u00e1rio no bucket \"beer-sample\". Para fazer isso, navegue at\u00e9 C:Arquivos de programasCouchbaseServerbin ou, se estiver usando vagrants<\/code> (ou linux) \/opts\/couchbase\/bin<\/code>usando um prompt de comando. Em seguida, digite cbq ou .\/cbq (no Linux) para iniciar a consulta CIL e depois:<\/p>\n
CREATE PRIMARY INDEX ON `beer-sample` USING GSI;\r\n<\/code><\/pre>\n
Isso criar\u00e1 um \u00edndice prim\u00e1rio no bucket beer-sample. Observe os sinais de retrocesso \"`\", pois eles s\u00e3o necess\u00e1rios para escapar do \"-\" em beer-sample. Agora voc\u00ea est\u00e1 pronto para escrever algum c\u00f3digo!<\/p>\n
Criando o BucketContext<\/h2>\n
O principal objeto para trabalhar com o bucket \u00e9 o BucketContext. O BucketContext \u00e9 an\u00e1logo ao DataContext no Linq2Sql e ao DbContext no EntityFramework. Sua finalidade principal \u00e9 fornecer uma interface para criar consultas e envi\u00e1-las ao servidor Couchbase.<\/p>\n
Voc\u00ea pode usar o BucketContext como um objeto aut\u00f4nomo ou pode derivar dele e criar um objeto de tipagem forte que mapeie as propriedades para os tipos em seu modelo de dom\u00ednio e de balde. Neste exemplo, farei a segunda op\u00e7\u00e3o:<\/p>\n
\/\/\/ \r\n\r\n\/\/\/ A concrete DbContext for the beer-sample example bucket.\r\n\/\/\/ <\/code><\/pre>\n
public class BeerSample : BucketContext { public BeerSample() : this(ClusterHelper.GetBucket(\"beer-sample\")) { } public BeerSample(IBucket bucket) : base(bucket) { DocumentFilterManager.SetFilter(new BreweryFilter()); } public IQueryable Beers { get { return Query(); } } public IQueryable Breweries { get { return Query(); } } }<\/p>\n
O bucket de amostras de cerveja (um bucket \u00e9 semelhante a um banco de dados em um sistema RDBMS) cont\u00e9m documentos que s\u00e3o \"tipificados\" como \"cervejaria\" e \"cerveja\". Esse sistema informal de tipos permitir\u00e1 consultar o bucket e retornar documentos de cervejaria ou documentos de cerveja por meio de um predicado (WHERE type=\"beer\", por exemplo). No c\u00f3digo acima, definimos propriedades expl\u00edcitas que retornam IQueryable<\/p>\n
Um exemplo de consulta<\/h2>\n
Voc\u00ea ver\u00e1 que o uso do Linq2Couchbase \u00e9 praticamente id\u00eantico ao do Linq2SQL ou do EF:<\/p>\n
var db = new BeerSample();\r\n\r\nvar query = from beer in db.Beers\r\n            join brewery in db.Breweries\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(beer.Name);\r\n}    \r\n<\/code><\/pre>\n
Uma vez que voc\u00ea tenha uma refer\u00eancia ao BucketContext, basta consult\u00e1-lo como faria com qualquer outro provedor Linq. Todas as palavras-chave Linq s\u00e3o suportadas, bem como constru\u00e7\u00f5es N1QL como ON KEYS, NEST e UNNEST! Em uma postagem posterior, abordaremos tudo isso com muito mais detalhes!<\/p>\n
O modelo de documento<\/h2>\n
No contexto BeerSample acima, os objetos Beer e Brewery ser\u00e3o os alvos de nossas proje\u00e7\u00f5es Linq e correspondem ou mapeiam documentos JSON equivalentes em nosso bucket (beer-sample). Aqui est\u00e1 uma listagem de cada um (observe que esta \u00e9 uma listagem parcial, as classes em sua totalidade podem ser encontradas aqui<\/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
\u00c9 claro que isso mapeia os documentos \"cerveja\"; observe o atributo DocumentTypeFilter. Isso adicionar\u00e1 \"automaticamente\" um predicado ou cl\u00e1usula WHERE que filtra pelo tipo \"cerveja\" a todas as consultas que t\u00eam como alvo esse documento. O atributo DocumentTypeFilter \u00e9 uma das duas maneiras de aplicar um filtro, a menos que voc\u00ea adicione manualmente o 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
Esse \u00e9 o objeto para o qual os documentos da \"cervejaria\" ser\u00e3o mapeados. Observe que n\u00e3o h\u00e1 nenhum atributo DocumentTypeFilter definido explicitamente; isso ocorre porque o construtor do contexto BeerSample adicionar\u00e1 o filtro ao DocumentFilterManager. Essa \u00e9 apenas uma abordagem diferente para o mesmo problema: adicionar um predicado a uma consulta para filtrar por tipo.<\/p>\n
Integra\u00e7\u00e3o com ASP.NET ou Owin\/Katana<\/h2>\n
H\u00e1 um padr\u00e3o muito distinto para usar o SDK do Couchbase .NET em projetos ASP.NET ou Katana\/OWin. Como o BucketContext usa o SDK do Couchbase .NET, voc\u00ea precisar\u00e1 seguir esse padr\u00e3o para aproveitar o cache de objetos no SDK e as conex\u00f5es TCP compartilhadas. Felizmente, \u00e9 um padr\u00e3o muito simples:<\/p>\n
Usando o Global.asax no ASP.NET<\/h3>\n
Em um aplicativo ASP.NET que usa o Global.asax, voc\u00ea aproveitar\u00e1 os manipuladores de eventos Application_Start e Application_End para criar e destruir os objetos Cluster e Bucket dos quais o BucketContext depende.<\/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
Aqui estamos criando a configura\u00e7\u00e3o (a prop\u00f3sito, isso tamb\u00e9m pode vir do App.Config) e, em seguida, inicializando o objeto ClusterHelper. Finalmente, quando o aplicativo \u00e9 encerrado, estamos destruindo os objetos Cluster e Bucket de longa dura\u00e7\u00e3o no manipulador Application_End. Esse ser\u00e1 um desligamento gracioso e as constru\u00e7\u00f5es no n\u00edvel do sistema operacional ser\u00e3o devolvidas ao sistema operacional em tempo h\u00e1bil.<\/p>\n
Uso do Setup.cs no Owin\/Katana<\/h3>\n
Nos aplicativos hospedados na Owin\/Katana, seguimos um padr\u00e3o semelhante, apenas usamos um m\u00e9todo diferente, a classe 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
Aqui, criamos e inicializamos o ClusterHelper quando o m\u00e9todo Configuration \u00e9 executado na inicializa\u00e7\u00e3o e, em seguida, registramos um delegado que ser\u00e1 acionado quando o aplicativo for encerrado, fechando nosso ClusterHelper e liberando recursos.<\/p>\n
Injetando em seus controladores<\/h3>\n
O BucketContext em si assume as caracter\u00edsticas do padr\u00e3o Unit of Work; voc\u00ea pode criar um para cada solicita\u00e7\u00e3o e, como o ClusterHelper gerencia as refer\u00eancias (supondo que voc\u00ea esteja seguindo as orienta\u00e7\u00f5es acima), a inst\u00e2ncia ser\u00e1 simplesmente GC no final da solicita\u00e7\u00e3o.<\/p>\n
A maneira mais simples de fazer isso \u00e9 simplesmente usar Inje\u00e7\u00e3o de depend\u00eancia<\/a> (o padr\u00e3o) em seus controladores para criar a inst\u00e2ncia quando o controlador for criado, por exemplo:<\/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
Agora, basta usar o BucketContext em seus m\u00e9todos de a\u00e7\u00e3o:<\/p>\n
public ActionResult Index()\r\n{\r\n    var query = (from beer in db.Beers\r\n        join brewery in db.Breweries\r\n        on beer.BreweryId equals N1QlFunctions.Key(brewery)\r\n        select new { \r\n            beer.Name, \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
Mais uma vez, como o contexto \u00e9 um objeto leve e de curta dura\u00e7\u00e3o, voc\u00ea pode definir o escopo para a solicita\u00e7\u00e3o e injet\u00e1-lo l\u00e1, reutilizando-o para todos os controladores invocados nessa solicita\u00e7\u00e3o.<\/p>\n
O que est\u00e1 por vir?<\/h2>\n
Muito em breve, o pr\u00f3ximo grande recurso ser\u00e1 o Change Tracking usando proxies. Al\u00e9m disso, espere por corre\u00e7\u00f5es de bugs, aprimoramentos de desempenho e outros recursos destinados a tornar o Linq2Couchbase um ODM\/ORM leve e com todos os recursos!<\/p>\n
Se houver um recurso que voc\u00ea deseja, uma corre\u00e7\u00e3o de bug ou se quiser contribuir, agradecemos todos os tipos de feedback, tanto os bons quanto os ruins.<\/p>\n