Documentación PetaPoco en Español

2011-09-30T11:45:00.001-06:00

Nota del editor: Esta es una traducción libre no oficial de la documentación de PetaPoco, el archivo original se encuentra disponible en:

http://www.toptensoftware.com/petapoco/

Aún se encuentra en borrador por lo que existen faltas de ortografía, sintaxis y traducción que se ajustaran conforme tenga tiempo.

PetaPoco

Un pequeño ORM para POCOs.

PetaPoco es un pequeño y rápido micro-ORM de un solo archivo para. NET y Mono.
Como Massive es un archivo único que es fácil añadir a cualquier proyecto.
A diferencia Massive que funciona POCOs fuertemente tipados.
Al igual que Massive, soporta dynamic Expandos - leer más.
Al igual que ActiveRecord, soporta con una estrecha relación entre el objeto y la tabla de base de datos.
Al igual que SubSonic, soporta la generación de las clases POCO con plantillas T4.
Al igual que Dapper, es rápido, ya que utiliza la generación de método dinámico (MSIL) para asignar valores a las propiedades de las columna.

Antecedentes

PetaPoco fue originalmente inspirado en Massive de Rob Conery, pero para su uso con objetos POCO no dinámicos

Lo comencé por que muchos de mis proyectos que utilizan SubSonic / Linq eran lentos o se convertían en una mezcla de LINQ y codinghorror.

Necesitaba una capa de acceso a datos pequeña, rápida, fácil de usar y que funcionara en NET 3.5 y / o Mono 2.6 (es decir: sin soporte para dynamic expandos)

Massive y sus 400 líneas de código me intrigaron y me preguntaba si algo similar se podría hacer sin dynamics.

Así que, ¿cuál nombre? Bueno, si es Massive es masiva, se trata de "Peta" masiva (ahora tiene más de 1.500 líneas, después de todo) y ya que trabaja con "POCO"s ... "PetaPoco" parecía un nombre divertido!

El numero de líneas de PetaPoco ha crecido hasta más de lo que se esperaba - no es el pequeño Massive de 400 líneas.

Pero echa un vistazo a lo que puede hacer ... reúne una gran cantidad de fuerza para su tamaño.

Características

Pequeño, sin dependencias ... un solo archivo de C # que se puede añadir a cualquier proyecto.
Funciona con POCOs estrictamente sin decorar, o POCOs con atributos.
Métodos auxiliares para Insert/Delete/Update/Save y IsNe.
Peticiones de paginado automático, obtiene el número de registros totales y buscar una página específica.
Soporte fácil de transacciones.
Soporte de remplazo de paramentos mejorado, incluyendo parámetros con nombre de las propiedades del objeto.
Gran rendimiento mediante la eliminación de LINQ y la asignación de propiedades rápido con la generación dinámica de métodos.
Incluye plantillas T4 para generar automáticamente las clases POCO.
El lenguaje de consulta es SQL ... sin una extraña sintaxis fluent o Linq (sí, cuestión de opinión)
Incluye una clase para construir SQL con baja fricción que hace que la escritura de SQL sea mucho más fácil.
Opciones para el registro de excepciones, la instalación de convertidores de valores y el mapeo de columnas a propiedades sin atributos.
Trabaja con SQL Server, SQL Server CE, MySQL, PostgreSQL y Oracle.
Trabaja bajo. NET 3.5 o Mono 2.6 y posteriores.
Soporte experimental para dynamic bajo. NET 4.0 y Mono 2.8
Pruebas NUnit.
OpenSource (licencia Apache)
Todo esto en unas 1.500 líneas de código

Descarga

PetaPoco esta disponible desde:

NuGet - http://nuget.org/List/Packages/PetaPoco

GitHub - https://github.com/toptensoftware/petapoco

Vamos al código!

Estos ejemplos comienzan más detallados de lo que necesitan pero se vuelven menos detallados según se introducen más funciones ... asegúrese de leer todo para tener una experiencia completa. He referenciado explícitamente el espacio de nombres PetaPoco, tal vez necesites agregar using PetaPoco.

Además, todos estos ejemplos han sido escritos a mano sin compilado. Es probable que existan errores. Si es así, por favor hágamelo saber.

Sin Ensamblados (dlls)

PetaPoco consta de un solo archivo – PetaPoco.cs. No requiere de ninguna dependencia, solo el GAC.

Agrega el archivo a tu proyecto y listo...

Ejecutando consultas

Define tu clase POCO:

// Representa un registro en la tabla de artículos

public class article

{

public long article_id { get; set; }

public string title { get; set; }

public DateTime date_created { get; set; }

public bool draft { get; set; }

public string content { get; set; }

}

Después, crea un PetaPoco.Database y ejecuta la consulta

// Crea un objeto database de PetaPoco

var db=new PetaPoco.Database("connectionStringName");

// Muestra todos los articulos

foreach (var a in db.Query<article>("SELECT * FROM articles"))

{

Console.WriteLine("{0} - {1}", a.article_id, a.title);

}

Para consultar un escalar

long count=db.ExecuteScalar<long>("SELECT Count(*) FROM articles");

O para obtener solo un registro

var a = db.SingleOrDefault<article>("SELECT * FROM articles WHERE article_id=@0", 123));

Paginado

PetaPoco puede paginar automáticamente

var result=db.Page<article>(1, 20, // <-- page number and items per page

"SELECT * FROM articles WHERE category=@0 ORDER BY date_posted DESC", "coolstuff");

Esto regresara un objeto PagedFetch

public class Page<T> where T:new()

{

public long CurrentPage { get; set; }

public long ItemsPerPage { get; set; }

public long TotalPages { get; set; }

public long TotalItems { get; set; }

public List<T> Items { get; set; }

}

Internamente, Petapoco hace lo siguiente:

1. Sintetiza y ejecuta la consulta para obtener el numero total de registros.

2. Modifica la consulta original para solicitar solo el subconjunto necesario.

Query vs Fetch

La clase Database tiene dos métodos para recuperar registros Query vs Fetch. Son muy similares excepto por que Fecth regresa un List<> de POCOs mientras que Query itera sobre el resultado sin cargar todo el conjunto memoria.

Comandos sin-consulta

Para ejecutar un comando sin-consulta usa el metodo Execute

db.Execute("DELETE FROM articles WHERE draft<>0");

Inserts, Updates and Deletes

Petapoco cuenta con auxiliares para insert, update y delete.

Para insertar un registro, necesitas especificar la tabla y la llave primaria:

// Crea un articulo

var a=new article();

a.title="My new article";

a.content="PetaPoco was here";

a.date_created=DateTime.UtcNow;

// Insertamos el articulo

db.Insert("articles", "article_id", a);

// Ahora a.article_id contendrá el id del nuevo registro

Actualizar es similar

// Obtenemos un registro

var a=db.SingleOrDefault<article>("SELECT * FROM articles WHERE article_id=@0", 123);

// Realizamos los cambios

a.content="PetaPoco was here again";

// Guardamos

db.Update("articles", "article_id", a);

O puedes pasar un tipo anónimo para actualizar un subconjunto de campos. En este caso solo el campo titulo se actualizara

db.Update("articles", "article_id", new { title="New title" }, 123);

Para eliminar

//Eliminar un articulo extrayendo la llave primaria del registro

db.Delete("articles", "article_id", a);

// O si ya se conoce la llave primaria

db.Delete("articles", "article_id", null, 123);

Decorando los POCOs

En los ejemplos anteriores, debemos especificar la tabla y la llave primaria, podemos ahorrarnos esto agregando esta información al POCO:

// Representa un registro en la tabla "articles"

[PetaPoco.TableName("articles")]

[PetaPoco.PrimaryKey("article_id")]

public class article

{

public long article_id { get; set; }

public string title { get; set; }

public DateTime date_created { get; set; }

public bool draft { get; set; }

public string content { get; set; }

}

Ahora los inserts, updates y deletes se simplifican a esto:

// Inserta un registro

var a=new article();

a.title="My new article";

a.content="PetaPoco was here";

a.date_created=DateTime.UtcNow;

db.Insert(a);

// actualizando

a.content="Blah blah";

db.Update(a);

// eliminando

db.Delete(a);

Hay otras sobrecargas para Update y Delete:

// Elimina un articulo

db.Delete<article>("WHERE article_id=@0", 123);

// Update an article

db.Update<article>("SET title=@0 WHERE article_id=@1", "New Title", 123);

Puedes indicar también que campos son ignorados

public class article

{

[PetaPoco.Ignore]

public long SomeCalculatedFieldPerhaps

{

get; set;

}

}

Si quieres ser mas explicito, en lugar de mapear todas las columnas puedes usar el atributo ExplicitColumns en la clase y Column en la propiedad para indicar que columnas deben ser mapeadas

// Representa un registro en la tabla "articles"

[PetaPoco.TableName("articles")]

[PetaPoco.PrimaryKey("article_id")]

[PetaPoco.ExplicitColumns]

public class article

{

[PetaPoco.Column] public long article_id { get; set; }

[PetaPoco.Column] public string title { get; set; }

[PetaPoco.Column] public DateTime date_created { get; set; }

[PetaPoco.Column] public bool draft { get; set; }

[PetaPoco.Column] public string content { get; set; }

}

esto funciona con partial classes. Colocas todo lo referente al mapeo de la clase en un archivo .cs y los campos calculados y otras propiedades se agregan en un archivo separado sin pensar en la capa de datos.

Plantillas T4

Escribir todos los objetos POCO a mano es tedioso y puede generar errores.

PetaPoco incluye plantillas T4 que pueden codificar automáticamente clases para todas las tablas de la base de datos, actualmente soporta: SQL Server, SQL Server CE, MySQL, PostrgeSQL y Oracle.

Usar las plantillas es muy simple, en el proyecto se incluye la carpeta \Models\Generates

PetaPocPetaPoco.Core.ttinclude – incluye todas las rutinas auxiliares para leer el esquema de la base de datos

PetaPoco.Generator.ttinclude – la plantilla actual que define que se generado

Database.tt – la plantilla en si misma que contiene varias configuraciones e incluye los otros dos archivos ttincluded

Un archivo Database.tt tipico se ve asi:

<#@ include file="PetaPoco.Core.ttinclude" #>

// Settings

ConnectionStringName = "jab";

Namespace = ConnectionStringName;

DatabaseName = ConnectionStringName;

string RepoName = DatabaseName + "DB";

bool GenerateOperations = true;

// Load tables

var tables = LoadTables();

<#@ include file="PetaPoco.Generator.ttinclude" #>

para usar las plantillas:

Agrega los tres archivos a tu proyecto.
Asegúrate de tener una connection string y un provider name configurados en el archivo app.config o web.config.
Cambia la propiedad ConnectionStringName en Database.tt por el nombre de tu connection string.
Guarda Database.tt.

Si todo sale bien Database.tt generara todos los POCOs representando las tablas en tu base de datos.

Para que funcione tienes que agregar también PetaPoco.cs a tu proyecto

La plantilla esta basada en la plantilla de Subsonic. Si estas familiarizado con su plantilla ActiveRecord veras que la plantilla de PetaPoco es muy similar.

Clausulas automáticas con Select

Cuando usas Petapoco, la mayoría de las consultas comienzan con “SELECT * FROM tabla”. Dado que ahora podemos extraer el nombre de la tabla directo del POCO usando el atributo TableName, también podemos generar automáticamente esta parte de la consulta.

Si ejecutas una consulta que no comience con “SELECT”, PetaPoco lo agregara automáticamente, así que:

// Obtener un registro

var a=db.SingleOrDefault<article>("SELECT * FROM articles WHERE article_id=@0", 123);

puede ser reducido a:

// Obtener un registro

var a=db.SingleOrDefault<article>("WHERE article_id=@0", 123);

PetaPoco no genera un “SELECT *”, en su lugar toma los nombres de las columnas del POCO y solo consulta estas columnas.

Metodos IsNew y Save

A veces vas a necesitar saber si un POCO ya esta guardado en la base de datos. Desde que tenemos la llave primaria, todo lo que tenemos que hacer es verificar si la propiedad a sido asignada a algún valor diferente de el valor default.

Así que para verificar si un registro es nuevo:

// Es un nuevo registro

if (db.IsNew(a))

{

// Si es...

}

También hay un método Save para ejecutar un Insert o Update según sea necesario

// Guarda un registro nuevo o existente

db.Save(a);

Transacciones

//Sección pendiente.

PetaPoco SQL Buildier (Constructor de Consultas SQL)

El objetivo es hacer el formateo de las sentencias SQL mas fácil y reemplazar los parámetros apropiados para protegernos de SQL Injection.

No es una forma de asegurarnos que la sentencia es sintácticamente correcta.

Esta es la forma mas básica:

var id=123;

var a=db.Query<article>(PetaPoco.Sql.Builder

.Append("SELECT * FROM articles")

.Append("WHERE article_id=@0", id)

)

Algo importante es que los índices de los parámetros son específicos en cada llamada a Append

var id=123;

var a=db.Query<article>(PetaPoco.Sql.Builder

.Append("SELECT * FROM articles")

.Append("WHERE article_id=@0", id)

.Append("AND date_created<@0", DateTime.UtcNow)

)

También puedes construir la sentencia condicionalmente:

var id=123;

var sql=PetaPoco.Sql.Builder

.Append("SELECT * FROM articles")

.Append("WHERE article_id=@0", id);

if (start_date.HasValue)

sql.Append("AND date_created>=@0", start_date.Value);

if (end_date.HasValue)

sql.Append("AND date_created<=@0", end_date.Value);

var a=db.Query<article>(sql)

por que cada llamada a append usa el parámetro @0? PetaPoco construye la lista completa de argumentos y actualiza los índices de parámetros internamente por ti.

Puedes también nombrar los parámetros y estos buscaran la propiedad apropiada en los argumentos.

sql.Append("AND date_created>=@start AND date_created<=@end",

new

{

start=DateTime.UtcNow.AddDays(-2),

end=DateTime.UtcNow

}

);

Con ambos, parámetros numerados o nombrados, si cualquiera de los parámetros no puede ser obtenido una excepción será lanzado.

Existen métodos para construir comandos SQL comunes.

var sql=PetaPoco.Sql.Builder()

.Select("*")

.From("articles").Where("date_created < @0", DateTime.UtcNow)

.OrderBy("date_created DESC");

Rastreo de comandos SQL

A veces es de utilidad tener disponible las sentencia SQL que acaba de ser ejecutada. Petapoco tiene las siguientes propiedades:

LastSQL – muy obvio.
LastArgs – un array de object con todos los argumentos pasados.
LastCommand – una string que muestra la sentencia SQL y los argumentos.

Visualizar la propiedad LastCommand en el debugger hace muy fácil saber lo que esta pasando.

OnException Handler Routine

PetaPoco envuelve todas las invocaciones de comandos SQL en try / catch. Las excepciones se pasa al método virtual OnException. Por el registro de estas excepciones (o el establecimiento de un punto de interrupción en este método) puedes seguir fácilmente una cuando hay problemas con el SQL.

Es todo

Cubrimos la mayoría de los aspectos básicos del trabajo con PetaPoco, pero para más información por favor lea estas publicaciones en el blog sobre PetaPoco.

Arturo Intentando Programar

Activar AgentXP en SQL Server 2005

Documentación PetaPoco en Español