Setting up a Xamarin app with ApiOmat
Within this tutorial we will take advantage of Xamarin's ability to share code between different projects and platforms. Therefore you will create a Xamarin. Forms app that uses a Portable Class Library (PCL) which contains the generated ApiOmat Xamarin SDK.
Using Xamarin Studio
Click New Solution and chose Multiplatform -> Apps -> Form App
In the next step select the desired target platforms and make sure the option Use Portable Class Library is selected. By clicking Next and Create afterwards, your solution will be created immediately.
Now, depending on what target platforms you've selected, a new solution with up to three new projects is created:
-
XamarinApp
-
XamarinApp.Droid
-
XamarinApp.iOS
The XamarinApp project is the PCL, where you will add the generated SDK. But before you do so, you need to configure it.
You cannot add Windows Phone 8.0 as target of the PCL, because the System.Linq.Parallel namespace, which is used by the SDK, is not supported on that platform.
This means you can't use PCL Profile 259. Instead we recommend to use PCL Profile 111. If your IDE doesn't show the profile number in the properties, you can open the .csproj file of the PCL project and see (and change) the profile there.
Add the required dependencies that are listed below:
-
Portable.BouncyCastle Version:1.8.1 (only needed when using the old C# SDK and not the new C# SQLite SDK)
-
sqlite-net-pcl
-
Regular C# / Xamarin SDK requires version 1.1.1
-
C#-SQLite / Xamarin-SQLite SDK (Beta) requires version 1.5.166-beta with the following dependency:
-
SQLitePCLRaw.bundle_green 1.1.11
-
-
If you are targeting Windows Phone 8 or later and no previously added package depended on it, then you also need to add Microsoft.Net.Http Version:2.2.29! Unfortunately, due to a problem with this package, GZip-Compression for outgoing and incoming requests won't be available in this case.
If you're not targeting Windows Phone 8 or later, please make sure that they're not selected as target frameworks in your project's build options.
Newer versions of the packages probably work as well, but we ran our tests with the versions mentioned above and thus only support them.
To add those packages, right click on Packages of the PCL project (XamarinApp in this example) and chose Add Packages...
Within the search bar you can search for the required packages. By adding version: x.x.x after the package name you can ensure that only the specific version will be listed. For each package activate the checkbox in front of the package's name. After adding all packages, simply click the Add Package button in the right corner at the bottom and all previously selected packages will be installed in a row. You will also have to accept the license agreement of some selected packages.
After adding all listed packages, your referenced packages should look like shown in the figure below:
Now you are ready to add the generated SDK. Right click on your project and choose Add existing folder... Choose the Com folder of your extracted Xamarin SDK, check Include All within the appearing dialogue and confirm by clicking OK. Afterwards, chose Copy the files to directory and confirm again by clicking the OK button.
Now, to make sure everything is fine, choose Project -> Build XamarinApp.
Please notice that you must also add some of the listed packages to your platform projects as well:
-
Portable.BouncyCastle (only needed when using the old C# SDK and not the new C# SQLite SDK)
-
sqlite-net-pcl
-
Xam.Plugin.Connectivity
-
Newtonsoft.Json
For the versions you have to use see the list above.
On some Windows targets (e.g. Windows 8 store app or Windows Phone 8.1 app), the SQLite-net PCL also requires to reference the Microsoft Visual C++ Runtime Package for Windows (a System.TypeInitializationException gets thrown from SQlitePCL.raw if required and missing).
When building your target project, the Xam.Plugin. Connectivity may complain about a duplicate "Plugin.Connectivity.pdb" on your build-path. You will have to delete the file either from the folder [MyProjectFolder]/packages/Xam.Plugin.Connectivity.[Version]/lib/portable-[targets] or from MyProjectFolder/packages/Xam.Plugin.Connectivity.[Version]/lib/[target] (whereas "MyProjectFolder" is the main folder for your solution, "Version" the installed version number of the package, "targets" the different supported targets for this library, as of writing "net45+wp80+wp81+wpa81+win8+MonoAndroid10+MonoTouch10+Xamarin.iOS10+UAP10" and "target" your specific target for the project, e.g. win8).
Now your PCL project should be built without any errors and we can add the project as a reference to the other project(s). Therefore, right click on the other project's References (those that aren't the PCL project) and choose Edit References...
When choosing the tab Projects you can now select your PCL project.
Because the ApiOmat C# / Xamarin SDK uses an SQLite database for saving requests when no connection to the server is available and for generally caching data, a few final steps are necessary to finish the setup.
According to Xamarin's documentation you have to define an interface, containing a method, that provides an existing SQLiteConnection in your PCL project. Afterwards you have to implement this interface in each of your platform specific projects, as shown below.
Content of ISQLite.cs (PCL project)
public interface ISQLite { SQLiteConnection GetConnection();}
Content of SQLite_iOS (iOS project)
[assembly: Dependency (typeof (SQLite_iOS))]// ...public class SQLite_iOS : ISQLite {public SQLite_iOS () {}public SQLite.SQLiteConnection GetConnection (){ var sqliteFilename = "TodoSQLite.db3"; string documentsPath = Environment.GetFolderPath (Environment.SpecialFolder.Personal); // Documents folder string libraryPath = Path.Combine (documentsPath, "..", "Library"); // Library folder var path = Path.Combine(libraryPath, sqliteFilename); // Create the connection var conn = new SQLite.SQLiteConnection(path); // Return the database connection return conn;}}
Content of SQLite_Android (Android project)
[assembly: Dependency (typeof (SQLite_Android))]// ...public class SQLite_Android : ISQLite {public SQLite_Android () {}public SQLite.SQLiteConnection GetConnection () { var sqliteFilename = "TodoSQLite.db3"; string documentsPath = System.Environment.GetFolderPath (System.Environment.SpecialFolder.Personal); // Documents folder var path = Path.Combine(documentsPath, sqliteFilename); // Create the connection var conn = new SQLite.SQLiteConnection(path); // Return the database connection return conn;}}
After adding those files you can initialize the Datastore with the SQLiteConnection in your Xamarin.Forms project, for example in the class that inherits from the Application class.
var conn = DependencyService.Get<ISQLite> ().GetConnection();Datastore.InitOfflineHandler( conn );
From now on, all methods provided by the SDK, including accessing, modifying and saving your models are available within your platform specific project(s) as well as the PCL, which is also going to host your platform independent Xamarin.Forms code. Also have a look at our C# SDK documentation, where the usage of the C# / Xamarin SDK is described in detail.