Forem: Scanbot SDK

Storage Wars: Web Edition – or, how we learned to store binary data effectively

Aare Undo — Mon, 23 Sep 2024 13:00:00 +0000

Prologue

All modern browsers offer ways to store data locally. Our world would look rather different if they didn’t. Since you’re reading this, I’m sure you already have some idea of what local storage in the browser is. Still, let’s quickly go over the basics.

I’m writing this in Google Docs. I figure it stores my data locally before syncing it to Google’s servers. This is a good thing, because it makes sure that any changes I make are immediately stored on my device, and that Docs doesn’t fully depend on an external server being available.

Cookies are the oldest way to store data locally – however, they’re ripe for abuse by third parties. They’re also intended for communication with servers anyway, so they are a story for another time.

Then we have session storage and local storage proper. They’re almost exactly the same, except for their scope and lifetime.

Local storage stores data per origin, meaning whenever and from whichever tab you visit the same URL, you have the same data stored locally.

Session storage, on the other hand, works per instance, meaning its lifecycle is bound to a single browser tab. It’s intended to allow separate instances of the same web app to run in different windows without interfering with each other, which is a nifty feature. However, it does not exactly fit our requirements.

Wait, which requirements? What exactly are we looking for?

We’re here to research storage options for the Scanbot Web SDK, you see.

This SDK has a complex API that deals with various different types of data. When you scan a document with it, you don’t just get a bunch of strings and numbers. For one, the result data also includes an array with the coordinates of the document’s location on the scanned image. For another, you also get the image itself as binary data (more on this later). All of this needs to be properly stored and managed as conveniently for the user as possible.

Here’s an example of the data object we need to store (I’ve removed annotations and irrelevant types for the sake of brevity):

class CroppedDetectionResult {
    croppedImage: RawImage | null;
    originalImage: Image;
    status: DetectionStatus = "NOT_ACQUIRED";
    detectionScores: DetectionScores;
    points: Point[];
    horizontalLines: LineSegment[];
    verticalLines: LineSegment[];
    aspectRatio: number;
    averageBrightness: number = 0;
}

As you can see, it’s not overly complicated. Some numbers and strings, some classes as types.

There are only two parts that are actually problematic: RawImage, which contains Uint8Array data, and Image, which is a type that can refer to any of the interfaces ImageData, ArrayBuffer, Uint8Array and RawImage itself.

How can we store all this, then?

Local storage

Let’s start with the basics, the OG of storage: localStorage. It has been available since before I could call myself a software developer, all the way back in 2009. Ah, simpler times. localStorage is still used in all kinds of applications and the API has remained relatively stable throughout the ages, so I will jump right into the implementation.

Let’s create a separate storage class for our data object. Just the bare bones for storing an item and retrieving it without worrying about unique keys or anything.

JSON parsing is necessary because localStorage only accepts strings as values, another indication that this is not meant for larger data sets. And here it is:

export default class SBStorage {

    static storeDocument(source: CroppedDetectionResult): void {
        localStorage.setItem("document", JSON.stringify(source));
    }

    static getDocument(): CroppedDetectionResult {
        const item = localStorage.getItem("document");
        return item ? JSON.parse(item) : null;
    }
}

Limitations

At this point, I just wanted to show you what a retrieved document looked like, but my React starter project immediately threw an exception:

sb-storage.ts:7 Uncaught (in promise) DOMException: Failed to execute 'setItem' on 'Storage': Setting the value of 'document' exceeded the quota.
    at SBStorage.storeDocument (

There is this nifty online tool that shows you how many characters can be held in localStorage: https://arty.name/localstorage.html. As of writing this, my limit seems to be 5,200,000. This number will vary based on the browser and version you’re using.

The site’s author even explains:

Chrome 6.0.472.36 beta let me save 2600-2700 thousands of characters, Firefox 3.6.8 – 5200-5300k, Explorer 8 – 4900-5000k, and Opera 10.70 build 9013 popped a dialog, that allowed me to give the script unlimited storage. Spec arbitrarily recommends 5 megabytes of storage, but doesn’t say a thing about actual characters, so in UTF-16 you get twice less.

So, let’s check how many characters’ worth of data we’re trying to store. A quick modification to the existing snippet …

const value = JSON.stringify(source);
console.log("Characters:", value.length);
localStorage.setItem("document", value);

… and the result we get is:

Characters: 68046772

As it turns out, localStorage can’t even store a tenth of that.

Even though we’ve already proven that it’s not a viable option here, I briefly want to touch on the fact that localStorage does not support binary data. That’s what I was going to get at in the first place, but instead we immediately ran into the quota issue.

I just want to quickly show you what serialization does to a binary data format. To begin with, the format of our croppedImage data is an Uint8Array. It looks more or less like what you would expect (this array is actually 1,504,272 characters long, but here’s the start of it):

[169, 195, 195, 169, 195, 195, 168, 194, 194, 168, ...

After serialization, the same array looks like the following:

{"0":169,"1":195,"2":195,"3":169,"4":195,"5":195,"6":168,"7":194,"8":194,"9":168, ...

We’ll get into why this is in a later section, but what we need to know right now is that localStorage only accepts strings and therefore doesn’t support binary formats out of the box.

There are ways to get around this – you can probably already imagine an algorithm to turn this map of keys and values back into an array of integers. It’s always going to be a hack, though. You just shouldn’t have to manipulate binary data manually.

Base64

The correct way to do this would be to convert the image data to a Base64 image first, which we can then store properly.

Base64 is a family of binary-to-text encoding schemes that represent binary data in an ASCII string format by transforming it into a radix-64 representation.

That may sound complicated, but it’s really a straightforward process. You simply create a reader object, pass your array as a blob, and read it in as a data URL using the native JavaScript function. If necessary, also remove the descriptor part of the string. Here’s the convenience function we use:

public static async toBase64(data: Uint8Array): Promise<string> {
    // See https://stackoverflow.com/a/39452119
    const base64url = await new Promise<string>(resolve => {
        const reader = new FileReader()
        reader.onload = () => resolve(reader.result as string)
        reader.readAsDataURL(new Blob([data]))
    });
    // remove the `data:...;base64,` part from the start
    return base64url.slice(base64url.indexOf(',') + 1);
}

And then the following, if not too long, can be effectively held in local storage:

const base64 = await ImageUtils.toBase64(source.croppedImage.data);
// Base64: wsLQw8LQw8LQw8TRxMXSxMXTxcfUxcjVxMjVxcnXx8vaztHh1dbm19np2dvr2Nv...
console.log("Base64: ", base64);

However, any kind of operation of this magnitude is computationally heavy, be it the direct manipulation of a key-value map or the Base64 version, and we’re trying to be optimal here. So all that just won’t cut it. We need to be able to work with binary data directly.

And this brings us to …

Binary data

In web development, we meet binary data mostly when dealing with files (creating, uploading, downloading). Another typical use case is image processing – which is what we’re doing here.

There are many classes for various implementations of binary data in JavaScript, such as ArrayBuffer, Uint8Array, DataView, Blob and File, but these different nuances of implementation aren’t important right now.

Anyway, the core object is ArrayBuffer – the root of everything, the raw binary data. And that is what we will be working with. Whichever of the aforementioned wrapper classes you use, it will contain a variation of an ArrayBuffer.

Everything is an object (almost)

Now, the explanation as to why stringification of ArrayBuffer or Uint8Array turns it into a bit of a nightmare is actually pretty interesting. You see, everything in JavaScript is actually an object, except strings. Strings are still strings. But with arrays, it means you can do the following:

const a  = [1, 2, 3]; a.foo = "bar"console.log(a); // [ 1, 2, 3, foo: 'bar']

That’s because natively, an array is still an object prototype, but it does stringify into looking like a simple array simply because its toString() function has been overwritten for the convenience of developers. Because it’s often needed.

And that is also exactly why stringifying an Uint8Array turns it into an object of key-value pairs (remember the {"0":169,"1":195,"2":195,"3":169 …} example from earlier) and why we need additional steps to properly serialize it.

Serialization

At this point, it’s also worth it to elaborate on a point I made previously: that binary data is not serializable. While that is still fundamentally true, JavaScript does have some native support for serialization these days, with the latest and greatest tool being TextDecoder. Take this example:

const buffer = new TextEncoder().encode('banana');
const testObj = { encodedText: buffer.toString() };

const serializedTestObj = JSON.stringify(testObj);
console.log(serializedTestObj); // {"encodedText":"98,97,110,97,110,97"}

const deserializedTestObj = JSON.parse(serializedTestObj);
const deserializedBuffer = deserializedTestObj.encodedText.split(',');
const newBuffer = Uint8Array.from(deserializedBuffer);
const str = new TextDecoder().decode(newBuffer);
console.log(str); // banana

Thank you to Will Munslow from dev.to for this snippet!

While it is relatively straightforward, you’ll notice right away that this encoding method requires:

For the data to initially be a string that’s serialized with the coder class, which is a relatively uncommon use case (in most cases you start off with binary data).
String splitting, which is an expensive operation.
At the end, both buffer deserialization and text decoding again.

Let’s now move on to the next web storage method.

IndexedDB

So, what is IndexedDB? I would’ve gladly given my own short overview of the concept, but MDN says it best:

IndexedDB is a low-level API for client-side storage of significant amounts of structured data, including files/blobs. This API uses indexes to enable high-performance searches of this data.

What that actually means for us is a convenient way to store the aforementioned binary data of ArrayBuffer format. Yay, no more of this complex, nonsensical and resource-hungry encoding and decoding logic!

To quickly reiterate, the main problems with localStorage are that:

It can only store strings.
It has a very small and unstable data cap.

IndexedDB easily solves both of these issues. On top of that, it has some additional benefits, such as the fact that it can be used inside web workers (more on this later). It’s also asynchronous, meaning the render cycle is not blocked while saving/loading.

The only thing localStorage has going for it is the simplicity of its API. It’s just localStorage.setItem and localStorage.getItem. There are a couple of additional convenience functions, but that’s roughly it. Done!

Messy API & solutions

IndexedDB isn’t perfect, either: The API is famously a fabulous mess. It’s such a mess, in fact, that a whole ecosystem of libraries has been developed around it just so that your average developer doesn’t have to deal with its nonsense.

So, before we finally move on to our actual implementation, let’s take a look at what’s already out there to help you with this.

There’s use-indexeddb, which promises to be the most lightweight one, but that’s because it only wraps a few of the basics. It’s not all that convenient to use, and it also features some intrusive logging that cannot be disabled.

Next up is Dexie, a more fully-fledged storage framework that looks pretty promising. Its API is very straightforward. It’s super intuitive to create a base, write queries and add entries:

const db = new Dexie('MyDatabase');

// Declare tables, IDs and indexes
db.version(1).stores({ friends: '++id, name, age' });

// Find some old friends
const oldFriends = await db.friends.where('age').above(75).toArray();

// or make a new one
await db.friends.add({
    name: 'Camilla',
    age: 25,
    street: 'East 13:th Street',
    picture: await getBlob('camilla.png')
});

At first glance, it seems to be inspired by C#’s LINQ statements, and it also supports live queries. That means you can combine it with, for example, Redux and completely handle state management through that. While that’s a nice feature, Dexie is actually a bit too elaborate for our use case.

Another one is idb, which claims to mostly mirror the IndexedDB API, but with some notable usability improvements. But really, looking at the implementation, it just seems to wrap the API in the Promise class and not much else. It’s definitely not worth the hassle of adding a third-party dependency for such a minor increase in convenience.

The final popular wrapper framework is called JsStore, which wraps the IndexedDB API into an SQL-like API.

var insertCount = await connection.insert({ into: 'Product', values: [value] });

var results = await connection.select({ from: 'Product', where: { id: 5 } });

Which, in my humble opinion, is not much of an improvement. SQL is still pretty complex and it’s easy to create sub-optimal transactions. It’s not raw SQL, so maybe it’s not too bad, but I’ve been burned by SQL too many times to trust anything like that again.

Plus, as with Dexie, JsStore seems to be overkill for our use case as well.

To be honest, I knew in advance that I wasn’t going to be impressed by any of these libraries. The plan was always to get our hands dirty, the Spartan way, and not to tie ourselves down by any more dependencies. I just wanted to give a quick overview of the options available. If our solution were more complex, I’d go with Dexie.

The Spartan approach

However, we’re building an SDK for clients, so we do not want to rely on any external libraries. It is possible, and we do use them, but we do not add them lightly, because:

They always come with a license, which we must adhere to and disclose.
They add overhead to future development and maintenance (I’m sure you know the pain of upgrading dependencies all too well).
They add additional points of failure to our project.

If possible and within reason, we want to be in control of what happens inside our SDK.

So, for our storage logic, let’s roll our own!

In terms of use cases, ours is relatively straightforward. The data model itself is complex, but the database transactions are not, so I was not expecting too much of a hassle. The basic setup is simple enough:

const request = indexedDB.open("SBSDKBase", 1);

We create the request, think of a name for the database and add a version number of the database we’re requesting from. Having to specify the version number right away may seem unnecessary, but the documentation makes it pretty clear why: database models change all the time and having an easy option to keep track of version history seems intuitive enough.

The request object has different callbacks: onerror, onupgradeneeded, and onsuccess. Right now, we can ignore errors, as we’re just trying to add some basic documents to the base and retrieve them. There’s no model changes, no indexing, we only use readwrite mode and increment automatically (let’s hope this doesn’t come back to bite us).

All we’re interested in at the moment is the success callback.

request.onsuccess = (event) => {
    const db = (event.target as IDBOpenDBRequest).result;
    db.createObjectStore("documents", { keyPath: "id", autoIncrement: true });

    const transaction = db.transaction("documents", "readwrite");
    const store = transaction.objectStore("documents");
    store.add(source);

    console.log("Added item to store");

    const getRequest = store.get(1);
    getRequest.onsuccess = (event) => {
        const result = (event.target as IDBRequest).result;
        console.log("Got item from store", result);
    };
};

This is the most bare-bones code snippet I thought I’d need to add a document to storage. Open the database, create a document table, put an object in it. I’ve been doing this for a long time, I’ve worked on various databases and thought I had a handle on it. I thought this would work.

Nope. I got bitten right away. The error:

Uncaught DOMException: Failed to execute 'createObjectStore' on 'IDBDatabase': The database is not running a version change transaction.

Why would I be unable to create a table when opening the database? I’m barely getting started and I already get the feeling that writing raw SQL is more intuitive than this. There, you can at least execute queries once you open the database.

Let’s hope it gets better from here on! At least the error message itself is not cryptic. We’ll try again by implementing onupgradeneeded (don’t forget to upgrade your db version):

request.onupgradeneeded = (event) => {
    const db = (event.target as IDBOpenDBRequest).result;
    db.createObjectStore("documents", { keyPath: "id", autoIncrement: true });
    console.log("IndexedDB upgraded", event);
};

Now we can also remove the create block from our success callback and voilá, we’ve created a database, added our first item to it, and also retrieved it:

request.onsuccess = (event) => {
    const db = (event.target as IDBOpenDBRequest).result;
    const transaction = db.transaction("documents", "readwrite");
    const store = transaction.objectStore("documents");
    store.add(source);
    console.log("Added item to store");

    const getRequest = store.get(1);
    getRequest.onsuccess = (event) => {
        const result = (event.target as IDBRequest).result;
        console.log("Got item from store", result);
    };
};

And the retrieved object still contains our image data in the correct Uint8Array format. Juicy!

Got item from store {
    status: 'OK', 
    detectionScores: {...}, 
    points: Array(4), 
    horizontalLines: Array(5), 
    verticalLines: Array(5), …}
    aspectRatio: 0.698217078300424averageBrightness: 183
    croppedImage: {..., format: 'BGR', data: Uint8Array(1859760)
    ...
}

Asynchronous improvements

Time to make the entire process a bit more convenient. Let’s wrap the database opening into its own asynchronous block:

private static openDB(): Promise<IDBDatabase> {
    return new Promise((resolve, reject) => {

        const DB_NAME = "SBSDKBase";
        const DB_VERSION = 4;
        const request = indexedDB.open(DB_NAME, DB_VERSION);

        request.onsuccess = (event) => {
            resolve((event.target as IDBOpenDBRequest).result);
        };

        request.onerror = (event) => { reject(event); };
        request.onupgradeneeded = (event) => {
            // Update object stores when necessary
        };
    });
}

And another block to get the store itself, so we don’t have to duplicate that any further:

private static async getDocumentStore(): Promise<IDBObjectStore> {
    const db = await SBStorage.openDB();
    const transaction = db.transaction("documents", "readwrite");
    return transaction.objectStore("documents");
}

And now we have two super intuitive public functions for our storage service to store a document and retrieve all of them:

static async storeDocument(source: CroppedDetectionResult): Promise<void> {
    const store = await SBStorage.getDocumentStore();
    store.add(source);
}

static async getDocuments(): Promise<CroppedDetectionResult[]> {
    const store = await SBStorage.getDocumentStore();
    return new Promise((resolve, reject) => {
        store.getAll().onsuccess = (event) => {
            const result = (event.target as IDBRequest).result;
            resolve(result);
        };
    });
}

Eventually we’ll have to add proper error handling, but as you can see, with a couple of wrapper functions, it’s relatively easy to implement IndexedDB on your own, no third-party libraries required.

This asynchronous approach with Promise already utilizes callbacks and does not block the main thread. JavaScript is pretty nice, you see. We just implemented some basic syntactic sugar to make the code look nicer, and that ended up being the optimal approach anyway.

Timing transactions

It’s possible to optimize this even further, and we’ll get to that in a second. But first, let’s check out how much time all these transactions take. You should always know exactly what you’re optimizing and why. Performance metrics are key.

The most robust way to do this is to just go back to our initial implementation and measure how many milliseconds have passed after each meaningful operation. For example:

const currentMS = new Date().getTime();
const request = indexedDB.open("SBSDKBase", 4);
console.log("Opening indexedDB", new Date().getTime() - currentMS);

request.onsuccess = (event) => {
    const db = (event.target as IDBOpenDBRequest).result;
    const transaction = db.transaction("documents", "readwrite");
    const store = transaction.objectStore("documents");
    store.add(source);
    console.log("Added item to store", new Date().getTime() - currentMS);

    const getRequest = store.get(1);
    getRequest.onsuccess = (event) => {
        const result = (event.target as IDBRequest).result;
        console.log("Got item from store", new Date().getTime() - currentMS);
    };
};

Opening indexedDB 0
Added item to store 17
Got item from store 30

That’s not too bad, but it’s also not nothing. Considering that I’m currently working on a higher-end MacBook Pro with an M2 chip and an SSD, this operation could easily take 20–50 times as long on a lower-end Android or iOS device.

We have already implemented basic asynchronous IndexedDB usage with Promises, and in some use cases this would be good enough. But since we’re dealing with large chunks of data, though, it’s worth investing in true parallelism and moving everything off the main thread.

And this brings us to …

Web workers

Web workers are a simple means for web content to run scripts in background threads. The worker thread can perform tasks without interfering with the user interface. (MDN)

How web workers differ from promises/callbacks is rather fundamental.

I won’t dive too deep into threading, but to put it briefly, a JavaScript environment is fundamentally single-threaded. In its simplest form, asynchronous is just syntactic sugar for promise chains that allow for the user interface to be rendered before other long-running operations.

It’s also important to note that two jobs can never run in parallel in this environment. One async operation might run in between two jobs of another one, so in that sense they can run “concurrently.” For true parallelism, e.g. simultaneously rendering the user interface and storing data, we need threads.

Luckily, all modern browsers give us worker threads, allowing for this kind of operation.

Basic implementation & problems

Let’s see how we can set up worker threads for our specific use case, following the same example code used previously.

Spawning a worker is a relatively trivial task. From MDN’s examples, you just need to create a worker JavaScript file:

onmessage = function(e) {
  console.log('Worker: Message received from main script');
  const result = e.data[0] * e.data[1];
  if (isNaN(result)) {
    postMessage('Please write two numbers');
  } else {
    const workerResult = 'Result: ' + result;
    console.log('Worker: Posting message back to main script');
    postMessage(workerResult);
  }
}

And then you’re able to import it in your main JavaScript file and pass data to it as follows:

if (window.Worker) {
  const myWorker = new Worker("worker.js");

  [first, second].forEach(input => {
    input.onchange = function() {
      myWorker.postMessage([first.value, second.value]);
      ...

As you can see, running a piece of JavaScript code on another thread is not as trivial as running it asynchronously. You need to spawn a dedicated worker from a separate file. While that seems relatively simple, once your build system becomes more complex, so does this.

Where do you put your worker file in a Vite environment? Where does it go when you’re using Webpack? Does your environment use bare-bones Webpack that is configurable, or is it wrapped behind another build system? What if you also have automated tests running – are they easily able to pick up your worker file?

Or, to give a more specific example: We use Webpack to transpile the SDK, and it has a separate worker-loader plugin that can be used to ensure workers are bundled into the end product. That’s pretty straightforward. However, our development environment uses the SDK’s source code directly, so it’s necessary to have another option to make sure this worker file is properly compiled into that environment as well.

Loading a file as data

So, the easiest solution turns out to be to simply create the file as you normally would, in your source code, and then simply use JavaScript itself to package it into a blob. That blob is then loaded into the worker, exactly as another external JavaScript file would be (and thank you to Martins Olumide on dev.to for this hint).

It may sound convoluted, but it’s a pretty solid solution to start off with. I bet it’s good enough for production, but before shipping this, we will definitely delve into additional performance metrics to see whether using Webpack to pre-compile it into the bundle is better or not.

First, the basic worker file will look like this:

const workerFunction = function () {
   // Perform every operation we want in this function
   self.onmessage = (event: MessageEvent) => {
      postMessage('Message received!');
   };
};

// This stringifies the whole function
let codeToString = workerFunction.toString();
// This brings out the code in the bracket in string
let mainCode = codeToString.substring(codeToString.indexOf('{') + 1, codeToString.LastIndexOf('}'));
// Convert the code into a raw data
let blob = new Blob([mainCode], { type: 'application/javascript' });
// A url is made out of the blob object and we're good to go
let worker_script = URL.createObjectURL(blob);

export default worker_script;

The comments in the block above should make pretty clear what we intend to do: We’re basically mock loading a separate worker file by simply stringifying the entire worker and returning it as a blob.

Putting it all together

After that, we just need to refactor our previous code a bit to make it fit into that JavaScript function and we have our worker up and running. We move the previously defined wrapper functions inside that function (because, thankfully, in JavaScript you can have inner functions, else this would be a mess) and do exactly what we did previously, only now we need to post the message instead of returning the data:

const workerFunction = function () {

    function openDB(): Promise<IDBDatabase> {
        ...
    }

    async function getDocumentStore(): Promise<IDBObjectStore> {
        ...
    }

    self.onmessage = (event: MessageEvent) => {
        console.log("Received in worker thread:", event.data);
        if (event.data.type === 'storeDocument') {
            console.log("Storing document in worker thread");
            getDocumentStore().then((store) => {
                store.add(event.data.data);
                self.postMessage(true);
            });
        } else if (event.data.type === 'getDocuments') {
            console.log("Getting documents in worker thread");
            getDocumentStore().then((store) => {
                const request = store.getAll();
                request.onsuccess = (event) => {
                    self.postMessage((event.target as IDBRequest).result);
                };
            });
        }
    };
};

Now that we’ve moved all of the IndexedDB API implementation to the worker, our main storage service file ends up looking pretty bare:

import { CroppedDetectionResult } from "../../core/worker/ScanbotSDK.Core";
import worker_script from './worker/sb-storage.worker';

export default class SBStorage {

    private static readonly worker: Worker = new Worker(worker_script);

    static async storeDocument(source: CroppedDetectionResult): Promise<boolean> {
        this.worker.postMessage({ type: 'storeDocument', data: source });

        return new Promise<boolean>((resolve, reject) => {
            this.worker.onmessage = (event) => {
                resolve(true);
            }
        });
    }

    static async getDocuments(): Promise<CroppedDetectionResult[]> {
        this.worker.postMessage({ type: 'getDocuments' });
        return new Promise<CroppedDetectionResult[]>((resolve, reject) => {
            this.worker.onmessage = (event) => {
                resolve(event.data);
            }
        });
    }
}

All that’s left in this file is the code to import the blob, initialize the worker itself, post messages to the worker and resolve the promise once a message has been received.

And that’s it! Some additional error handling needs to be implemented, but that’s busywork at this point. The takeaway: In just a few steps, we’ve built ourselves an optimal storage solution for complex objects – using only IndexedDB and web workers, no third-party libraries needed.

Try the Integration Challenge – run our Android SDK in 10 minutes or less

Kevin — Wed, 17 Jul 2024 14:21:11 +0000

Did you visit Droidcon 2024 in Berlin? If so, you may have noticed our Integration Challenge, for which we asked developers to integrate our Barcode Scanner SDK for Android in less than 10 minutes.

40 people tried to do so. All of them managed it in less than 6 minutes, with the best time clocking in at incredible 1:02! 🤯

Can you top that? Let’s find out – we’ve added the instructions to our Quick Start Guide!

⏱️ If you want to see how fast you can do it, start your clock when you scroll down.

Let’s go through the steps one by one.

Step 1: Clone the template app (or create a project from scratch)

We’ve prepared a template project so you won’t waste any time on building a UI. You can clone or download it from our GitHub repository.

Open the project in Android Studio and you’re good to go.

Step 2: Add the Scanbot SDK dependencies

The Scanbot SDK for Android is distributed through our private Maven repository server (nexus.scanbot.io), which needs to be specified in the settings.gradle.kts file in the root folder of your project:

// settings.gradle.kts in the root of the project:
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()

        // Add Scanbot SDK maven repositories here:
        maven(url = "https://nexus.scanbot.io/nexus/content/repositories/releases/")
        maven(url = "https://nexus.scanbot.io/nexus/content/repositories/snapshots/")
    }
}

Afterward, the dependencies can be added in the dependencies section of your Android application project configuration, usually in the app/build.gradle.kts file:

// app/build.gradle.kts (dependencies section):
implementation("io.scanbot:scanbot-barcode-scanner-sdk:5.2.0")
implementation("io.scanbot:rtu-ui-v2-barcode:5.2.0")

To check out the latest version of the Scanbot SDK, please always refer to the SDK’s changelog.

For more details on the dependencies, please refer to our detailed installation guide.

Step 3: Add the camera permission

The Scanbot Barcode Scanner SDK needs access to the device camera so it can scan from a live camera stream. Therefore, you have to define the camera permission in the AndroidManifest.xml file:

<!-- AndroidManifest.xml: -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>

    <!-- Add Camera permission here: -->
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-feature android:name="android.hardware.camera" />

    <application ...>

Note how we also added the uses-feature tag for better recognition of your app on the Google Play Store (see the Android documentation).

Our Ready-to-Use UI Components handle the runtime permissions automatically, so there is no need to add anything else in the code.

Step 4: Initialize the SDK

Usually, we recommend initializing the SDK in the Application class of your app (see our detailed setup page). However, in this Quick Start guide, we’ll do it in an Activity class.

First, make sure to add the following imports to the top of the file (e.g., MainActivity.kt):

// Add the following imports in your Activity (for example, MainActivity.kt):
import android.widget.Toast
import androidx.activity.result.ActivityResultLauncher
import io.scanbot.sdk.barcode_scanner.ScanbotBarcodeScannerSDKInitializer
import io.scanbot.sdk.ui_v2.barcode.BarcodeScannerActivity
import io.scanbot.sdk.ui_v2.barcode.configuration.BarcodeScannerConfiguration
import io.scanbot.sdk.ui_v2.common.activity.registerForActivityResultOk

To initialize the SDK, simply use the ScanbotBarcodeScannerSDKInitializer class in the onCreate method of your Activity:

// Adapt your Activity's onCreate method as follows:
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    ...
    // Initialize the SDK here:
    ScanbotBarcodeScannerSDKInitializer()
        // optional: uncomment the next line if you have a license key
        // .license(this.application, LICENSE_KEY)
        .initialize(this.application)
}

💡 You can use the Scanbot Barcode SDK for quick testing or evaluation purposes even without a license key. However, the SDK will only work for 60 seconds per app session and may not be used for production purposes. Want to scan longer than 60 seconds? Get your free trial license key here.

Step 5: Start the Barcode Scanner and process the result

You only need a few lines of code to integrate the Scanbot Barcode Scanner UI (BarcodeScannerActivity) into your application’s workflow. It’s as simple as starting a regular Android Activity.

First, you need to register the ActivityResultLauncher in your Activity class and save it as a variable:

// Add the following variable in your Activity:
private val barcodeScreenLauncher: ActivityResultLauncher<BarcodeScannerConfiguration> =
    registerForActivityResultOk(BarcodeScannerActivity.ResultContract()) { resultEntity ->
        // Barcode Scanner result callback:
        // Get the first scanned barcode from the result object...
        val barcodeItem = resultEntity.result?.items?.first()
        // ... and process the result as needed, for example, display as a Toast:
        Toast.makeText(
            this,
            "Scanned: ${barcodeItem?.text} (${barcodeItem?.type})",
            Toast.LENGTH_LONG
        ).show()
    }

The result of the Barcode Scanner UI will be delivered to the callback you just defined.

Now, to launch the Barcode Scanner UI, you just call the barcodeScreenLauncher where needed. For example, in the setOnClickListener of your button:

// Launch the barcode scanner in your Activity:
barcodeScreenLauncher.launch(BarcodeScannerConfiguration())

🚀 That’s it! 🚀 You have successfully integrated a full-featured barcode scanner as an RTU UI Activity into your app. If you’d like, let us know what your time was!

💡 Customization: In this Quick Start guide, we have used the default configuration for the scanner UI. Feel free to explore the configs and customize the UI and the behavior according to your needs via the BarcodeScannerConfiguration class. For more details, please refer to the Ready-to-Use UI page.

Integrating a barcode scanner into your iOS app – the easy way

Kevin — Fri, 28 Jun 2024 11:25:46 +0000

Want to integrate barcode scanning functionalities into your iOS app? With our Ready-to-Use UI, this only takes you a few minutes. We’ll show you how it works!

Introduction

Setting up a simple app that can scan any 1D or 2D barcode is very straightforward – all we need are the following steps:

Create a project
Install the SDK
Set up the main screen
Implement the scanning modes
Build, run, and scan!

After that, you will be scanning barcodes with lightning speed! ⚡

Requirements

All you need for this project is the following:

macOS with Xcode 14.0 or higher
A test device, since we’ll need to use the camera (minimum deployment target: iOS 13.0)
Basic knowledge of how to build an iOS app

💡 Our iOS Barcode Scanner SDK supports both Swift and Objective-C, but we’ll stick to Swift for this tutorial.

Preparing the project

First, we’re going to create a new Swift project with the Storyboard interface.

To create the project:

Open Xcode and click on Create New Project… (or go to File -> New -> Project…)
Make sure you have the iOS tab selected, then choose App.
Give it a name, e.g., MyBarcodeScanningApp.
Choose Storyboard as the interface.
Select Swift as the programming language.

Next, we’ll install the Barcode Scanner SDK package.

Installing the SDK

For this tutorial, we will use the Swift Package Manager to install the Barcode Scanner SDK.

In Xcode, go to File -> Add Package Dependencies…
Paste the following package URL into the search bar: https://github.com/doo/scanbot-barcode-scanner-sdk-ios-spm.git
Select the package and click Add Package.
In the pop-up that appears after verification, for “Add to Target”, choose your project.
Click Add Package again.

💡 Without a license key, our SDK only runs for 60 seconds per session. This is more than enough for the purposes of our tutorial, but if you like, you can generate a license key here.

For more information about where to put the license key in your code, please refer to SDK Initialization in our docs.

We’ll need access to the device camera to scan barcodes, so let’s set the corresponding privacy property now.

In the project navigator, select your project, then select your app under “TARGETS”. Open the tab Info, add the target property Privacy – Camera Usage Description, and type in a meaningful value, e.g., “Grant access to your camera to start scanning”.

Integrating the scanning functionalities

Now that the project is set up, integrating barcode scanning into your app is very straightforward.

In fact, it’s so straightforward that we’ll implement not just one, but three different scanning modes in our project:

Single-barcode scanning: Read and show the value of a single barcode.
Multi-barcode scanning: Read as many barcodes as you like and display their values in a list.
AR overlay: Display the values of the barcodes in the viewfinder on the screen in real time.

Here’s how we’re going to achieve that:

Step 1: Set up the main screen (create three buttons and connect them to our View Controller)
Step 2: Implement the scanning modes (copy and paste the code for the three scanning modes into the @IBAction functions)
Step 2.5 (optional): Customize the scanning UI
Step 3: Start scanning 🤳

Let’s dive right in!

Step 1: Setting up the main screen

How exactly you approach this is up to you, but for the sake of this tutorial, we will just add three UIButton elements (“Single-Barcode Scanning”, “Multi-Barcode Scanning”, and “AR Overlay”) onto the View Controller Scene in Main.storyboard. Then, we connect them as an Action to ViewController.swift by dragging them while holding the control key.

For our purposes, let’s call the resulting @IBAction functions “startSingleScanning”, “startMultiScanning”, and “startAROverlay”.

We also need to import the ScanbotBarcodeScannerSDK package like so:

import ScanbotBarcodeScannerSDK

In the next step, we’ll add the code to get our scanning interface up and running into those functions.

Step 2: Implementing the scanning modes

Thanks to our RTU UI components, integrating our Barcode Scanner SDK’s features into your app is a breeze!

In fact, you can just copy and paste the code from our documentation 🦥

Here’s the code to put in each function for your convenience:

For single-barcode scanning:

...
    @IBAction func startSingleScanning(_ sender: Any) {
        // Create the default configuration object.
        // Create the default configuration object.
        let configuration = SBSDKUI2BarcodeScannerConfiguration()

        // Initialize the single-scan use case.
        let singleUsecase = SBSDKUI2SingleScanningMode()

        // Enable and configure the confirmation sheet.
        singleUsecase.confirmationSheetEnabled = true
        singleUsecase.sheetColor = SBSDKUI2Color(colorString: "#FFFFFF")

        // Hide/unhide the barcode image of the confirmation sheet.
        singleUsecase.barcodeImageVisible = true

        // Configure the barcode title of the confirmation sheet.
        singleUsecase.barcodeTitle.visible = true
        singleUsecase.barcodeTitle.color = SBSDKUI2Color(colorString: "#000000")

        // Configure the barcode subtitle of the confirmation sheet.
        singleUsecase.barcodeSubtitle.visible = true
        singleUsecase.barcodeSubtitle.color = SBSDKUI2Color(colorString: "#000000")

        // Configure the cancel button of the confirmation sheet.
        singleUsecase.cancelButton.text = "Close"
        singleUsecase.cancelButton.foreground.color = SBSDKUI2Color(colorString: "#C8193C")
        singleUsecase.cancelButton.background.fillColor = SBSDKUI2Color(colorString: "#00000000")

        // Configure the submit button of the confirmation sheet.
        singleUsecase.submitButton.text = "Submit"
        singleUsecase.submitButton.foreground.color = SBSDKUI2Color(colorString: "#FFFFFF")
        singleUsecase.submitButton.background.fillColor = SBSDKUI2Color(colorString: "#C8193C")

        // Set the configured use case.
        configuration.useCase = singleUsecase

        // Create and set an array of accepted barcode formats.
        configuration.recognizerConfiguration.barcodeFormats = SBSDKUI2BarcodeFormat.twoDFormats

        // Present the recognizer view controller modally on this view controller.
        SBSDKUI2BarcodeScannerViewController.present(on: self,
                                                     configuration: configuration) { controller, cancelled, error, result in

            // Completion handler to process the result.
            // The `cancelled` parameter indicates whether the cancel button was tapped.

            controller.presentingViewController?.dismiss(animated: true)
        }
...

For multi-barcode scanning:

...
    @IBAction func startMultiScanning(_ sender: Any) {
        // Create the default configuration object.
        let configuration = SBSDKUI2BarcodeScannerConfiguration()

        // Initialize the multi-scan use case.
        let multiUsecase = SBSDKUI2MultipleScanningMode()

        // Set the counting repeat delay.
        multiUsecase.countingRepeatDelay = 1000

        // Set the counting mode.
        multiUsecase.mode = .counting

        // Set the sheet mode of the barcodes preview.
        multiUsecase.sheet.mode = .collapsedSheet

        // Set the height of the collapsed sheet.
        multiUsecase.sheet.collapsedVisibleHeight = .large

        // Enable manual count change.
        multiUsecase.sheetContent.manualCountChangeEnabled = true

        // Configure the submit button.
        multiUsecase.sheetContent.submitButton.text = "Submit"
        multiUsecase.sheetContent.submitButton.foreground.color = SBSDKUI2Color(colorString: "#000000")

        // Set the configured use case.
        configuration.useCase = multiUsecase

        // Create and set an array of accepted barcode formats.
        configuration.recognizerConfiguration.barcodeFormats = SBSDKUI2BarcodeFormat.twoDFormats

        // Present the recognizer view controller modally on this view controller.
        SBSDKUI2BarcodeScannerViewController.present(on: self,
                                                     configuration: configuration) { controller, cancelled, error, result in

            // Completion handler to process the result.
            // The `cancelled` parameter indicates whether the cancel button was tapped.

            controller.presentingViewController?.dismiss(animated: true)
        }
...

For the AR overlay:

...
    @IBAction func startAROverlay(_ sender: Any) {
        // Create the default configuration ject.
        let configuration = SBSDKUI2BarcodeScannerConfiguration()

        // Configure the usecase.
        let usecase = SBSDKUI2MultipleScanningMode()
        usecase.mode = .unique
        usecase.sheet.mode = .collapsedSheet
        usecase.sheet.collapsedVisibleHeight = .small

        // Configure AR Overlay.
        usecase.arOverlay.visible = true
        usecase.arOverlay.automaticSelectionEnabled = false

        // Set the configured usecase.
        configuration.useCase = usecase

        // Create and set an array of accepted barcode formats.
        configuration.recognizerConfiguration.barcodeFormats = SBSDKUI2BarcodeFormat.twoDFormats

        // Present the recognizer view controller modally on this view controller.
        SBSDKUI2BarcodeScannerViewController.present(on: self,
                                                     configuration: configuration) { controller, cancelled, error, result in

            // Completion handler to process the result.
            // The `cancelled` parameter indicates whether the cancel button was tapped.

            controller.presentingViewController?.dismiss(animated: true)
        }
    }
}

There’s one tiny thing we’ll change here right away, though: We want to be able to scan both 1D and 2D barcode formats.

For this, let’s go to configuration.recognizerConfiguration.barcodeFormats in each @IBAction function and change SBSDKUI2BarcodeFormat.twoDFormats to SBSDKUI2BarcodeFormat.commonFormats.

Let’s now explore some of the other customization options.

Step 2.5 (optional): Customizing the scanning UI

Our RTU UI not only makes it very easy to integrate our SDK’s scanning functionalities, but also to style the UI elements in any way you like 🎨

(Well, maybe not in ANY way. Sorry, Bob.)

The comments already give you a hint about what’s possible to change:

Hide or show specific UI elements
Configure the active and inactive states of some UI elements
Change colors
Change titles and subtitles
Change the accepted barcode formats
Control the barcode sheet behavior for multi-scanning
… and more

As an example, let’s take a closer look at some of the configuration options of our multi-barcode scanning feature:

// Set the counting mode.
multiUsecase.mode = .counting

Here, we can change .counting to .unique. This will prevent the SDK from scanning multiple barcodes with the same value, which is helpful if you only want to count the number of unique barcodes.

// Set the sheet mode of the barcodes preview.
multiUsecase.sheet.mode = .collapsedSheet

Change .collapsedSheet to .button to not show the upper part of the barcode results sheet at the bottom of the screen and display a button that calls up the sheet instead.

💡 You can change the entire RTU UI’s color scheme using the palette feature.

Once you’ve made your changes, build and run your app.

Step 3: Scanning some barcodes!

Now you can go ahead and scan 1D and 2D barcodes – one after the other, many at the same time, and even with an AR overlay that lets you preview their values!

If you’re in need of some barcodes, we’ve got you covered:

If this tutorial has piqued your interest in integrating barcode scanning functionalities into your iOS app, make sure to take a look at our SDK’s other features in our documentation.

Happy coding!

Visual Studio alternatives for Mac – finding a new home for MAUI development

Mayank Patil — Tue, 18 Jun 2024 12:05:26 +0000

Support for Visual Studio for Mac will end on August 31, 2024. So, which tools should MAUI developers use when Visual Studio for Mac is no more? We’ve compared JetBrains Rider, the .NET MAUI extension for VS Code, and the CLI approach!

Introduction

Man, choosing a tool for developing cross-platform Xamarin apps on a Mac used to be so easy. Microsoft had our backs with Xamarin Studio, and later with Visual Studio for Mac.

Recently though, Microsoft decided to add a little twist!

Yes, the Xamarin MVP Monkey is giving us all a dramatic goodbye… 😢

And Visual Studio for Mac is going with it. 🎹🎹 Yep, you heard that right: Visual Studio for Mac 17.6 will ride off into the sunset on August 31, 2024.

Microsoft’s decision to retire the IDE isn’t unsurprising: The company is focusing on developing the .NET MAUI framework, the successor of Xamarin.Forms.

But fear not, dear developers, because Microsoft has a plan. 😉

They’re doubling down on Visual Studio Code as the go-to coding tool for Mac users. It’s like saying goodbye to your trusty old car and hopping into a shiny new rocket ship!

But there are other options that might just become your preferred development environment. So in this article, we’ll explore these options.

So strap in folks, because the MAUIverse is calling. 🚀

MAUI on Mac: your options

Alright, it’s time to check out the tools!

We’ll be covering three viable options for developing our .NET MAUI applications:

The .NET MAUI extension in Visual Studio Code for Mac
JetBrains Rider for Mac
Using the command line tools on Mac (with an editor of your choice)

In this post, we’ll look at how to set up all options, their usage, and their pros and cons. After all, with great tools comes great responsibility (and maybe a few bugs too!).

In particular, we’ll go through the following for each option:

Installation
Creating a new project
Running and debugging
Using the NuGet package manager

Let’s start with the .NET MAUI extension in Visual Studio Code, which is the option recommended by Microsoft.

.NET MAUI extension in Visual Studio Code

The .NET Multi-Platform App UI (MAUI) extension is the gateway to the MAUI realm for Visual Studio Code users on Mac. It comes with all the necessary tools for developing cross-platform apps.

With the ability to develop and debug your creations on various devices, emulators, and simulators directly within VS Code, Microsoft aims to replicate the seamless experience of Visual Studio for Mac.

The .NET MAUI extension is built on top of the powerful C#, C# Dev Kit and .NET Install Tool extensions, which gives you:

IntelliSense
An intuitive solution explorer
Package management and project references
Debugging
Unit tests
…and more!

💡 Installing the VS Code .NET MAUI extension also automatically installs the C#, C# Dev Kit and .NET Install Tool extensions as dependencies.

⚠️ Keep in mind that the .NET MAUI extension is still in preview. It therefore has some limitations and kinks to work out.

C# Dev Kit and C# extensions

C# Dev Kit is an extension designed to enhance your coding experience. Among other things, it gives you a solution explorer to navigate your code in the IDE as well as integrated unit test discovery and execution to ensure your code is test-driven.

This extension builds on the powerful C# language capabilities provided by the C# extension. C# Dev Kit’s tools and utilities integrate natively with VS Code and help developers to write and debug code faster, to avoid errors, and to simplify maintenance.

💡 C# Dev Kit is free for individuals, academia, and open-source development. For organizations, it’s included with Visual Studio Professional and Enterprise subscriptions.

Installation

Visual Studio Code is a lightweight but powerful source code editor. It comes with built-in support for JavaScript, TypeScript and Node.js and has a rich ecosystem of extensions for other languages and runtimes (such as C++, C#, Java, Python, PHP, Go, .NET).

Download VS Code and install it.
Download .NET and install it (make sure you download the right file for Apple Silicon machines).
In Visual Studio Code, install the .NET MAUI extension. This will also install C#, C# Dev Kit and .NET Install Tool as dependencies.

Installing the .NET MAUI extension in Visual Studio Code

For iOS/macOS development:

We need to install Xcode for its SDK and simulators. Downloading Xcode requires an Apple ID.
Download and install Xcode.
Install the Xcode command line tools with the following command:

xcode-select --install

Launch Xcode. On the first open it will ask you to set up the iOS Simulator, so let’s do that.

Your iOS setup is now ready to run on simulators. However, to run the app on your device, you will need a valid certificate and provisioning profile (you can find more information here).

For Android development:

Install Microsoft OpenJDK 17. Older JDK versions can cause issues and are therefore not recommended.
During the installation, JDK will prompt you to install Rosetta (if not already installed).
After installing JDK, create a new project and install the Android SDK using the following command:

sudo dotnet build -t:InstallAndroidDependencies
-f:net8.0-android
-p:AndroidSdkDirectory=/Users/MyLocalFolderName/Library/Android/sdk
-p:JavaSdkDirectory=/Library/Java/sdk
-p:AcceptAndroidSDKLicenses=True

In this command, AndroidSdkDirectory specifies where to install the Android SDK (e.g., /Users/MyLocalFolderName/Library/Android/sdk) and JavaSdkDirectory where to install the Java SDK (e.g., /Users/MyLocalFolderName/Library/Java/sdk).

💡 Another approach is to use Android Studio to manage the SDK, APIs, tools, emulators, debug options, logs, etc. This requires some environment variable setup.

Restart VS Code and check out the Output tab, which gives you information about the Android and iOS/macOS SDK status.
Now you have to accept the license for your Android SDK.

In VS Code, press Cmd + Shift + P, select “.NET MAUI: Configure Android”, and you should get an option to accept the license. Alternatively, restart your project, and you’ll be prompted to accept the license via the command line.

Set the JDK and Android SDK paths as well. In VS Code, press Cmd + Shift + P and select the option “.NET MAUI: Configure Android”

Now you should be able to run it on your Android device.

Finally, we need to install the .NET MAUI workloads with the following command:

dotnet workload install maui

Creating a new project

We will create our first Visual Studio Code demo application using the .NET MAUI extension as follows:

Click the Create .NET Project button or press Cmd + Shift + P
Select .NET: New Project
Select the project template .NET MAUI App
Select a project directory
Enter the project name and submit
Confirm Create Project

Creating a new project in VS Code using the .NET MAUI extension

If your project gets a build time error regarding the .NET MAUI tools, use the following command to install the necessary workloads:

dotnet workload restore

Running and debugging

On the bottom toolbar in Visual Studio Code, you will see the toolbar item “{ }” . With this, you can check the current target configuration.
Through the “{ }” button, you can also update the startup project and the target device options.
After selecting the configurations, you can simply press F5 to run the project. You can also open the RUN AND DEBUG tab from the side panel of VS Code and click on the Run and Debug button.
Debugging is similar to what we had in Visual Studio for Mac, like setting the breakpoints in the code.
Changing the configuration from Debug to Release mode isn’t supported yet. However, you can do that by adding a custom configuration in a launch.json file. After adding these configurations, you can use them from the RUN AND DEBUG tab.

The launch.json file is created locally in the .vscode folder. Here is what the configurations look like:

"configurations": [
    {
        "name": "Developer",
        "type": "maui",
        "request": "launch",
        "configuration": "Debug",
        "preLaunchTask": "maui: Build"
    },
    {
        "name": "Production",
        "type": "maui",
        "request": "launch",
        "configuration": "Release",
        "preLaunchTask": "maui: Build"
    }
  ]

Running and debugging in VS Code

Package management & project reference

NuGet package manager:

Visual Studio Code doesn’t really have a full-fledged NuGet package manager GUI like Visual Studio for Mac does. But there are some alternative options.

Restoring the packages:

You can set Automatic NuGet restore to ON. VS Code will now restore the packages automatically if the project is missing them.

Visual Studio Code -> Settings -> Extensions -> C# -> LSP Server -> Dotnet -> Enable Automatic Restore

Alternatively, go to Visual Studio Code -> Settings and search for the following text: ”dotnet.projects.enableAutomaticRestore”

This is the option we’re looking for:

“Enable Automatic Restore”

The other option is to use the command line to restore the packages. We’ll look at this in the next section.
To change or update the NuGet source, you have to modify the Nuget.Config file directly, which you can find at /Users/<username>/.config/NuGet.Config.

Adding NuGet packages and project references:

Adding, removing, and updating packages is easy. It’s not like the NuGet package manager window in Visual Studio for Mac, but it does the job.

To add a NuGet package or a project reference, go through the Solution Explorer context menu like so:

VS Code File Explorer -> Solution Explorer -> Expand Solution -> Right Click on the project

To remove/update a NuGet package, you can expand the project dependencies and navigate to the exact package.
To remove a project reference, you have to directly edit the .csproj file, e.g.:

<ItemGroup>
    <ProjectReference Include="..\..\FirstClassLibrary.csproj" />
</ItemGroup>

JetBrains Rider

I believe this GIF adequately portrays Rider’s power. But will you be able to handle it?

JetBrains Rider is a full-fledged cross-platform .NET IDE providing a complete environment for developing .NET MAUI apps.

Rider works with a wide variety of .NET Framework, Mono, and .NET Core project types. It supports most languages used in .NET development, including C#, VB.NET, F#, ASP.NET syntax, XAML, XML, JavaScript, TypeScript, JSON, HTML, CSS, and SQL. Its large set of powerful features that also work across different languages lets you deliver quality code faster than ever.

All this makes it the best choice for replacing Visual Studio for Mac.

One important thing to note, however, is that JetBrains Rider requires a paid subscription.

Highlights:

More stable and reliable compared to Visual Studio for Mac.
Eliminates a lot of the annoyances of developing .NET MAUI apps in Visual Studio for Mac.
A full-fledged IDE, unlike the .NET MAUI extension for VS Code.
The decompiler allows you to jump directly into the third-party package/code in your project, even from a particular XAML class implementation (e.g., Label).
Powerful IntelliSense code completion, refactoring, debugging, version control and more.
Convenient shortcuts that increase productivity, a bunch of different IDE settings, and more.

Installation

Download JetBrains Rider here and follow the general macOS application installation process.
For iOS/macOS development, we must install Xcode.
For Android, we need to install Microsoft OpenJDK 17 and Android Studio.

Initial JetBrains Rider settings

For Android development:

After installing Android Studio to get the Android SDK, launch JetBrains Rider.
Install the Rider Android Support plugin to get started with Android:

JetBrains Rider -> Settings -> Plugins -> Install "Rider Android Support"

After installing this plugin, a new tab will show up in the JetBrains Rider settings:

JetBrains Rider -> Settings -> Build, Execution, Deployment -> Android

Here, set the paths for the Android SDK and the Microsoft Open JDK 17.

Make sure the developer options are enabled on your Android device. This completes the setup for Android development, so your app is ready to roll on your device.

You also have the option to create and launch an emulator from Android Studio.

For iOS development:

Install Xcode, then launch it to download/install the iOS simulators.
Now launch JetBrains Rider and set the Xcode path:

JetBrains Rider -> Settings -> Build, Execution, Deployment -> Apple Platforms

After doing this, your iOS setup is complete, and your iOS app is also ready to roll on the simulator. To run the app on your iOS device, however, you will need a valid certificate and provisioning profile (you can find more information here).

Alright! Then let’s dive into creating a new application with Rider.

Creating a new project

Creating a new project is similar to Visual Studio for Mac: Just create a solution and select a project template.

Creating a new project in JetBrains Rider

Running and debugging

In Rider, there are separate sections for selecting a platform configuration, be it Android or iOS. The device and simulator/emulator lists are populated depending on the platform.

Device and simulator/emulator lists in Rider

For debugging, select the debug button in the bottom left of the IDE window.

NuGet package manager

Rider integrates a simple interface for the NuGet package manager. It provides a good interface for search filters, adding/selecting custom sources, and logs, installation of packages for multiple projects at once, and more.

You can also right-click on the project and select Manage NuGet package, which will open this tab at the bottom.

Managing NuGet packages in Rider

The buttons on the left allow you to restore/download, update, refresh packages and much more.

.NET CLI on Mac

For the elite developers who prefer flexing their CLI muscle over relying on fancy IDE magic and crave results based solely on their precise inputs rather than any third-party influence, we raise a digital salute. 🫡

I call those people Terminal Ninjas. With unwavering confidence in their commands, they bend the CLI to their will. If you’re among them: Kudos! Let’s get started.

Choosing the terminal

Just like the other options, this one also has its pros and cons. It might take a bit of R&D until you find all the necessary commands needed for your development process.

Installation

Download the .NET SDK here and install it.
Install the .NET MAUI workload by using this command in the terminal (with or without sudo, depending on your privileges):

dotnet workload install maui

To verify the workload installation, use the following command:

dotnet workload list

For developing iOS/macOS and Android applications, we need to do the following:

For iOS/macOS development, install the Xcode tool for SDK and simulators.
For Android development, install the Microsoft OpenJDK and Android Studio for the Android SDK and emulators.

For the individual iOS and Android setup steps, please refer to the .NET MAUI extension section above.

Creating a new project

Let’s jump into all the core commands you’ll need:

For creating a new project, the basic command is:

dotnet new maui

Here, maui is the template for MAUI projects. Typically, you’ll do this after some basic preparation, like creating a directory for the project:

mkdir FirstCLIApp
cd FirstCLIApp
dotnet new maui

This series of commands creates a new project based on the template maui in the directory name FirstCLIApp. So by default your solution will be created as FirstCLIApp.sln, which will have a MAUI project named FirstCLIApp.csproj.

For setting a project name, use the following command:

dotnet new maui -n "FirstCLIApp"

To check out all available project templates for a project, you can use this command:

dotnet new list

For more parameters you can use while creating a project, see below. You can find further details in the Microsoft docs.

dotnet new <TEMPLATE>
    [--dry-run]
    [--force]
    [-lang|--language {"C#"|"F#"|VB}]
    [-n|--name <OUTPUT_NAME>]
    [-f|--framework <FRAMEWORK>]
    [--no-update-check]
    [-o|--output <OUTPUT_DIRECTORY>]
    [--project <PROJECT_PATH>]
    [-d|--diagnostics]
    [--verbosity <LEVEL>]
    [Template options]

Running and debugging

In this section, we will look at the commands related to restoring, building and running the project. For the full command reference, check out the .NET CLI docs.

Restore packages: Restores the dependencies and tools of a project.

dotnet restore

Build: The following command will restore the project dependencies and build the app.

dotnet build
    [<PROJECT>|<SOLUTION>]
    [-a|--arch <ARCHITECTURE>]
    [--artifacts-path <ARTIFACTS_DIR>]
    [-c|--configuration <CONFIGURATION>] 
    [-f|--framework <FRAMEWORK>]
    [--disable-build-servers]
    [--force] [--interactive] 
    [--no-dependencies] 
    [--no-incremental]
    [--no-restore] 
    [--nologo] 
    [--no-self-contained] 
    [--os <OS>]
    [-o|--output <OUTPUT_DIRECTORY>]
    [-p|--property:<PROPERTYNAME>=<VALUE>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [--self-contained [true|false]] 
    [--source <SOURCE>]
    [--tl:[auto|on|off]] 
    [--use-current-runtime, --ucr [true|false]]
    [-v|--verbosity <LEVEL>] 
    [--version-suffix <VERSION_SUFFIX>]

Run: The following command will restore the project dependencies and build the app.

dotnet run 
    [-a|--arch <ARCHITECTURE>] 
    [-c|--configuration <CONFIGURATION>]
    [-f|--framework <FRAMEWORK>] 
    [--force] [--interactive]
    [--launch-profile <NAME>] 
    [--no-build]
    [--no-dependencies] 
    [--no-launch-profile] 
    [--no-restore]
    [--os <OS>]
    [--project <PATH>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [--tl:[auto|on|off]]
    [-v|--verbosity <LEVEL>]
    [[--] [application arguments]]

We can run the above commands without any parameters, but that sets them to their default values, which aren’t always what we need. So let’s jump into some use cases.

iOS simulator:

dotnet build
    -t:Run // target
    -f net8.0-ios // framework
    -p:_DeviceName=:v2:udid=<MY_SPECIFIC_UDID> // property

Here, the .NET MAUI iOS app is launched on a particular simulator by passing the simulator’s unique identifier. There are two ways to get the identifier:

Using Xcode:

Xcode -> Windows -> Devices and Simulators -> Right-click on the simulator -> Copy Identifier

Or using the command line (the following command prints all the devices in the terminal along with their identifiers):

/Applications/Xcode.app/Contents/Developer/usr/bin/simctl list

iOS device:

With the developer mode enabled on your iPhone or iPad, use the following command:

dotnet build
    -t:Run // target
    -f net8.0-ios // framework
    -p:RuntimeIdentifier=ios-arm64 // property
    -p:_DeviceName=<MY_SPECIFIC_UDID> // property

You can retrieve the device identifiers in the same way as the simulator identifiers.

Android emulator/device:

The following command works for both devices and emulators. If you use a device, make sure that developer mode is enabled.

dotnet build 
    -t:Run // target
    -f net8.0-android // framework

Finally, on the topic of debugging: When using the command line, debugging gets more complicated. It’s a huge topic that deserves an article of its own, so we won’t cover it here.

NuGet package manager

These are the commands used frequently to manage NuGet packages:

Restore the packages and tools for the project:

dotnet restore | dotnet restore <PROJECT_FILE>

Clear the local NuGet cache:

dotnet nuget locals all --clear

Add/remove a package:

dotnet remove [<PROJECT>] package <PACKAGE_NAME>

dotnet add [<PROJECT>] package <PACKAGE_NAME>
    [-f|--framework <FRAMEWORK>]
    [--interactive]
    [-n|--no-restore]
    [--package-directory <PACKAGE_DIRECTORY>]
    [--prerelease]
    [-s|--source <SOURCE>]
    [-v|--version <VERSION>]

There are many other important aspects, such as adding/removing/updating/disabling a custom source.

Add a NuGet source:

dotnet nuget add source <PACKAGE_SOURCE_PATH>
    [--name <SOURCE_NAME>]
    [--username <USER>]
    [--password <PASSWORD>]
    [--store-password-in-clear-text]
    [--valid-authentication-types <TYPES>]
    [--configfile <FILE>]

Remove a NuGet source:

dotnet nuget remove source <NAME> [--configfile <FILE>]

Enable or disable a NuGet source:

dotnet nuget disable source <NAME> [--configfile <FILE>]

dotnet nuget enable source <NAME> [--configfile <FILE>]

Update a NuGet source:

dotnet nuget update source <NAME>
    [--source <SOURCE>]
    [--username <USER>]
    [--password <PASSWORD>]
    [--store-password-in-clear-text]
    [--valid-authentication-types <TYPES>]
    [--configfile <FILE>]

Display a list of all available NuGet sources. It reads from the global Nuget.Config file:

dotnet nuget list source

Short comparison

Based on our own usage, we would like to provide feedback for the tools discussed in this article. As the command line approach is not a tool per se, we will only compare the .NET MAUI extension for Visual Studio Code and JetBrains Rider.

Rating factors	.NET MAUI extension	JetBrains Rider
IntelliSense / editor	★★★★★	★★★★★
Solution explorer	★★★	★★★★★
Decompiler & navigation	★★	★★★★★
Running and debugging	★★★	★★★★★
Package manager	★	★★★★★
Project ref. management	★	★★★★★
Feature richness	★★★	★★★★★
Free of charge?	✔️*	❌

Elaboration on some points

Solution explorer:
The solution explorer in Rider offers more features and settings compared to the VS Code .NET MAUI extension. It’s also more interactive.

Running and debugging:
The run-and-debug experience in Rider is superior, with more configuration options and an easy-to-use interface. For example, you can see the list of simulators and devices separately, unlike in the VS Code .NET MAUI extension.

Decompiler & navigation:
One very helpful feature in Rider is that you can navigate to the class declaration directly, even if it is a third-party library. Other than that, code navigation is similar in both.

Package manager:
The package manager in the VS Code .NET MAUI extension is very basic: You can just add/update/remove a NuGet package. But inside Rider, you get a dedicated tool where you can add/update/remove NuGet packages as well as NuGet sources.

Project reference management:
Project reference management is very easy in Rider. If you’re using the VS Code .NET MAUI extension, you have to manually add and remove references.

Feature richness:
Rider is a full-fledged IDE, so it has many more features compared to the VS Code .NET MAUI extension.

Pricing:
Rider is paid software. The VS Code .NET MAUI extension depends on the C# Dev Kit extension, which is free for individual, academic, and open-source developers. Enterprises will need a Visual Studio Professional subscription.

Recommendation

We hope this comparison of the currently available Visual Studio alternatives for Mac helped you choose the best option for developing .NET MAUI applications.

We’d like to leave you with the following advice:

If you prefer a fully fledged, powerful IDE, go with JetBrains Rider.
If you prefer to have a combination of a lightweight IDE and the CLI, then the .NET MAUI Extension in VS Code is your best bet.
If you don’t want to rely on anything but your commands, then go with the CLI. However, this option still requires a good editor, which in most cases will be VS Code.

Good luck in selecting your approach and happy coding!

Forem: Scanbot SDK

Storage Wars: Web Edition – or, how we learned to store binary data effectively

Prologue

Local storage

Limitations

Base64

Binary data

Everything is an object (almost)

Serialization

IndexedDB

Messy API & solutions

The Spartan approach

Asynchronous improvements

Timing transactions

Web workers

Basic implementation & problems

Loading a file as data

Putting it all together

Try the Integration Challenge – run our Android SDK in 10 minutes or less

Step 1: Clone the template app (or create a project from scratch)

Step 2: Add the Scanbot SDK dependencies

Step 3: Add the camera permission​

Step 4: Initialize the SDK

Step 5: Start the Barcode Scanner and process the result​

Integrating a barcode scanner into your iOS app – the easy way

Introduction

Requirements

Preparing the project

Installing the SDK

Integrating the scanning functionalities

Step 1: Setting up the main screen

Step 2: Implementing the scanning modes

Step 2.5 (optional): Customizing the scanning UI

Step 3: Scanning some barcodes!

Visual Studio alternatives for Mac – finding a new home for MAUI development

Introduction

MAUI on Mac: your options

.NET MAUI extension in Visual Studio Code

C# Dev Kit and C# extensions

Installation

Creating a new project

Running and debugging

Package management & project reference

JetBrains Rider

Installation

Initial JetBrains Rider settings

Creating a new project

Running and debugging

NuGet package manager

.NET CLI on Mac

Installation

Creating a new project

Running and debugging

NuGet package manager

Short comparison

Elaboration on some points

Recommendation

Step 3: Add the camera permission

Step 5: Start the Barcode Scanner and process the result