Getting Started

In order to start working with Artisan.Orm:

1. Install the NuGet package or add Artisan.Orm project to your solution.

2. Make sure that your Web.Config (or App.config) file contains the connectionStrings section.

   <configuration>
     <connectionStrings>
       <add name="DatabaseConnection" 
            connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=Artisan;Integrated Security=True;Trust Server Certificate=True;" />
     </connectionStrings>
   </configuration> 

3. Create your repository class inheriting it from the Artisan.Orm.RepositoryBase:

   using Artisan.Orm;
   
   public class Repository: RepositoryBase
   {
   
   }

   Note that if the connection string name in Web.Config (or App.config) file is "DatabaseConnection" then you can skip the constructor for the repository. That "DatabaseConnection" connection string will be used by default.

   If your connection string has another name or you have several connection strings, then the connection string name or connection string itself can be passed as a parameter to the base:

   public class Repository: RepositoryBase
   {
       public Repository () : base ("AnotherConnection") {}
   
       /* or
   
       private string connectionString = @"Data Source=.\SQLEXPRESS;Initial Catalog=Artisan;Integrated Security=True;Trust Server Certificate=True;";
       public Repository () : base (connectionString) {}
   
       */
   }

   When the Repository class instance is created, the RepositoryBase creates an SqlConnection leaving it closed.

4. Add your repository methods basing then on RepositoryBase methods for SqlCommand initialization:

   For example:

   public User GetUserById(int id)
   {
       return GetByCommand(cmd =>    // SqlConnection is still closed here
       {
           cmd.UseProcedure("dbo.GetUserById"); // Configuring command with stored procedure name
           cmd.AddIntParam("@Id", id);          // and parameters 
   
           // SqlCommand extension opens SqlConnection, 
           // reads data, closes SqlConnection and returns the result.
           return cmd.ReadTo<User>();
       });
   }
   
   public void DeleteUser(Int32 userId)
   {
       ExecuteCommand(cmd =>  // SqlConnection is closed here
       {
           cmd.UseProcedure("dbo.DeleteUser"); // Configuring command with stored procedure name
           cmd.AddIntParam("@UserId", userId); // and parameters         
       }
       // Right after command configuration,
       // ExecuteCommand method opens SqlConnection, 
       // executes ExecuteNonQueryCommand and closes SqlConnection
      ); 
   }

   Read more about extension methods provided by Artisan.Orm:

   • Read Methods Understanding
   • SqlCommand Extensions
   • SqlDataReader Extentions

5. The RepositoryBase inherints IDisposable interface, so the best way of calling repository methods is within the using statement:

   User user;
   
   using (var repository = new Repository())
   {
       user = repository.GetUserById(i);
   }

   Or within try catch finaly:

   Repository repository;
   User user;
   
   try 
   {
       repository = new Repository();
       user = repository.GetUserById(i);
   }
   catch (Exception ex) 
   {
       ...
   }
   finaly {
       repository.Dispose();
   }

   Or to implement IDisposable interface in your calling class:

   public class DataService: IDisposable
   {
       private IDisposable repository;
   
       public DataService () 
       {
           repository = new Repository();
       }
   
       ...
       
       public void Dispose()
       {
           repository.Dispose();
       }
   }

6. Besides the repository and its methods, it is required to create:

   • Mappers (C#) for each reading/saving type,
   • User-defined table types (TSQL) for types intended for saving,
   • Stored procedures (TSQL) to read, save and delete objects.