Creating Your First Tizen .NET Application

The Tizen .NET framework allows you to efficiently and easily create beautiful applications for Tizen. A great way to experience this yourself is to follow the steps to your first Tizen .NET application. If you have to set up your development environment, please go to set up the development environment.

To get started,

After completing the above steps, you will have created your first application, and you can move on to Enhancing your application.

Creating a Project

To build a Tizen .NET application, you must follow these general steps:

  1. Create a project.
  2. Design the user interface for the application.
  3. Write code to implement the logic of the application.
  4. Build and deploy the application.

You can perform all of these steps in the IDE. The Tizen .NET preview works in Microsoft's Visual Studio (2015). After making sure the development environment is properly set up, you can create a new Tizen .NET project:

  1. Launch Visual Studio.
  2. To create a new project, select File > New > Project.

    Create a new project

  3. In the New Project window, select Tizen in the Templates tree on the left, and select Blank App (Tizen Xamarin.Forms Portable). Visual Studio defines a name, location and solution name for you, but you can modify the values: at least set the name to something meaningful.

    Select a template

    Once you are happy with the name and location, click OK.

Tizen Project Wizard window is shown as next step. You can define the package name and define which profiles are added in your solution. Click OK If you select Common profile, Mobile and TV profile cannot be selected.

A solution with 2 or 3 projects is created:

  • One project is named <projectname> (Portable) and contains the Xamarin.Forms code, which can be shared across platforms.
  • If you selected the common profile in the Tizen Project Wizard, a common project is added with <projectname>.Tizen suffix and contains the code to instantiate your common application within the Tizen framework.
  • If you selected the mobile profile in the Tizen Project Wizard, a mobile project is added with <projectname>.TizenMobile suffix and contains the code to instantiate your mobile application within the Tizen framework.
  • If you selected the TV profile in the Tizen Project Wizard, a TV project is added with <projectname>.TizenTV suffix and contains the code to instantiate your TV application within the Tizen framework.

If you are already familiar with Xamarin.Forms, this project has exactly the same structure as a Xamarin.Forms portable application, with the "Portable" project being the portable class library and the others being the platform-specific projects; however, for the Tizen .NET preview, only the Tizen platform-specific project is generated.

The .cs file in the portable project already contains simple Xamarin.Forms code, which makes a basic UI. Therefore, you can now build and run your application.

When you are done running your first application, you can enhance it further by reading a brief overview of what the code generated by the template is doing, and learning about a few more concepts to add to your application appeal.

Adding a Class Library and Restoring NuGet Manually

To add a class library and restore NuGet manually:

  1. If you add a Class Library (Tizen) in Visual Studio, the editing window shows red wavy lines.

    Red wavy lines

  2. Right-click the solution item in the Solution Explorer view and click Restore NuGet Packages.

    Restore NuGet packages

    Wait for the NuGet restoring to complete. Click the ClassLibrary project, and then click Refresh when the Refresh button appears.

    Refresh

  3. The .NETStandard.Library shows up and the code looks clean.

    .NETStandard.Library

The following figure shows warning messages that you can see in the Error List window when building the project. These can occur because the application is based on the Microsoft.NETCore.App and the Class library is based on NETStandard.Library, and the difference makes Visual Studio 2015 or 2017 show a warning. However, it is OK to run the project, because the Microsoft.NETCore.App includes the NETStandard.Library set.

Figure: Warning messages

Warning messages

 

Adding a Tizen Project to an Existing Xamarin Cross Platform Project

The Xamarin cross platform template consist of a shared PCL (Portable Class Library) and multiple platform dependent application projects for IOS and Android.

To add a new Tizen project:

  1. In the Visual Studio menu, go to File > New > Project to open the New Project dialog.
  2. Select Cross-Platform and Blank App (Xamarin.Forms Portable).

  3. Right-click the solution item in the Solution Explorer view and click Add > New Project.
  4. Select Tizen Blank App (Tizen Xamarin.Forms Portable) and click OK.

  5. Select the Tizen application’s package name and profile in the Tizen project wizard.

  6. The Solution Explorer shows the 2 Tizen projects are added in your existing Xamarin.Forms solution. The Tizen project is set as a startup project.

NoteSince the Tizen projects have dependencies with the Xamarin.Forms NuGet package version, you need to install the Xamarin.Forms NuGet package that has the same version as Xamarin.Forms.Platform.Tizen. Mismatching NuGet versions can cause build or packaging problems. To install the proper Xamarin.Forms NuGet package, right-click the solution item in the Solution Explorer view and select Manage NuGet Packages for Solution.

Figure: Mismatched NuGet version warning

 

Figure: Installing the correct NuGet package

Building and Running Your Application

When you have created your first project, you can build and run it:

  1. Register an author certificate.
  2. Build the solution.
  3. Deploy the application to a target.
  4. Run the application.

1 Registering an Author Certificate

If you already have registered a certificate in Visual Studio or can use a default Tizen certificate, you can skip this step.

After installing the Visual Studio plugin, and before making Tizen package, it is useful to set up a signing certificate.

You have 3 options:

  • Use a default Tizen certificate

    If you do not need to upload your application to Tizen Application store, you can use a default certificate and deploy your application in the Tizen Emulator too. You can check this in Menu > Tools > Options > Tizen > Certification. If you do not check the Sign the .tpk  file using the following option box, your application is made with a default certificate.

    Figure: Tizen default certificate registration

  • Use a Tizen certificate profile

    If you have used Tizen Studio and have already generated a certificate profile using the Tizen Certificate Manager (Menu > Tools > Tizen > Tizen Certificate Manager, the usage is added in tools menu too), the profile information can be read in %ToolPath/Tizen/SDK/user-data/profile.

    Figure: Tizen certificate profile registration

  • Use your own certificates.

    If you already have author and distributor certificates, you can import them in Menu > Tools > Options > Tizen > Certification.

    Figure: Tizen certificates registration

 

2 Building the Solution

To build the solution, go to Build > Build Solution in the main Visual Studio menu (you can also right-click the solution title in the Solution Explorer window and select Build). If the build process works all the way through to the end, the final part of the build output window shows something similar to the following figure - indicating that a .tpk package was built.

Figure: Building process output

Tizen .NET applications are always deployed as installed packages. The package files take the .tpk suffix, and the package generation is controlled by the manifest file. The Visual Studio template generates a package manifest, which is named tizen-manifest.xml and placed at the top level of the .Tizen project. The default manifest is sufficient to build these example applications without modification. If you need to make any changes, such as changing the icon displayed when the application is installed (it defaults to the Tizen logo), or installing resources that are used by the application at runtime, see Packaging Your Tizen .NET Application.

3 Deploying the Application

To run the application, you must first deploy it to the target: either a device or an emulator. Deploying means transfering the .tpk (package file) to the target and invoking the Tizen package manager to install it; this usually happens in a single command.

To deploy to a target:

  1. The target can be a development device (connected to a USB port), or the Tizen emulator. Launch the emulator from the Visual Studio menu by going to Menu > Tools > Tizen > Tizen Emulator Manager.

  2. You can create emulators as shown above by clicking Create. For more information on creating emulator instances, see Emulator Manager.
  3. The emulator launches after a small delay. When it is up and running, the display inside Visual Studio changes a bit, and the green debug button updates to show the running emulator.

Communication with the device happens through the SDB program (Smart Development Bridge). Visual Studio uses this program behind the scenes, so you normally do not have to use it directly, but in case there are problems, you can run the SDB manually to check that it actually finds the device.
To check the SDB, click Menu > Tools > Tizen > Tizen Sdb Command Prompt, and type sdb devices.

The following figure shows an example of a successful emulator detection.

Figure: Emulator detection

Emulator detection

If you want to change the target to be deployed, you can change it in the Visual Studio configuration manager as shown in the following figure. After selecting the right target in the combo box, go to debugging or start without debugging.

Figure: Emulator list

4 Running the Application

After the deployment, you can launch the application. If the deployment was successful, the application icon is visible on the device screen. Click the icon to launch the application. The following figure shows the launched application (as seen on the emulator).

Figure: Application running on the mobile emulator

Application running

Figure: Application running on the TV emulator

If the deployment had problems, try to use the SDB to install the application:

$ sdb install <path-to-package>/XamarinApplication1.TizenMobile.tpk 

or

$ sdb install <path-to-package>/XamarinApplication1.TizenTV.tpk 

If the installation succeeds, the application icon shows up on the emulator or device screen, and you can click it to launch the application.

Enhancing Your Tizen .NET Application

The C# code from your first application displays a label centered on the screen, containing the Welcome to Xamarin Forms! text. The Hello application (created from the template) is set up and ready to be built and run by Visual Studio right after you create it, as shown in the preceding sections of this topic.

Xamarin.Forms provides a way to build portable applications which run in a native way: it provides a set of controls to help build a user interface, as well as generating code which adapts the user interface code to use the native facilities of the supported platforms. The following information just scratches the surface of these controls, but it is enough to give you an idea of how to build on the initial application.

The following example shows the portable code portion of the Tizen Xamarin.Forms Portable project XamarinApplication1.cs file, generated by the template:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Xamarin.Forms;
 
namespace XamarinApplication1
{
    public class App : Application
    {
        public App()
        {
            // Root page of your application
            MainPage = new ContentPage
            {
                Content = new StackLayout
                {
                    VerticalOptions = LayoutOptions.Center,
                    Children = {
                        new Label {
                            HorizontalTextAlignment = TextAlignment.Center,
                            Text = "Welcome to Xamarin Forms!"
                        }
                    }
                }
            };
        }
        protected override void OnStart()
        {
            // Handle when your app starts
        }
        protected override void OnSleep()
        {
            // Handle when your app sleeps
        }
        protected override void OnResume()
        {
            // Handle when your app resumes
        }
    }
}

 

The Xamarin.Forms controls used to create the user interface of a Tizen .NET application can be roughly categorized into 4 groups:

  • Pages represent screens within an application. The UI of an application is built from one or more pages and with a navigation mechanism, if needed. The navigation scheme is specified by the INavigation interface. Many pages are of the ContentPage type, which describes the view of a single screen.
  • Layouts are containers used to compose views into logical structures. Some available types are absolute, grid, relative, and stack layouts; each provide mechanisms, such as orientation, spacing, and padding, to control the layout. The StackLayout class is a basic layout where you just stack controls on top of one another (or side-by-side). Layouts can be bundled and nested in each other.
  • Views are the controls displayed on the user interface, such as labels, buttons, and text entry boxes.
  • Cells are specialized elements used for items in tables and lists, which help describe how the items must be rendered.

You can read all about how Xamarin.Forms works at the Xamarin Developer Center. In addition, there is a comprehensive book about Xamarin.Forms from Microsoft Press, which is available as a free download. This topic does not duplicate the definitive documentation, only introduces the controls in use in the example above, and a bit more.

The Xamarin.Forms controls in play in this application:

  1. The App class is declared, deriving from the Application class, which is the Xamarin.Forms class that represents a cross-platform mobile application.
  2. The App class constructor creates a ContentPage instance (line 14) where you set up the view to display.
  3. You assign what you want to display to the Content property of that class.

    In this case, the content is a container, specifically a StackLayout instance (line 16). This is just a layout that positions its child elements in a single vertical (by default) or horizontal line - thus the name: the elements are "stacked" on top of one another.

  4. You set up the child elements by adding to the Children property (line 19) - in this case just a single Label instance (line 20), whose Text property you set to the message you want to display.
  5. Some lines (18 and 21) implement some control over the layout.
  6. Besides the App constructor, the rest of the file is just boilerplate - event handlers from the Application class that can be filled in if the application needs code to handle application state changes.

That is a very brief view without any real details; the Xamarin.Forms documentation goes into much more detail on each of the classes, interfaces, properties, and attributes involved and is a good place to do further research.

The code does not show the instantiation of the App class. Since application launching is platform-specific, the launching part, including the instatiation of the App class and the declaration of the Main() method (required as the entry point of every C# program), happens in the .Tizen project, in the matching file there. For example, if the file you are looking at in the portable project is named XamarinApplication1.TizenMobile.cs or  XamarinApplication1.TizenTV.cs, the platform-specific file is XamarinApplication1.TizenMobile.cs or   XamarinApplication1.TizenTV.cs  in the .Tizen project. For an application like this one, which just uses Xamarin.Forms controls, the generated code at the .Tizen part of the project contains everything needed, and you do not need to make any modifications. The following example shows the content of the XamarinApplication1.TizenMobile.cs or  XamarinApplication1.TizenTV.cs file:

using System;
 
namespace XamarinApplication1.TizenMobile
{
    class Program : global::Xamarin.Forms.Platform.TizenMobile.FormsApplication
    {
        protected override void OnCreate()
        {
            base.OnCreate();
            LoadApplication(new App());
        }
        static void Main(string[] args)
        {
            var app = new Program();
            global::Xamarin.Forms.Platform.Tizen.Forms.Init(app);
            app.Run(args);
        }
    }
}

Defining a Button

The basic template uses a label, which displays text in an area of the screen. The properties inherited from the base classes of Label give lots of control over the display: font attributes, families, and sizes as well as layout options. A button control is relatively similar, but is specifically designed to react to click events. As a result, the Button class defines an event called Clicked, which tells the application what to do when the click event takes place. To instantiate a generic button:

Button button = new Button
{
    Text = "Click here!"
};
button.Clicked += OnButtonClicked;

The above example adds the OnButtonClicked method to the button's Clicked event, and you need to define that method. When an event triggers, 2 parameters are delivered to any handler set up to watch it. The first parameter is an object representing the control that triggered the event and the second parameter is the event data appropriate to the event type:

void OnButtonClicked(object sender, EventArgs e)
{
    // Do something with the click event
}

Adding a Label to be Updated When the Button is Clicked

To build the modified application, create a new project. The default name for the second project is XamarinApplication2 (as shown in the namespace declaration in the following code example), but of course you can name it anything you want.

In order to do something visible on the screen to show that you actually got the click event, define another label. Give the label a value (by setting the Text property) to be displayed in the initial state, and have the event handler update the Text property (and color) once the click event triggers:

  1. Since the the click event triggers outside the class constructor, you must declare the label and a click counter up at the class level (lines 11-12).
  2. The button is instantiated (line 16) as is the new label (line 23): these 2 are then included as children of the StackLayout (lines 41-42), so they are stacked below the label from the initial program.
  3. In this example, the initial text of the first label is changed to "Welcome to Tizen!".
  4. The event handler is added (lines 47-52). In it, increment the click counter, build a string showing how many times the button has been clicked, and set the Text property of the label to that string. Just for visual effect, also set the color of the label to something different than the initial color (which was set at line 26).

The following example shows the modified code:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Xamarin.Forms;
 
namespace XamarinApplication2
{
    public class App : Application
    {
        Label label;
        int clicks = 0;
 
        public App()
        {
            Button button = new Button
            {
                Text = "Click here!",
                BackgroundColor = Color.Red,
                HorizontalOptions = LayoutOptions.Center,
            };
            button.Clicked += OnButtonClicked;
            label = new Label
            {
                Text = "unclicked",
                HorizontalOptions = LayoutOptions.Center,
            };
 
            // The root page of your application
            MainPage = new ContentPage
            {
                Content = new StackLayout
                {
                    VerticalOptions = LayoutOptions.Center,
                    Children = {
                        new Label {
                            HorizontalTextAlignment = TextAlignment.Center,
                            Text = "Welcome to Tizen!"
                        },
                        button,
                        label,
                    }
                }
            };
        }
        void OnButtonClicked(object s, EventArgs e)
        {
            clicks += 1;
            label.Text = String.Format("Number of clicks: {0}", clicks);
        }
        protected override void OnStart()
        {
            // Handle when your app starts
        }
        protected override void OnSleep()
        {
            // Handle when your app sleeps
        }
        protected override void OnResume()
        {
            // Handle when your app resumes
        }
    }


}

The following image shows what happens if you try out the modified code and run the application with it. At the startup, the button is red and the text below the button is unclicked. After a couple of clicks, the click counter is displayed below the button, and the button color has changed.

Figure: Enhanced application

Enhanced application 

Packaging Your Tizen .NET Application

This section gives a basic overview of packaging, to aid in understanding how to make simple changes. For more complex applications, see the packaging information in the Tizen documentation.

A Tizen .NET application is deployed in the form of an installable package, where the package file takes the suffix .tpk. A Tizen .NET package has a relatively simple structure: internally it is a zipfile with content that matches the directory layout of the project.

In the following figure, the layout of the platform specific (.Tizen) project is shown. It includes the libres, and shared (with a res subdirectory containing an image file) directories , and the tizen-manifest.xml file. There is also the bin directory, which Visual Studio only shows if you select the Show all files option for the solution. These pieces all go into the package.

Figure: Project layout

Project layout

Package generation (and in fact installation) is controlled by a package manifest file, which is named tizen-manifest.xml. The Visual Studio template generates a package manifest, and places it at the top of the directory tree of the .Tizen project. The following figure shows the .tpk file for the initial application, to illustrate how the combination of the directory layout and the package manifest leads to the actual package.

Figure: Package content

Package content

The initial points to learn here are:

  • The shared directory is for items that are considered systemwide (shareable). The application icon is packaged in shared/res: on installation, the icon appears on the home screen with the icons for the other applications. You can either replace the icon (which is just a copy of the default Tizen logo) with one of your own using the file name generated by Visual Studio, or put a new icon in the same project directory and update the package manifest to indicate the new name.
  • The res directory is for application-private resources. If the application needs a file to open at runtime, it can be placed here.
  • The bin directory contains the generated application executable.
  • The lib directory contains the generated application support code.
     If you use nugget libraries, they are imported in the lib directory.
  • The package manifest is included in the package, as it is used at the installation time.
  • 2 signature files (author and distributor) are included, as they are checked at the installation time.

Other information relating to packaging includes declarations of features and privileges, and the placement of language-specific files.