Show TOC

SAP Business Application Wizard for Developing Managed Windows Apps with Visual StudioLocate this document in the navigation structure

(Windows) Use the SAP Business Application wizard to facilitate implementation of the application's technical tasks, which allows the application developer to focus on implementing the business logic of the application.

Purpose
Developers using the SAP Mobile Platform SDK must perform the same technical tasks for every application before accessing back-end services and implementing the application's business logic. These tasks include, but are not limited to:
  • Registering the device on SAP Mobile Platform Server or SAP HANA Cloud Platform mobile services
  • Configuring logging and tracing
  • Setting the app up to access a back-end service
  • Adding references to various SAP and third party libraries
The application developer can streamline this process by using the SAP Business Application project template and associated wizard to generate C# skeleton applications for various Windows runtimes that in turn:
  • Contain code that performs these technical tasks in a manner recommended by SAP
  • Include the correct references to the required SAP and non-SAP libraries (for example the Microsoft OData library)
  • Set the necessary capabilities in the application manifest file
Note The project template focuses on the most common use cases, but does not include all SAP Mobile Platform SDK features. For example the features of the Usage component are not included, and a limited set of features are used by the template from the CertificateProvider and ODataOnline libraries.
System and Development Environment Requirements
  • Supported development environments
    • Visual Studio 2013 with Update 3 or higher, minimum Community Edition or greater
      Note While it may be possible to install the project template and the wizard on systems that run the RTM, Update 1 and Update 2 versions of Visual Studio 2013, such configurations are not supported and have not been tested.
    • Visual Studio 2015 RTM or higher, minimum Community Edition or greater
  • Operating system requirements
    • Client OS - minimum Windows Vista SP2 or higher
    • Server OS - minimum Windows Server 2008 SP2 or higher (excluding the Server Core version)
  • NuGet package manager At minimum, version 2.6 is required to set up the SAP Mobile Platform SDK package source for the available Visual Studio installation. If you use a lower version, the generated projects do not compile as the necessary SAP packages are not restored by the package manager.
Features
  • Supported platforms and project types/runtimes options The SAP Business Application C# project template supports these Windows runtimes:
    • .NET 4.5.x using WPF for the UI
    • Windows Store Apps targeting Windows 8.1 and Windows Phone 8.1.x using the "Windows Runtime" runtime
    • Windows 10 Universal Windows Platform (UWP) apps targeting Windows 10 and Windows 10 Mobile (Windows 10 Mobile support is preliminary as the final Windows 10 Mobile OS is not available at the time of the SP10 release)
    Restriction The platforms you can select from vary depending on the developer machine installation. For example:
    • The Windows 10 UWP platform is not available to users who have Visual Studio 2013, which does not support UWP projects
    • If you are using Visual Studio 2015 and Windows 8.1 and Windows Phone 8.0/8.1 Tools is not installed, the Windows 8.1 and Windows Phone 8.1 platforms are unavailable, since Visual Studio does not recognize projects targeting those platforms
    • If you are using Windows 7 for development, only the .NET platform is available, regardless of the Visual Studio version you are using
  • Onboarding options Onboarding is registering the user's device on SAP Mobile Platform Server or SAP HANA Cloud Platform mobile services. After successfully onboarding, the application is able to access the back-end service that is associated with its application ID.
    You can use the wizard to configure:
    • Application ID - determines which SAP service the application can access via SAP Mobile Platform Server or SAP HANA Cloud Platform mobile services.
    • MobilePlace configuration service to obtain onboarding information - offers a screen to the user where an email address can be entered. This email address and the application ID are sent to a service that stores onboarding configurations (such as host, port, UI configuration, and so on). Based on the email address, input fields are populated automatically. If the onboarding component receives all the information required from the MobilePlace service, onboarding starts automatically. If not, only the missing information, for example, credentials, must be entered by the user. Optionally you can configure the MobilePlace subscreen to prefill the email input field with an email suffix, for example "@sap.com" so the user only needs to enter the local part of the email.

      The application version must be sent to MobilePlace so it can find a matching configuration for the application ID and the email address. The default value is "1.0" and this value cannot be edited in the UI of the generated application. The developer can change the version number after the skeleton app has been generated.

      The MobilePlace service is particularly useful for in-house applications.

    • Offer demo mode - allows the application to be tested without a back-end connection, so the user can become familiar with the application before accessing real data. If this option is enabled, the onboarding component provides a new screen where the application can be started in demo mode. The wizard only generates code for the technical part of the demo mode.

      To customize demo mode:

      If "Offer demo mode" is used together with "Generate code that is necessary to start using the SAP service associated with the application ID you entered", the wizard will generate a data provider which returns sample data without using a network connection. This provider is located in the DemoModeHandler.cs file. When the application is in demo mode, HTTP requests are intercepted and processed by the code located in the previously mentioned file, which returns built-in data to the application. The application developer needs to replace the offline data returned by the demo mode handler code to align with the needs of the developed application (for example to return Business Contacts if needed instead of product information). The DemoModeHandler.cs file contains further information in comments about how to change or enhance the code depending on the app developer's needs. Demo mode can be implemented in various ways, but using this provider ensures that there is no need to change the application logic; the application does not have to execute separate code lines when in demo or normal mode.

    • Default values of the onboarding form - decide what kind of input fields the onboarding component should show and what the default values for those fields should be. For example, if the application developer knows that the application does not use basic authentication or direct gateway connections, then hide those input fields on the onboarding screen.

      To hide a field, deselect the box next to the field identifier. The fields corresponding to the previous example are: User Name, Password and Gateway Client.

    Remember You can use the SDK to directly connect to a Gateway system and fetch data without onboarding a device. However, this option should generally be used only during a proof-of-concept phase of application development and only if the app is connected to an intranet server. Further along the development process, the onboarding process is necessary. Therefore, skeleton applications always use the onboarding (Logon) components (FlowEngine, MobilePlace and LogonCore). The skeleton application uses the standard SAP onboarding UI component to interact with the user; however developers can replace the onboarding UI component and implement their own onboarding flow if necessary using the LogonCore component.
  • Logging and tracing options An application may need to log certain application activities, states, or trace HTTP requests to help diagnose certain error conditions during application usage. The application developer can use the SAP provided components for this purpose by selecting one or more options in the Logging and Tracing section of the wizard:
    • Add code to the project that can be used to upload logs and HTTP traces - generates higher level APIs that the application developer can call to upload logs or HTTP traces. The generated code aggregates certain APIs from the Supportability and SupportabilityUploader libraries, takes care of administrative steps and state changes of certain objects (for example saving the tracing and logging settings of the HTTP client used for uploading data, disabling tracing and logging on the HTTP client instance while uploading (ensuring data integrity) and after the uploading step it restores the HTTP client logging and tracing settings, and so on). This allows the developer to call a single method to upload logs and traces.
      Note
      • This option generates the uploader methods that can be considered high level uploader APIs. However, if no other options are selected, the developer determines when and how uploading takes place; that is, whether uploading is automatic or triggered manually via a UI element by the user, or, whether UI feedback (for example a progress bar) is presented to the user during data upload. This option requires some coding to call these generated APIs. The application developer can also add options to display logs or email them from the onboarding screen if needed.
      • If Add code to the project that sets up logging and HTTP tracing is disabled, the developer must initialize logging (create loggers, set the log destinations, and so on) and tracing components (to start tracing HTTP requests, setup transactions, and so on). Without setting up the logging and/or tracing component uploading logs and/or HTTP traces fail since there is nothing to upload.
    • Generate application code that uploads logs and HTTP traces - can be enabled only if Add code to the project that can be used to upload logs and HTTP traces is enabled. This option generates application code that calls the uploader methods and provides a platform-specific UI that shows upload progress to the user. The user can also cancel the uploading of logs and HTTP traces. The wizard generates a platform-specific UI that allows the user to manually trigger the upload process. The upload trigger varies by platform:
      • .NET desktop application: trigger the log/trace upload via menus
      • Windows 8.1 apps: trigger the log/trace upload via the Settings Charm bar
      • Windows Phone 8.1 apps: trigger the log/trace upload on the Settings page
      • Windows 10 application: trigger the log/trace upload via the Hamburger menu then tapping the Settings button
      The application developer can change or replace these UI elements. For example, instead of menus in the .NET application, the developer show a new modal dialog and provide buttons to trigger uploading of logs and traces. The developer can also change the wizard-provided UI that shows uploading progress and allows the user to cancel uploading logs and HTTP traces.
      Note If Add code to the project that sets up logging and HTTP tracing is disabled, the developer must initialize logging (create loggers, set the log destinations, and so on) and tracing components (to start tracing HTTP requests, setup transactions, and so on). Without setting up the logging and/or tracing component uploading logs and/or HTTP traces fail since there is nothing to upload.
    • Add code to the project that sets up logging and HTTP tracing - generates application code that sets up the logging and tracing component when the application starts. The generated code creates a new instance of a logger that has the same name as the project and also starts a new "transaction". HTTP traces are collected in a "transaction" structure. The wizard also generates inactive code that includes a description that enables the developer to decide whether the code should be activated. For example, by default, HTTP traces are not collected; therefore, the code that enables the collection is inactive. The developer can simply enable or write the application logic that determines when to enable the code. The developer can also create additional loggers, change logging destinations, and rename or remove the generated logger.
  • Backend service access (Connected Services) options
    • Generate code that is necessary to start using the SAP service associated with the application ID you entered - generates a higher-level API that can be called by the application developer to start interacting with the back-end service and code to provide access to the fully set up OData store.
      Remember This option does not establish service access when starting the application, since the higher-level APIs are not called by the application. The application developer must decide when and how the generated APIs are called during runtime. The wizard generates code that sets up an OData store that uses the OData Online library. See the Note below for information about replacing the OData Online library in the skeleton application with a different one.
    • Generate sample service browser code - can be enabled only if Generate code that is necessary to start using the SAP service associated with the application ID you entered is already enabled. This option is recommended for application developers who are unfamiliar with the SAP Mobile Platform SDK OData API. When you enable this option, the wizard:
      1. Generates the application logic to call the higher-level generated APIs to set up the OData store at the appropriate time with UI feedback to the user.
      2. Generates a user control that displays the available entity sets of an OData service. The user can then pick an entity set to browse its entities.

        A user can select an entity to examine its properties. The code of the OData service browser is generated in a separate file as a user control, allowing for easy removal of the user control from the application by the developer when it is no longer needed. Since the OData service browser code is generated in a separate file, it is easy to become familiar with the OData API SAP provides as the code that interacts with the back-end service can be found in a single file that is separate from the rest of the application code.

        Tip The user control does not demonstrate all OData library features. It's only purpose is to familiarize developers new to the SAP OData library. For example, features such as editing, creating and deleting an entity, sending batch requests, invoking function imports and so on, are not available in the generated browser control.
      Note By default, the wizard generates code that uses the OData Online library. However, you can use other OData libraries that implement the SAP provided OData API (for example the Offline OData library, which requires Achitecture X86) in the application. To use another OData library:
      1. Use the NuGet package manager to uninstall the OData Online library from each project the solution contains.
      2. Add references to the OData library you want to use with the necessary dependencies, or, if that library comes as a NuGet package, install the package instead.
      3. Open the Globals.cs file and locate the OpenODataStoreAsync method. Follow the instructions described in the comment in that method to replace the OData Online implementation. The rest of the code can remain unchanged since it uses only the interfaces that are common to each OData library implementation.
      4. Repeat these steps for every project in the solution to replace the default OData library implementation.
    • Branding - generated applications use certain UI components from the SDK that are presented to the user (including the onboarding UI, lock UI, MobilePlace controls, and so on), that use a standard SAP look and feel which might not meet your organization's look and feel requirements. Enabling Generate the Styles.xaml file for each project generates a Styles.xaml file that contains all the styles used internally by SAP developed UI components. The developer can then edit this file to change the look and feel of these UI components to match the organization's standards.
Known Issues and Workarounds
  • Issue: After creating a solution in Visual Studio 2015, it does not compile if the solution contains a UWP project and one or more projects that targets other Windows runtimes. The output generates error messages similar to:"
    XamlCompiler error WMC1006: Cannot resolve Assembly or 
    Windows Metadata file 'System.Runtime.dll'" "Xaml Internal Error 
    error WMC9999: Type universe cannot resolve assembly: System.Runtime, 
    Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a."
    NuGet packages are restored only for project types other than the UWP project type after creating the solution.

    Solution: Select Rebuild Solution from the Build menu. This restores the NuGet packages for the UWP project and allows the solution to compile successfully. You must have an internet connection to succeed.

  • Issue: Compilation errors indicating the SAP namespace cannot be resolved, when using Visual Studio 2013. This is an indication that the SAP Mobile Platform SDK NuGet package source is set up incorrectly, which generally happens when the NuGet package manager is not updated for Visual Studio 2013 to at least version 2.6.
    Solution: Manually set up the NuGet package source:
    1. Select Start of the navigation path Tools Next navigation step NuGet Package Manager Next navigation step Package Manager Settings End of the navigation path.
    2. Add the package source and point to the location where the Windows SAP Mobile Platform SDK NuGet packages are unpacked. This location is set by the user in the installer of the SAP Mobile Platform SDK during installation.
    3. When the package source has been added and enabled in the Package Manager, go to the Build menu and choose Rebuild Solution. This adds packages to all projects in your solution and the solution compiles.