:::: MENU ::::

Tuesday, August 17, 2021

There are lots of occasions where you want to create a PDF document, e.g. for a report or an invoice. While there are plenty of options for PDF handling in .NET it turns out none of them actually work with Azure Functions running true serverless in a consumption plan. This is because all libraries I found do rely on GDI+ which is not available in the consumption plan. However most of these solutions work with Azure Functions running in App Plan Basic or higher.

So what is the alternative for running truly serverless?

One of the beauties of serverless systems to me is that you can mix and match runtimes and programming languages and really leverage the advantages of each to compose a distributed system. So while I prefer to build most Function apps using C# and .NET in this case nodejs with Javascript is a better alternative. Since the PDF creation will just be a small component of the overall solution I'm trying to build I can still use C# for all of my other functions.

For Javascript there is a really good library that works both in the browser and the server using nodejs: https://github.com/bpampuch/pdfmake

This library works well with Azure Functions running in the consumption plan and allows easy document composing using a template.

So let's create a new Azure Functions app. An intro into creating Azure Functions in general can be found here: https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-function-vs-code?pivots=programming-language-javascript

After that we need to install the pdfmake library

npm install pdfmake — save

I wanted the actual PDF template to be hosted in Azure blob storage so I can easily update it. Therefore we need to add an input binding to Azure storage to retrieve the template in our function.json:

{    "bindings": [      {        "authLevel": "function",        "type": "httpTrigger",        "direction": "in",        "name": "req",        "methods": [          "post"        ],        "route": "pdf"      },      {        "type": "http",        "direction": "out",        "name": "res"      },      {        "name": "pdfTemplate",        "type": "blob",        "path": "templates/template.json",        "connection": "Storage",        "direction": "in"      }    ]  }

Here is a sample template, I'm using to create a voucher. Find the full reference for creating pdf with pdfmake here: https://pdfmake.github.io/docs/

{      "pageSize": "A4",      "pageOrientation": "portrait",      "content": [        {          "text": "Gutschein",          "fontSize": 27,          "color": "#707070",          "margin": [            0,16          ],          "style": "page"        },        {          "text": "einlösbar bei",          "fontSize": 15,          "color": "#707070",          "margin": [            0,32,0,4          ],          "style": "page"        },        {          "text": "{vendor_name}",          "fontSize": 15,          "bold": true,          "style": "page"        },        {          "text": "{vendor_street}",          "fontSize": 15,          "style": "page"        },        {          "text": "{vendor_zip_city}",          "fontSize": 15,          "style": "page"        }      ]    }

So finally let's put this all together in our function's index.js

const pdfMakePrinter = require('pdfmake');    module.exports = async function (context, req) {      const voucher = context.req.body;      let templateStr = JSON.stringify(context.bindings.pdfTemplate);        templateStr = templateStr.replace('{vendor_name}', voucher.vendorName);      templateStr = templateStr.replace('{vendor_street}', voucher.vendorStreet);      templateStr = templateStr.replace('{vendor_zip_city}', voucher.vendorZipCity);        const pdf = await generatePDF(JSON.parse(templateStr));        context.res = {          body: pdf      };  };    async function generatePDF(docDefinition) {        const fontDescriptors = {           Roboto: {              normal: 'fonts/Roboto-Regular.ttf',              bold: 'fonts/Roboto-Medium.ttf',              italics: 'fonts/Roboto-Italic.ttf',              bolditalics: 'fonts/Roboto-MediumItalic.ttf'          }      };      const printer = new pdfMakePrinter(fontDescriptors);      const doc = printer.createPdfKitDocument(docDefinition);        return new Promise(resolve => {          const chunks = [];          doc.end();          doc.on('data', (chunk) => {              chunks.push(chunk);          });          doc.on('end', () => {              resolve(Buffer.concat(chunks));          });          });      };

Voucher is a json object we are receiving in the body of the incoming post request. The pdf template is providing via an input binding. After replacing some placeholders with real values in the template we can create the pdf file using the method generatePDF and return it as http response.

And that's it! Pretty simple eh? Now I can just call this function from other functions or from where ever.

----


Thursday, July 23, 2020

Multilingual support is one of the most common requirements for mobile apps. One of the great parts of building mobile apps with Xamarin is that handling multiple languages is super simple. It may seem like a difficult task, but it is relatively easy if you leverage built in .NET capabilities to add multilingual support to your apps. A while back I wrote an article on how to do add multilingual support with my plugin. In this article, I will talk about some typical problems that you might face when adding multilingual support and how to solve them. Let's start! 

Tuesday, June 2, 2020

On the speaking circuit, I've been doing a good number of presentations on Dapper. My talk is entitled Better Object Mapping in .NET with Dapper and this is an attempt to catch the eyes of developers who might have heard of object mapping from things like Entity Framework.

What is Dapper?

Dapper is a Micro-ORM or Micro Object Relational Mapper.

Maybe it's better to start at the beginning. If you're using a relational database, such as SQL Server, MySql, or PostgreSQL, you probably have had to deal with the problem of "how do I turn a result set into an object I can actually do work with?"

SQL Result + Object

There are a ton of ways to do this currently:

Write your own mapping from a result set

This process is really tedious, and I've written my fair share of code that gets the string from ordinal position 0 and the long from ordinal position 52.

I'm not even going to show demo code, because I don't want you to write it. Use Dapper.

EDIT: Ok - here's how'd you write it.

Imagine you have a (relational) database table called Users. It has columns in it.

Columntype
Idbigint
FirstNamenvarchar(50)
LastNamenvarchar(50)
EmailAddressnvarchar(255)
DateOfBirthdatetime

If you wanted to query that content, you could simply write the following SQL:

SELECT Id, FirstName, LastName, EmailAddress, DateOfBirth  FROM [dbo].[Users]

And if you wanted to get that data into an object that is actually useful... you'd... well..

public class ApplicationUser  {      public long Id { get; set; }      public string FirstName { get; set; }      public string LastName { get; set; }      public string EmailAddress { get; set; }      public DateTime DateOfBirth { get; set; }  }

Yeah! Write a DataReader...

var sql = @"SELECT Id, FirstName, LastName, EmailAddress, DateOfBirth          FROM [dbo].[Users]";    using (var connection = new SqlConnection(CONNECTION_STRING))  {      await connection.OpenAsync();      using (var reader = await connection.ExecuteReaderAsync(sql))      {          var applicationUsers = new List<ApplicationUser>();          while (await reader.ReadAsync())          {              applicationUsers.Add(new ApplicationUser()              {                  Id = reader.GetInt64(0), // ordinal position                  FirstName = reader.GetString(1),                  LastName = reader.GetString(2),                  EmailAddress = reader.GetString(3),                  DateOfBirth = reader.GetDateTime(4)              });          }          return applicationUsers;      }  }

Not bad, right? Maybe not, until you're trying to retrieve a 10+ column result set.

Also, what if you want to change the order of your parameters? You need to reorder the ordinal positions of your readers.

Yes, you can get the ordinal by calling reader.GetOrdinal("EmailAddress");. Please don't do that in the .ReadAsync() loop though. Call it once outside of the loop and cache the results. Calling GetOrdinal for each column on each row read is expensive and will slow down you application.

And the more obvious detail, you need to know the data types for the columsn you're retrieving! Is it a string? Or a datetime? Or an Int16, Int32, or Int64?? Wowza.

Data Tables

The first .NET project I worked on back in 2007 used DataTables exclusively for all data access. This was to the extent where I believed DataTables were the ONLY way to get the results of a SQL Query.

And DataTables aren't too bad. The biggest downside to them is that they're memory hogs, and using them with larger datasets can imped performance.

Example:

var sql = @"SELECT Id, FirstName, LastName, EmailAddress, DateOfBirth          FROM [dbo].[Users]";    using (var connection = new SqlConnection(CONNECTION_STRING))  {      await connection.OpenAsync();      using (var reader = await connection.ExecuteReaderAsync(sql))      {          DataTable table = new DataTable();          table.Load(reader);            var emailAddress = table.Rows[0]["EmailAddress"];      }  }

Again - not bad! This approach is more accessible (in my opinion) than the DataReader.

Entity Framework

EF is the 6,000 pound gorilla in the room. It's what Microsoft recommends using for data access. And I have a lot of opinions on why I don't like Entity Framework for data access, but I don't feel this is the place nor the time.

By the way, it's great for demos.

Other Micro ORMS

Here are some other ORMs that are interesting to look at:

What makes Dapper special?

At its core, Dapper is simply a collection of extension methods off of a SqlConnnection object.

Here is an example of using Dapper to query the database and return a list of objects.

Remember our object?

public class ApplicationUser  {      public long Id { get; set; }      public string FirstName { get; set; }      public string LastName { get; set; }      public string EmailAddress { get; set; }      public DateTime DateOfBirth { get; set; }  }

Here's the Dapper approach to Querying and Mapping the results to an object (or in our case, a collection of objects).

using (var connection = new SqlConnection(CONNECTION_STRING))  {      var sql = "SELECT Id, FirstName, LastName, EmailAddress, DateOfBirth From [dbo].[Users]";        var results = await connection          .QueryAsync<ApplicationUser>(sql);  }

That's it. No need to .Open the connection. Just create it and call the Query or QueryAsync method.That's a great question. Let's go back to the DataReader example and see how it was done there:

var sql = @"SELECT Id, FirstName, LastName, EmailAddress, DateOfBirth                      FROM [dbo].[Users] WHERE FirstName = @firstName";    using (var connection = new SqlConnection(CONNECTION_STRING))  {      await connection.OpenAsync();      using (var command = connection.CreateCommand())      {          command.CommandText = sql;          command.Parameters.AddWithValue("firstName", "Kevin");            using (var reader = await command.ExecuteReaderAsync())          {              var applicationUsers = new List<ApplicationUser>();              while (await reader.ReadAsync())              {                  applicationUsers.Add(new ApplicationUser()                  {                      Id = reader.GetInt64(0), // ordinal position                      FirstName = reader.GetString(1),                      LastName = reader.GetString(2),                      EmailAddress = reader.GetString(3),                      DateOfBirth = reader.GetDateTime(4)                  });              }              return applicationUsers;          }      }  }

What's the difference? First, the SQL statement has a WHERE clause in it. I've added a parameter with the @firstName identifier.

Note: Please please please parameterize your SQL queries. This is one of the easiest things you can do to protect your databases.

In order for the query to work, you need to pass the parameter value to the data reader. I had to take an extra step by creating a full SqlCommand instead of just executing a reader. Not a big deal - but it's necessary to add parameters.

command.Parameters.AddWithValue("firstName", "Kevin"); tells the command which parameter I want to map to and the value to use for it.

Now! Let's do the same with Dapper.

var sql = @"SELECT Id, FirstName, LastName, EmailAddress, DateOfBirth          FROM [dbo].[Users] WHERE FirstName = @firstName";    using (var connection = new SqlConnection(CONNECTION_STRING))  {      var results = await connection          .QueryAsync<ApplicationUser>(sql, new { firstName = "Kevin" });  }

The next parameter of QueryAsync (or many other Dapper methods) is a parameter object.

I'm passing an anonymouse object for my parameters, and Dapper will assist with telling the database that I want @firstName to map to Kevin. I don't need to worry about any of that work.

It seems like you're over-simplfying?

I totally am. But my goal here is to tell you what Dapper is meant to do.

Most database operations you need to make: SELECT, UPDATE, INSERT, DELETE are supported with a couple lines of code. I'm planning several follow up posts that cover scenarios around these topics, but I felt this article would become more reference than "hey, this is a tool I like and you should check it out."

Rob made a great point earlier, I'm not really diving in deep enough into mapping. There is a rabbit hole of use-cases where Dapper can be combined with other awesome libaries, like AutoMapper. I'm not diving in deep here, but it seems like a great idea for future posts.

Use Stored Procedures? No problem

I also use Dapper in every single application I scaffold out. It's that critical to my project success.

Is it open-source?

Yes! And even better, it's built by the good folks over at StackOverflow. Maybe you've heard of it. It's one of the most frequented websites on the internet, and they do not play around when it comes to performance.

Dapper was created by their team in order to make mapping data to objects as painless as possible while being fast. Check out their performance benchmarks

Give it a try!

If you're jumping into Dapper for the first time, take it easy! There are a lot of great examples in the GitHub repo for getting started.

If you run into problems, feel free to ask me on Twitter. I'm happy to research your questions and write some detailed explainations on more complex use-cases.

More