Developer

Accessing Windows Store and Windows Desktop Application Settings

Use the ApplicationSettings property of the LogonCore instance to access application settings.

  • The application developer cannot instantiate the ApplicationSettings class directly, it is instantiated by the LogonCore component.
  • An instance of this class is available via a LogonCore instance, only if the device is registered with the LogonCore component.
The ApplicationSettings class implements the IReadOnlyDictionary interface (or the equivalent interface/class on other platforms). This allows the application developer to:
  • Iterate through all the stored settings.
  • Use setting names to retrieve setting values.
The ApplicationSettings class guarantees that if an ApplicationSettings instance is available, it is in a consistent and valid state; the values this class stores are validated against a metadata document.
The application developer cannot modify the application settings directly, which is guaranteed by:
  • Implementing the IReadOnlyDictionary interface that provides read-only access to the settings container (new values cannot be added to the settings).
  • Storing values that implement the IReadOnlyProperty interface, which provides read-only access to the individual setting values.

Downloading Application Settings Method

This method:
  • Asynchronously downloads the application settings and metadata of the settings structure from mobile service for development and operations or SAP Mobile Platform Server.
  • Validates the downloaded settings against the newly downloaded metadata and persists the new settings and metadata.
  • Always succeeds and never sends a request if the LogonCore is used with Gateway.
  • .NET version
    Task DownloadSettingsAsync()
  • Windows Runtime version:
    IAsyncAction DownloadSettingsAsync()
Error Handling:
  • An HttpRequestException is thrown in case of a networking error, or if the server can be reached, but the response status code is not in the "success" range (200-299).
  • An ApplicationSettingsException is thrown if the downloaded metadata is invalid or if the downloaded settings payload does not match the defined metadata. The application developer should catch the generic exception (Exception) and check whether the exception implements the IApplicationSettingsException interface. Exception classes are not Windows Runtime types, so they cannot be exported when the library type is WinMD.

    To keep the API aligned across all Windows platforms, error-handling also applies to the .NET version of the library, so that the application developer who uses this component can target the .NET (desktop), tablet (Windows 8.1), and Windows Phone 8.1 (WinRT runtime) platforms with identical code.

Updating Writable Application Settings on the Server

This method:
  • Returns the copy of the writable application setting values in a non-mutable dictionary.
  • Guarantees that the application developer cannot edit the application settings directly; the settings stay consistent and valid on the client. However, the application developer can get the mutable version of the settings that are writable, so some or all of those values can be updated on the server.
  • Since properties (objects that store individual settings) cannot be instantiated by application developers, use this method to get access to the writable properties.
  • Only copies of the writable setting values are returned, guaranteeing that modification of the copied properties are not reflected in the stored application settings on the client.
  • Windows .NET and the Windows Runtime version:
    IReadOnlyDictionary<string, IProperty> GetWritableSettings()

The writable values are modified on the client in the ApplicationSettings instance only if the modified values are sent to the server, and the server confirms that these values have been updated on the server side. This prevents the application settings from being overwritten on the client.

Send the Modified Writable Settings to the Server Method

This method:
  • Sends the modified writable settings to mobile service for development and operations or SAP Mobile Platform Server to asynchronously update server-side settings.
  • Requires the application developer to call the GetWritableSettings method, prior to calling this method, to access the writable properties that hold individual setting values.
  • Does not send requests to the server and always fails, stating that there are no modifications to the settings, if the LogonCore is used with Gateway.
This method ensures that:
  • Only the modified properties are sent to the server.
  • If updating the writable settings fails, then the application settings remain valid and consistent on the client.
  • After successfully updating the writable settings on the server, the settings are downloaded again to ensure that the application settings on the client are in sync with the settings stored on the server. This is necessary since the server might not accept all the values, but still reports success, or modification to one of the property values implies another requires change. Another example: there are nullable boolean values, but sending null in these values results in the server changing these null values to false.
  • .NET version:
    Task UpdateSettingsAsync(IReadOnlyDictionary<string, IProperty> settingsToUpdate)
  • Windows Runtime version:
    IAsyncAction UpdateSettingsAsync(IReadOnlyDictionary<string, IProperty> settingsToUpdate)
Error Handling:
  • An HttpRequestException is thrown in case of a networking error, or if the server can be reached, but the response status code is not in the "success" range (200-299).
  • An ApplicationSettingsException is thrown if the downloaded metadata is invalid or if the downloaded settings payload does not match the defined metadata. The application developer should catch the generic exception (Exception) and check whether the exception implements the IApplicationSettingsException interface. Exception classes are not Windows Runtime types, so they cannot be exported when the library type is WinMD.

    To keep the API aligned across all Windows platforms, error-handling also applies to the .NET version of the library, so that the application developer who uses this component can target the .NET (desktop), tablet (Windows 8.1), and Windows Phone 8.1 (WinRT runtime) platforms with identical code.

Updating Device Information on the Server

Although device information such as model type, subtype, and phone number can be updated by calling the GetWritableSettings method, modifying the relevant properties then calling the UpdateSettingsAsync method, a helper method that supports this particular scenario has been added to the API. This (helper) method offers these benefits to the application developer:
  • No need to call the GetWritableSettings method.
  • No need to know the application setting names that belong to the device settings group.
  • Can use dedicated properties of a class (DeviceInfo) instead of defining device specific settings. The method updates the device settings asynchronously on mobile service for development and operations or SAP Mobile Platform Server, and fails if called when using a Gateway connection.

The method accepts a DeviceInfo class instance.


The method should consider only those properties of the DeviceInfo class that have been modified by the application developer, which prevents device information which contain null values on the server that have not been modified by the application developer from being updated.
  • .NET version:
    Task UpdateDeviceInfoAsync(DeviceInfo deviceInfo)
  • Windows Runtime version:
    IAsyncAction UpdateDeviceInfoAsync(DeviceInfo deviceInfo)
Error Handling:
  • An HttpRequestException is thrown in case of a networking error, or if the server can be reached, but the response status code is not in the "success" range (200-299).
  • An ApplicationSettingsException is thrown if the downloaded metadata is invalid or if the downloaded settings payload does not match the defined metadata. The application developer should catch the generic exception (Exception) and check whether the exception implements the IApplicationSettingsException interface. Exception classes are not Windows Runtime types, so they cannot be exported when the library type is WinMD.

    To keep the API aligned across all Windows platforms, error-handling also applies to the .NET version of the library, so that the application developer who uses this component can target the .NET (desktop), tablet (Windows 8.1), and Windows Phone 8.1 (WinRT runtime) platforms with identical code.

Application Connection ID Property

This property:
  • Always returns null if a Gateway connection is used or if the device is not registered
  • Returns the application connection ID from the settings that can normally be found under the "ApplicationConnectionId" key, if the device is registered on mobile service for development and operations or SAP Mobile Platform Server
  • Is read-only
  • Windows:
    // Retrieving the application connection id as a string from the ApplicationSettings component of the Logon Core instance
    string connectionId = logonCore.ApplicationSettings.ApplicationConnectionId);
    … // use the connection id
    
    // updating some of the writable settings the generic way.
    // Note: this is only possible if the device is registered with mobile service for development and operations or SAP Mobile Platform Server.
    //       When Gateway connection is used there are no writable settings available, that is why we need the check below.
    var writableSettings = logonCore.ApplicationSettings.GetWritableSettings();
    if (!logonCore.State.IsGatewayConnectionUsed) {
          writableSettings["DeviceModel"].Value = "Lenovo";
          writableSettings["DeviceSubType"].Value = "x64";
          writableSettings["WnsPushEnable"].Value = true;
          await logonCore.ApplicationSettings.UpdateSettingsAsync(writableSettings);
    
          // Here we update device information settings using the specialized helper method.
          await logonCore.ApplicationSettings.UpdateDeviceInfoAsync(new SAP.Logon.Core.Settings.DeviceInfo() {
                Model = "Lenovo T530",
                SubType = "x64"
          });
          
          // Reading an application setting that has no dedicated property in the ApplicationSettings component.
          var deviceModel = logonCore.ApplicationSettings["DeviceModel"].Value;
    }
    

Obtaining the Application Endpoint URL

This property:
  • Returns null if the device is not registered
  • Returns the URL to the service document if a Gateway connection is used
  • Returns the proxy URL, which can be used to download the service document, if the device is registered on mobile service for development and operations or SAP Mobile Platform Server
  • Is read-only
  • Windows:
    Uri ApplicationEndpointUrl { get; }

DataVault Password Policy Property

This property returns the password policy returned by mobile service for development and operations or SAP Mobile Platform Server. If the server does not provide one, the component returns the default policy.

  • Windows
    DataVaultPasswordPolicy PasswordPolicy { get; }

IReadOnlyProperty

  • The interface inherits from the IMetaProperty interface. A class that implements this interface must be constructed using a class that implements the IMetaProperty interface; properties can be created only from metadata and a value. This ensures that no ad hoc properties are created internally at runtime and that if a property is created it holds a valid value. No instances can be created that are in an inconsistent state (by holding a value that does not match the metadata restrictions defined in the metaproperty instance).
  • The interface extends the IMetaProperty interface with one Value property that holds a valid value that was validated against the metadata at construction time. After constructing the property its value and its metadata cannot be changed.
  • The application developer can access only IReadOnlyProperty instances when accessing the application settings. This ensures that application settings are not overwritten on the client side by the application developer.
Properties of this interface:
  • IsNullable Indicates whether the value of a property can be null or not. For details, see the OData specification
    • Windows:
      bool IsNullable { get; }
  • Name Represents the name of one application setting. For details about restrictions and rules on naming an OData property see the OData specification. It is a read-only property:
    • Windows:
      string Name { get; }
  • Type Represents the type of the value of the property. The PropertyType type is an enumeration that defines the following constants as enum values: String, Boolean, Byte, Int8, Int16, Int32, Int64, Double, Single and Complex. An application developer can use this information to cast the generic "object" type of the "Value" property to get the typed value of a setting. When a property is a complex property (in OData terms) this "Type" property (in programming language terms) is set to Complex and the type name of the complex property is saved in the TypeName property. An application developer should check the Type and the CollectionKind properties to safely cast a property (app setting) value to a type supported by the programming language. If the CollectionKind property is set to the Collection enum value, then the value of the setting property is a read-only list of either a primitive (string, bool, int32 and so on) or a complex type. The PropertyType enumeration value might be extended by further primitive types (such as DateTime) if needed.
    • Windows:
      PropertyType Type { get; }
  • TypeName This property holds the OData name of the type of the property. The value is never null and is read-only.
    • Windows:
      string TypeName {get;}

Obtaining the Latest mobile service for development and operations Version

To support the latest mobile service for development and operations version and features of the version 4 registration service, the UserName property returns a string from mobile service for development and operations.

Information about the userName property can be found in the ApplicationSettings section of the Logon API documentation.

IProperty

  • The class that implements this interface can be instantiated only internally by the application settings component, and the class grants write access to the setting that is stored locally. An application developer can get instances of the class that implement this interface only by calling the GetWritableSettings method. If the application developer has a reference to an instance of a class that implements this interface, the ApplicationSettings component guarantees that the Value property contains a copy of the application setting value of the original property. This means that even if the property value is set by the application developer the value is not reflected in the ApplicationSettings component thus guaranteeing a consistent and valid state of settings.
  • To modify a writable setting, the application developer must pass the read-only dictionary of <string, IProperty> instance retrieved by calling the GetWritableSettings method to the UpdateSettingsAsync method.
  • If an invalid value is set (a value that does not fulfill the metadata restriction for the given property) an exception is thrown.