Design Details for MDM Self Service Portal

2/9/2009

This section describes how the MDM Self Service Portal application is designed and how to implement basic functions, such as logging. Understanding the application design and implementation for the portal can help you extend or change the functionality more extensively than by using simpler update methods to the appearance and behavior of the portal, such as changing the theme.

WebPage Base Class

All pages in MDM Self Service Portal derive from a common base class, the WebPage class. The WebPage class is located in the WebPage.cs file.

You use the WebPage class to detect when the browser updates a page and to initialize the correct ASP.NET culture. The WebPage class processes Language Bar selection by initializing CurrentThread to a culture-specific language. The Language Bar is a user control that lets users select the language in which to display the portal pages.

Master Page

All the pages in MDM Self Service Portal are contained within a master page. The master page consists of a header and footer with a placeholder area in between that displays the content for the current page.

The header on the master page contains a navigation bar with buttons. When a user chooses a button, the application displays pages that have different styles and creates a tab control effect.

There are three permanent buttons and one non-permanent button. The application uses the non-permanent button to display pages such as the Error page, the Pending Enrollment Details page, and the Enrolled Device Details page.

The footer on the master page contains the Language Bar control and several additional links.

Language Bar Control

The Language Bar control displays link controls for all languages for installed localized resources in the App_GlobalResources folder.

Because the Language Bar control is located on the master page, the control is visible on all pages of the MDM Self Service Portal Web site.

When a user selects a language link, the portal application sends a Get request for the current page that includes the selected language as a parameter. When the page displays on the server, the control uses the LanguageBar::Page_Load() method to set the language links to point to the current page.

The following shows a code example for the LanguageBar::Page_Load() method.

foreach(CultureInfo cultureInfo in cultures)
{
LinkButton linkBtn = new LinkButton();
linkBtn.Text = cultureInfo.NativeName;
linkBtn.PostBackUrl = this.Request.CurrentExecutionFilePath + "?lang=" + cultureInfo.Name;
this.Controls.Add(linkBtn);

delimitator = new Label();
delimitator.Text = "|";
this.Controls.Add(delimitator);
}

In the previous example, the PostBackUrl property is set to the current page by using this.Request.CurrentExecutionFilePath.

Because every page on the portal derives from the WebPage class, each page processes the passed language query string parameter by setting the language to the one that is selected. WebPage.InitializeCulture() processes the language query string.

Error Handling

MDM Self Service Portal logs errors by using the SelfServiceContext.AddError() method. This sets an error message into the session variable Session[SelfServiceContext.sessionErrorsKey].

Typically, after the error is logged, a transfer is made to the Error page, Server.Transfer(SelfServiceContext.errorPage) that displays the error message.

Confirm Dialog Box Control

MDM Self Service Portal displays the Confirm dialog box that prompts a user to confirm an action, such as canceling an enrollment request or wiping a device. The dialog box is a user control in ConfirmBox.ascx.

The portal implements the functionality for the Confirm dialog box by using a combination of server-side code and client-side code. The user control includes the following ASP.NET controls:

• An image
• A hidden field
• A panel that contains the page elements
• A label to display the dialog box
• A Confirm button
• A Cancel button

The dialog box appears as a rectangle on a semi-transparent background. The rectangle is the panel control, and the background is the image control that holds a semi-transparent image that stretches across the screen. The portal achieves this effect by using different z-index CSS settings for the panel and the image. For more information about these settings, see the .confirm_box and .confirm_backdrop sections in the .css file.

When a user chooses certain buttons on the page, the application calls a JScript.NET function to display and hide the Confirm dialog box.

In the Confirm dialog box, if a user chooses the Cancel button, usually labeled as No, the application calls a client-side event. The client-side event calls a JScript function to hide the box. If a user chooses the Confirm button, usually labeled Yes, the application calls a server-side event.

When the server receives the server-side event, the server reads the value of a hidden field. Typically, the application uses this hidden field value to pass the index of the row to the GridView for the user. The row index is set at the time that the application displays the page, as a parameter to the ShowConfirm JScript function.

The following code shows an example of how DeviceList.GridViewDevices_RowDataBound(): works by using the Confirm dialog box:

buttonDelete.OnClientClick = ConfirmBox.ClientClickShowConfirm(
e.Row.DataItemIndex.ToString(Thread.CurrentThread.CurrentCulture.NumberFormat),
prompt,
Resources.Resource.ConfirmDialogCancelPendingConfirm,
Resources.Resource.ConfirmDialogCancelPendingCancel
);

In the previous example, the Delete button in the GridView is associated with the client-side event handler, OnClientClick, and displays the Confirm dialog box. The first parameter for the function is the index of the row. Additional parameters are the message and the Confirm and Cancel button labels.

Logging Provider and Event Logging.

MDM Self Service Portal supports logging and tracing functionality by using the TextFileWebEventProvider class. This writes Web events to a text file. The TextFileWebEventProvider class uses the following configuration parameters in the Web.config file:

• LogFileName: The relative path and name of the text log file
• LogFileMaxSizeMb: The maximum size of an individual log file
• LogFilesMaxSizeMb: The maximum size of all log files

When a log file reaches the size designated by logFileMaxSizeMb, MDM Self Service Portal creates a new log file and renames the earlier log file. When the portal log files reach a cumulative size determined by logFilesMaxSizeMb, MDM Self Service Portal deletes the oldest log file.

The portal application class, LogUtil, exposes the following three methods to enable the portal to log traces, user activity, and events:

• LogTrace()
• LogActivity()
• LogEvent()

LogTrace() and LogActivity() methods log entries into the log text file that you configure TextFileWebEventProvider to use. Typically, you use LogTrace() to log code path execution points or error conditions. You can use LogActivity() to log application events or user operations such as enrollment requests, wipe requests, and canceled wipe requests.

LogEvent() logs events to a Windows-based operating system. The Windows Event Viewer displays these events and notifies an administrator of important conditions of the state of the portal. For example, the Windows Event Viewer can report that it cannot read a configuration file, or that a log file is approaching maximum size.

MDM Self Service Portal Configuration File

In addition to the Web.config file, MDM Self Service Portal includes a custom configuration file, SelfService.config, for application settings. SelfService.config is located in the App_Data folder. You can configure all the settings in SelfService.config by using the Portal Administrator page on the portal Web site.

By default, access to the Portal Administrator page is restricted to members of SCMDM2008ServerAdminstrators. MDM Self Service Portal enforces the restriction in two ways: by enforcing access control lists (ACLs) on the file, and by impersonating the logged in user at run-time to check user permission against the ACL on the file. The application uses the SelfServiceContext.IsAuthorizedConfigWrite() method to implement these restrictions.

At run-time, the application code deserializes the SelfService.config file and loads the file into memory as an object. The file must comply with an XML schema, SelfServiceConfiguration.xsd, so that the application code can serialize and deserialize the file. The application uses XmlSerializer serialization from or deserialization to C# when it converts between the XML file and the C# object. The C# object code generates at compile time from the schema by using the Xsd.exe tool in Visual Studio.

The following example shows the BeforeBuild code from the csproj file:

<Target Name="BeforeBuild">
    <Exec Command="&quot;$(VSINSTALLDIR)\SDK\v2.0\Bin\xsd.exe&quot;       SelfServiceConfiguration.xsd /c /l:cs /nologo /n:Microsoft.Mobile.ManagementServices.SelfServicePortal /o:Code" WorkingDirectory="$(ProjectDir)" />
    <!-- Include the C# file in the list of files to compile. -->
    <CreateItem Include="Code\SelfServiceConfiguration.cs">
      <Output TaskParameter="Include" ItemName="Compile" />
    </CreateItem>
  </Target>

As shown in the previous example, the input that Xsd.exe requires is a schema file, SelfServiceConfiguration.xsd. The output that Xsd.exe generates is the Code\SelfServiceConfiguration.cs file that represents the same object in C#. Because Xsd.exe relies on a schema file to generate the correct output, changes in the schema immediately reflect in the code. Any schema-valid XML file will parse correctly. However, if you change the schema so that it does not match the rules that the MDM Self Service Portal expects, the code file will change. In this scenario, you do not receive a run-time error, but MDM Self Service Portal will not build successfully.

The following describes the decision to use a design that requires a schema and uses XmlSerializer instead of using the appSettings configuration settings that are provided by ASP.Net:

• When you change the appSettings file, you must restart the application to view the changes. This extra step is required whether you make changes in the Web.config file or update settings by using the external file feature for Web.config. If you make changes by using the custom configuration handler for Web.config sections, the same limitation applies. By using the method described in this section, edits display immediately.
• All attributes and elements represent as strongly typed .Net objects. These objects enable the application to access the flat appSettings hash in memory directly without requiring the application to use the correct string.
• You can easily read settings in the file and view them in a hierarchical structure.