SDK Developer Guide for .NET

Intel AppUp™ Software Development Kit

Developer Guide for .NET technology

Copyright © 2010 Intel Corporation

All Rights Reserved

Document Number: 323985-001US

Revision: 1.00

World Wide Web: http://www.intel.com

Document Number: 323985-001US


Disclaimer and Legal Information

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL(R) PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. UNLESS OTHERWISE AGREED IN WRITING BY INTEL, THE INTEL PRODUCTS ARE NOT DESIGNED NOR INTENDED FOR ANY APPLICATION IN WHICH THE FAILURE OF THE INTEL PRODUCT COULD CREATE A SITUATION WHERE PERSONAL INJURY OR DEATH MAY OCCUR. Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice. Do not finalize a design with this information. The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order. Copies of documents which have an order number and are referenced in this document, or other Intel literature, may be obtained by calling 1-800-548-4725, or by visiting Intel's Web Site.

Intel processor numbers are not a measure of performance. Processor numbers differentiate features within each processor

family, not across different processor families. See http://www.intel.com/products/processor_number for details.

For beta and pre-release product versions. This document contains information on products in the design phase of development.

BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino Atom, Centrino Atom Inside, Centrino Inside, Centrino logo, Core Inside, FlashFile, i960, InstantIP, Intel, Intel logo, Intel386, Intel486, IntelDX2, IntelDX4, IntelSX2, Intel Atom, Intel Atom Inside, Intel Core, Intel Inside, Intel Inside logo, Intel. Leap ahead., Intel. Leap ahead. logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel SingleDriver, Intel SpeedStep, Intel StrataFlash, Intel Viiv, Intel vPro, Intel XScale, Itanium, Itanium Inside, MCS, MMX, Oplus, OverDrive, PDCharm, Pentium, Pentium Inside, skoool, Sound Mark, The Journey Inside, Viiv Inside, vPro Inside, VTune, Xeon, and Xeon Inside are trademarks of Intel Corporation in the U.S. and other countries.

* Other names and brands may be claimed as the property of others.

Copyright (C) 2010, Intel Corporation. All rights reserved.

Microsoft product screen shot(s) reprinted with permission from Microsoft Corporation.

2 Document Number: 323985-001US

http://www.intel.com/products/processor_number

About this Document

Revision History

Document Number

Revision Number

Description Revision Date

323985 001 Initial document release to support SDK V1.0 August 2010

Developer Guide for .NET technology 3


Contents

1 ................................................................ 5 About this Document1.1 .................................................................................5 Intended Audience1.2 .....................................................................5 Using this Developers Guide1.3 ........................................................................6 Conventions and Symbols1.4 ................................................................................6 Related Information

2 .................................................................................. 7 Overview2.1 .............................................................7 Intel AppUpSM Developer Program2.2 ........................................................................................8 SDK Contents2.3 ................................................................................ 10 Development Flow

3 ....................................................................... 12 Getting Started3.1 ........................................................................ 12 Hello World in C# / WPF3.2 ................................................................ 16 Hello World in C# / WinForms3.3 ............................................................ 18 Hello World in Visual Basic / WPF3.4 .................................................... 20 Hello World in Visual Basic / WinForms

4 ............................................................ 23 Advanced Information4.1 ........................................................................................... 23 API Levels4.2 ................................................................... 24 Error and Warning Handling

4.2.1 .......................................................... 25 C# (WPF and WinForms)4.2.2 .............................................. 26 Visual Basic (WPF and WinForms)

4.3 ................................................................................... 28 Instrumentation4.3.1 .......................................................... 28 C# (WPF and WinForms)4.3.2 .............................................. 31 Visual Basic (WPF and WinForms)

4.4 ................................................................................... 33 Crash Reporting4.4.1 ............................................................... 33 Default Crash Report4.4.2 ....................................................... 34 Customizing Crash Reports

4.5 ............................................. 38 Using the Intel AppUp™ Software Debugger

§


About this Document

1 About this Document

This document is for developers getting started with the Intel AppUpTM Software Development Kit 1.0 for .NET technology. The SDK (Software Development Kit) includes programming libraries, documentation, and sample code to help developers create, test, and submit .NET applications intended for distribution via the Intel AppUpSM center.

1.1 Intended Audience This document is intended for experienced software developers who are developing applications for the Intel AppUpSM center, using one of the supported languages and graphical APIs. These can be new applications or existing applications being ported for the Intel AppUpSM center. The SDK supports the following languages and Microsoft Windows* graphical APIs:

• C# for WPF (Windows Presentation Foundation) applications

• C# for WinForms (Windows Forms) applications

• Visual Basic for WPF applications

• Visual Basic for WinForms applications

NOTE: This SDK supports products compiled targeting the .NET Framework 3.5 runtime. Developers creating applications that incorporate this SDK must compile and validate those applications with the .NET Framework 3.5 runtime.

NOTE: Not all SDK functions and capabilities are supported for each language/API combination.

NOTE: This SDK release supports development of Intel AppUpSM center applications only (not components).

1.2 Using this Developers Guide This developer guide contains the following sections:

• Section 1, About this Document, introduces the contents and conventions of this document.



• Section 2, Overview, introduces the Intel AppUpSM Developer Program, this SDK, and the general application development flow.

• Section 3, Getting Started, provides the minimum steps for getting an existing application ready to submit to the Intel AppUpSM Developer Program portal, for C# (WPF and WinForms) and Visual Basic (WPF and WinForms).

• Section 4, Advanced Information, describes how to integrate the additional capabilities of the SDK library to build a more robust application that provides a better experience for users and/or better usage feedback to developers.

1.3 Conventions and Symbols

The following table shows the conventions used in this document.

Conventions and Symbols Used in This Document

Indicates an element of syntax, reserved word, keyword, filename, computer output, or part of a program example. The text appears in lowercase unless uppercase is significant.

This type style

This type style Indicates the exact characters you type as input. Also used to highlight the elements of a graphical user interface such as buttons and menu names or filenames and labels when discussing program examples.

Hyperlink Indicates a hyperlink to internal or external information. Use CNTL+mouse click to navigate.

Notes, cautions, etc. Note: Indicates an important comment or side topic for the user.

1.4 Related Information

Reference information for the .NET SDK is provided in the Intel AppUpTM Software Development Kit API Reference for .NET technology document, which is located on the Intel AppUpSM Developer Program portal.

§


http://appdeveloper.intel.com/en-us/article/intel-appup-software-development-kit-api-reference-dotnet-technology




Overview

2 Overview

This section provides an overview of the following:

• Intel AppUpSM Developer Program

• SDK Contents

• Application Development Flow

2.1 Intel AppUpSM Developer Program The Intel AppUpSM Developer Program provides developers with everything they need to create and then sell their applications to end users of Intel® Atom™ processor-based devices (netbooks, smartphones, and pads) through the Intel AppUpSM center. This allows you to earn money for your development efforts. The figure below shows a high-level view of how developers, Intel, and consumers interact.



The following paragraphs summarize this interaction:

• Developers prepare their applications for submission to the Intel AppUpSM Developer Program portal using existing tools and Intel-provided SDK libraries, plug-ins, documentation, and support.

• Intel validates submitted applications and, when they are ready, publishes them in the Intel AppUpSM center for consumers.

• Consumers purchase (or download) published applications from the Intel AppUpSM center and run them on their client platforms.

• Information on downloads, usage, and ratings is provided to developers via the Intel AppUpSM Developer Program Dashboard. The Dashboard also displays payment information.

For more information on how the program works, including details on how payment is handled, visit the program portal at http://appdeveloper.intel.com.

2.2 SDK Contents The Intel AppUpTM SDK for .NET technology includes the following major elements:

• Intel AppUpTM software libraries for C# and Visual Basic

• Code Examples for C# and Visual Basic (WPF and WinForms)

• Documentation to show you how to incorporate the appropriate API calls into your applications

The figure below shows the different elements of the SDK.


http://appdeveloper.intel.com/

Overview

SDK Libraries

SDK libraries provide you with access to Consumer Client services such as Authorization, Error and Warning Handling, Instrumentation (metering) and Crash Reporting. Functionality will increase over time with new library releases, as appropriate for each language and runtime.

SDK libraries are the only parts of the SDK that are redistributed with applications. There will be separate implementations of the library for each supported runtime and, in the case of native applications, for each supported operating system.

Intel AppUp™ Software Debugger

The Intel AppUp™ Software Debugger is a utility that emulates the Application Services of the Consumer Client. The debugger allows you to test and debug your application without requiring the full client or access to hardware.

Documentation

Three types of documentation are provided to help you develop applications for the Intel AppUpSM Developer Program: (1) sample code, (2) a Developer Guide (this document), and (3) an online API Reference for a specific language/API.

Development Process Integration

Developer Process Integration allows you to quickly insert SDK library code into your existing applications, integrate the Intel AppUp™ Software Debugger into your debug flow, etc., from within your IDE. The Intel AppUp™ SDK Plug-in 1.0 for Visual Studio* 2008 software supports development process integration for C#.

Developer Portal Integration

Developer Portal Integration allows you to interact with the Intel AppUpSM Developer Program portal to view your Dashboard, interact with Developer Resources, etc., from within your IDE. The Intel AppUp™ SDK Plug-in 1.0 for Visual Studio* 2008 software supports development portal integration for C#.



2.3 Development Flow The figure below illustrates the high-level development flow for Intel AppUpSM Developer Program applications. The general steps in this flow are as follows:

• Enroll in the Intel AppUpSM Developer Program, by creating an account on the Intel AppUpSM Developer Program portal and then joining the program.

• Download the Intel AppUpTM SDK (Software Development Kit) for your target application development language and runtime. In some cases, a Plug-in package is available for an Integrated Development Environment to ease the development process. (It is important to keep your SDK up-to-date with periodic refreshes from the Intel AppUpSM Developer Program portal.)

• Insert the minimum SDK code into your existing application. This will always include the authorization code. For some languages, it may also include header, exception handling, and cleanup code or references.

• Perform initial testing with the Intel AppUp™ Software Debugger to make sure the authorization code is working properly.

• Flesh out your existing application with other SDK code, as appropriate. You should consider advanced Error and Warning Handling, Instrumentation, and advanced Crash Reporting for your application. It is not required that you address these areas, but they can help your application provide a better user experience. In some cases, they can provide you with more insight into your application’s usage. Some languages/runtimes do not support all of the SDK capabilities.

• Perform additional testing with the Intel AppUp™ Software Debugger to make sure any additional SDK code is working properly.

• Replace the Debug GUID with a Production GUID. You must obtain the Production GUID from the Intel AppUpSM Developer Program portal.

• Package your application into an .MSI installation package that supports “silent install”. Make sure the appropriate SDK .dll library file is wrapped into your application installer. Section 3 provides more information on this topic.

• Pre-validate your .MSI package and make changes as needed. Pre-validation can help smooth validation by Intel. Section 3 provides more information on this topic.

• Submit your final installation package to the Intel AppUpSM Developer Program portal for validation by Intel.


Overview

§



3 Getting Started

This section describes the basic steps to get an application ready for the Intel AppUpSM Developer Program portal. First, the steps are described for C# and WPF using the sample project AdpWpfHelloWorld. Then the differences are described for the other language/API combinations.

3.1 Hello World in C# / WPF The C#/ WPF AdpWpfHelloWorld sample project (installed with the SDK) is a minimal application that incorporates Intel AppUpTM software authorization code and basic error handling. (A button to demonstrate Crash Reporting is also included in the sample, but is not required and is not discussed in this section.)

Assume that you have a working AdpWpfHelloWorld application like the sample, but that it does not have Intel AppUpTM SDK code included. Assume also that you have already installed the SDK. The following steps describe how to integrate Intel AppUpTM SDK code into the application:

Step 1: Add SDK Library as Reference

In Visual Studio, use the Add Reference item on the Project menu to add AdpLibrary.dll to the project. (Or right click on Reference and use Add Reference from the shortcut menu to add the library to the project.) The SDK is installed in <drive>\Program Files\IntelAppUp SDK\DotNet\lib. (This same library must be wrapped into your application installer and installed with the application.)

Step 2: Declare SDK Namespace

In the declaration section at the start of the C# source file, define com.intel.adp as a namespace. This frees you from having to add it as a prefix for SDK calls in your application. See the sample below:

/// <ADP>

using com.intel.adp;

/// </ADP>


Getting Started

Step 3: Insert SDK Authorization Code Using Authorized Debug ID

Locate the code that initializes the application and insert the SDK authorization code. The SDK authorization code for AdpWpfHelloWorld is highlighted in a red box in the sample below. (The authorization code includes the Application Constructor call, which performs initialization and authorization, and catches exceptions. When the application ends, the code performs SDK library shutdown and catches exceptions. The application is derived from a core Application class. Only one instance of the Application class may exist in an application.)

NOTE: A system is authorized to run an application if the application was purchased by the user on the current system or if the system is one of the five systems allowed by the licensing system. As the application developer, you are responsible to ensure that the current system has a license to use your application; the OS or runtime does not enforce this automatically.

Note that an Authorized Debug ID is used. During development, this Debug ID allows testing with the Intel AppUp™ Software Debugger. This Debug ID is a 128-bit number, expressed as a string using predefined constants. The value of the Authorized Debug ID is contained in the SDK library. You can also use the absolute value (all one’s), as shown in the sample. You must replace the Debug ID with a Production ID after testing. The Production ID is discussed in detail later in this section.) There is also an Expired Debug ID to allow you to test the “expired” branch of your application.

NOTE: Steps 1-3 above are the only mandatory steps to get a C# application running initially. Advanced Error and Warning Handling, Instrumentation, and Crash Reporting are not discussed here, but you should consider them for actual applications. Those topics are all covered in Section 4, Advanced Information.



InitializeComponent();

/// <ADP>

try

{

AdpApplication app = new AdpApplication(new AdpApplicationId(0x11111111, 0x11111111, 0x11111111, 0x11111111));

/// Note: replace "0x11111111, 0x11111111, 0x11111111, 0x11111111" with the actual application ID

/// once you obtain it from Intel AppUp(SM) Developer Program web portal

/// To test Expired ID, use AdpConstants.ADP_EXPIRED_APPLICATIONID

}

catch (AdpException e)

{

if ( e is AdpErrorException)

{

// TO DO: add your logic to handle the errors during initialization

MessageBox.Show(e.Message, "Error");

System.Environment.Exit(1);

}

else if ( e is AdpWarningException)

{

// TO DO: add your logic to handle the warnings

MessageBox.Show(e.Message, "Warning");

}

}

/// </ADP>

Step 4: Test Application with Intel AppUp™ Software Debugger

The SDK includes the Intel AppUp™ Software Debugger, which emulates the Application Services of the Consumer Client on your system, without requiring the full client or access to hardware. The Intel AppUp™ Software Debugger allows testing of authorization, error handling, crash reporting, and instrumentation.

With the Intel AppUpTM SDK Plug-in 1.0 for Visual Studio 2008 software installed and the Intel AppUpTM SDK code included, you can start and stop the Intel AppUp™ Software Debugger and Visual Studio debugger at the same time. Intel AppUp™ Software Debugger trace information is included in a dedicated Visual Studio Output tab and in an Intel AppUp™ Software Debugger window.

Use one of the following methods to start the Intel AppUp™ Software Debugger and Visual Studio debugger:


Getting Started

• Visual Studio Start Debugger icon

• F5 key

• Visual Studio Start Debugger menu item

Use one of the following methods to stop the Visual Studio debugger and Intel AppUp™ Software Debugger:

• Visual Studio Stop Debugger icon

• SHIFT+F5 key

• Visual Studio Stop Debugger menu item

See Section 4 for more information on using the Intel AppUp™ Software Debugger.

Step 5: Get and Swap In a Production ID

Once your application is working, you must replace the Debug ID with a Production ID before you can submit the application to the Intel AppUpSM Developer Program portal. Production IDs are obtained from the Intel AppUpSM Developer Program portal, which requires that you enroll in the Intel AppUpSM Developer Program. The Production ID is a 128-bit number organized as four integers in hex format. The following example shows part of the authorization code with a Production ID included.

AdpApplication app = new AdpApplication(new AdpApplicationId(0x12341234, 0x56785678, 0x12341234, 0x56785678));

Assume you are enrolled in the Intel AppUpSM Developer Program and have logged into the program portal. Start the application submission process and provide information that uniquely identifies your application. After entering that information, click on the Get a GUID button on the portal. The site displays a GUID, which is a Production ID. You can copy and paste this Production ID into your application, replacing the Debug ID. (You can also request that the portal email a Production ID to you.)

NOTE: While the Production ID is used, you can no longer use the Intel AppUp™ Software Debugger for normal testing and debugging. (The debugger will return an ADP_NOT_AUTHORIZED error.) You can always return to using the Debug ID to perform broader testing and debugging using the Intel AppUp™ Software Debugger.

You can obtain a Production ID as early in your development cycle as you wish. Since submitting the name for an application is required to receive a Production ID, getting a Production ID early increases your chances that your desired application name will still be available.



Step 6: Create an Installation Package

Create a “silent install” .MSI package that meets the Intel AppUpSM Developer Program packaging requirements. These requirements ensure that applications provide a good user experience during installation and Uninstallation. For a list of packaging requirements, refer to http://appdeveloper.intel.com/en-us/article/packaging-requirements. For tips on packaging applications for Windows, refer to http://appdeveloper.intel.com/en-us/article/how-creating-your-msi-installer-using-visual-studio-2008. You must wrap the AdpLibrary.dll library file into your application installer. The installer must copy the .dll file into the same folder where the application’s main executable is copied.

Step 7: Pre-Validate the Installation Package

Intel validates application packages submitted to the Intel AppUpSM Developer Program portal prior to publishing them on the Intel AppUpSM center. You should become familiar with the validation process and pre-validate as many of the items as possible yourself prior to submission. This helps to smooth the approval process for your application. Use of a tool such as ORCA can help to pre-validate the installation package. For more information on the validation process, refer to http://appdeveloper.intel.com/en-us/article/troubleshooting-validation-failures.

Step 8: Submit the Application

Submit your application package by following the steps on the Intel AppUpSM Developer Program portal. You can then monitor status of the application via the My Dashboard page on the portal. Alternately, with the Intel AppUpTM SDK Plug-in 1.0 for Visual Studio 2008 software installed, you can use the Dashboard feature to monitor status.

3.2 Hello World in C# / WinForms This discussion assumes you have read the previous C# / WPF subsection. Only the differences between that subsection and C# / WinForms are covered here.

The AdpWinFormHelloWorld sample application (installed with the SDK) is the basis for this discussion. The following steps describe how to integrate Intel AppUpTM SDK code into the C# / WinForms application:


This step is the same as for C# / WPF. Add AdpLibrary.dll to the WinForms project in Visual Studio.


http://appdeveloper.intel.com/en-us/article/packaging-requirements

http://appdeveloper.intel.com/en-us/article/packaging-requirements

http://appdeveloper.intel.com/en-us/article/how-creating-your-msi-installer-using-visual-studio-2008

http://appdeveloper.intel.com/en-us/article/how-creating-your-msi-installer-using-visual-studio-2008

http://appdeveloper.intel.com/en-us/article/troubleshooting-validation-failures

Getting Started


This is the same step as for C# / WPF. Declare com.intel.adp as a namespace so you do not need to add it as a prefix for SDK calls in your application.

Step 3: Insert SDK Authorization Code Using Debug ID

This step, inserting SDK authorization code using a Debug ID, is the same as described previously for C# / WPF. The syntax is the same as for C# / WPF, but a different application constructor is used when the WinForms application is compiled.

NOTE: Steps 1-3 above are the only mandatory steps to get a C# application running initially. Advanced Error and Warning Handling, Instrumentation, and Crash Reporting are not discussed here, but you should consider them for actual applications. Those topics are all covered in Section 4, Advanced Information.


The steps to start and stop the Intel AppUp™ Software Debugger and Visual Studio debugger are the same as described previously for C# / WPF. With the Intel AppUpTM SDK Plug-in 1.0 for Visual Studio 2008 software installed and the Intel AppUpTM SDK code included, you can start and stop the Intel AppUp™ Software Debugger and Visual Studio debugger at the same time. Intel AppUp™ Software Debugger trace information will appear in a dedicated Visual Studio Output tab and in an Intel AppUp™ Software Debugger window.


This step, obtaining and swapping in a Production ID, is the same as described previously for C# / WPF. The syntax is the identical to C# / WPF.

Step6: Create an Installation Package

Follow the same general process for creating a “silent install” .MSI package as for C# / WPF.


Follow the same general process for pre-validating an application installation package as for C# / WPF.


Follow the same process for submission as described previously for C# / WPF.



3.3 Hello World in Visual Basic / WPF This discussion assumes you have read the previous C# / WPF subsection. Only the differences between that subsection and C# / WinForms are covered here. VB is an abbreviation for Visual Basic.

The VB / WPF AdpWpfVbHelloWorld sample application (installed with the SDK) is the basis for this discussion. The following steps describe how to integrate Intel AppUpTM SDK code into the VB / WPF application:


This step is the same as for C# / WPF. Add AdpLibrary.dll to the WinForms project in Visual Studio.


Declare the SDK namespace com.intel.adp using the Imports Statement shown below. This frees you from having to add it as a prefix for SDK calls in your application.

Imports com.intel.adp

Step3: Insert SDK Authorization Code Using Authorized Debug ID

Locate the Initialization event code and insert the SDK authorization code. The SDK authorization code for AdpWpfVbHelloWorld is highlighted in a red box in the sample below. You many need to create an Initialization event if your application does not already have one. (The authorization code includes the Application Constructor call, which performs initialization and authorization, and catches exceptions. When the application ends, the code performs SDK library shutdown and catches exceptions.)


Getting Started

Private Sub Window_Initialized(ByVal sender As System.Object, ByVal e As System.EventArgs)

Try

Dim app As New AdpApplication(New AdpApplicationId(&H11111111, &H11111111, &H11111111, &H11111111))

' Note: replace "&H11111111, &H11111111, &H11111111, &H11111111" with the actual application ID

' once you obtain it from Intel AppUp(SM) Developer Program web portal

' To test Expired ID, use AdpConstants.ADP_EXPIRED_APPLICATIONID

Catch ex As AdpException

If TypeOf ex Is AdpErrorException Then

' TO DO: add your logic to handle the errors during initialization

MsgBox(ex.Message)

System.Environment.Exit(1)

ElseIf TypeOf ex Is AdpWarningException Then

' TO DO: add your logic to handle the warnings

MsgBox(ex.Message)

End If

End Try

End Sub




This step, obtaining and swapping in a Production ID, is the same as described previously for C# / WPF. The syntax for VB is different, as shown below.

Dim app As New AdpApplication(New AdpApplicationID(0x12341234, 0x56785678, 0x12341234, 0x56785678))









3.4 Hello World in Visual Basic / WinForms This discussion assumes you have read the previous Visual Basic / WPF subsection. Only the differences between that subsection and Visual Basic / WinForms are covered here. VB is an abbreviation for Visual Basic.

The AdpWinFormVbHelloWorld sample application (installed with the SDK) is the basis for this discussion. The following steps describe how to integrate Intel AppUpTM SDK code into the VB / WinForms application:


This step is the same as for VB / WPF.


This step is the same as for VB / WPF.

Step 3: Insert SDK Authorization Code Using Authorized Debug ID

Locate the Initialization event code and insert the SDK authorization code. The SDK authorization code for AdpWinFormVbHelloWorld is highlighted in a red box in the sample below. You many need to create an Initialization event if your application does not already have one. (The authorization code includes the Application Constructor call, which performs initialization and authorization, and catches exceptions. When the application ends, the code performs SDK library shutdown and catches exceptions.)


Getting Started

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load

Try







' TO DO: add your logic to handle the errors during initialization

MsgBox(ex.Message)



' TO DO: add your logic to handle the warnings

MsgBox(ex.Message)

End If

End Try

End Sub




This step, obtaining and swapping in a Production ID, is the same as described previously for C# / WPF. The syntax for VB is different, as shown below.

Dim app As New AdpApplication(New AdpApplicationId0x12341234, 0x56785678, 0x12341234, 0x56785678))









§


Advanced Information

4 Advanced Information

This section provides advanced information on the following topics:

• API Levels

• Error and Warning Handling

• Instrumentation

• Crash Reporting

• Using the Intel AppUp™ Software Debugger

4.1 API Levels The Intel AppUpTM SDK library provides a mechanism to determine compatibility of the API level of applications versus the API level of client systems.

Applications with API levels higher than that supported by the client system are not permitted to be downloaded to the client. If the API level on a client system is rolled back to a lower API level, applications with higher API levels already intstalled on the client system are not permitted to run. A Consumer Client can concurrently support applications with different API levels.

API level information for an application is displayed in the Intel AppUp™ Software Debugger output, as shown in the figure below. This information can be useful when debugging potential issues.



4.2 Error and Warning Handling The exception handler in Section 3, Getting Started, is basic. This basic handler can be expanded to provide more robust handling of errors and warnings.

The .NET SDK library includes three pre-defined exception classes for errors and one pre-defined exception class for warnings to provide greater granularity in exception handling. You should consider using these classes to provide more robust error handling for your application. The exception classes are as follows:

Error Exception Classes

• InitializationException – Catches error exceptions thrown while the SDK library application constructor attempts to initialize the SDK library code. This class is derived from AdpErrorException.

• UnauthorizedException – Catches error exceptions thrown while the SDK library code attempts to authorize the application. This class is derived from AdpErrorException.



• AdpRuntimeException – Catches general runtime error exceptions while executing SDK library code. This class is derived from AdpErrorException.

Warning Exception Class

• AdpWarningException – Catches warning exceptions while executing SDK library code.

AdpErrorException and AdpWarningException are both derived from the same base class, AdpException. (AdpErrorException was used in the samples in Chapter 3, Getting Started, but it is recommended that the more granular classes be used in actual applications.)

NOTE: Most testing is performed with the ADP_DEBUG_APPLICATIONID GUID. You can change the GUID to the ADP_DEBUG_EXPIREDID to test the application “expired” branch of your error handler.

For exceptions that are not possible to handle in your application, the recommended approach is to re-throw the exception. (The method to re-throw the exception depends on the application language and context.) The integrated crash handler in the SDK library then catches the exception and generates a Crash Report using the context information from the exception. See the Crash Reporting subsection for details on Crash Reporting.

4.2.1 C# (WPF and WinForms)

The C# code sample below includes application constructor call and a catch for each of the SDK library warning and error exception classes. The sample uses an Authorized Debug.



{

app = new AdpApplication(new AdpApplicationId(0x11111111, 0x11111111, 0x11111111, 0x11111111));



}

catch (AdpException ex)

{

if (ex is AdpErrorException)

{

if (ex is InitializationException)

{

// TO DO: add your logic to handle the errors during initialization

MessageBox.Show(ex.Message, "Initialization Error");


}

else if (ex is UnauthorizedException)

{

// TO DO: add your logic to handle the errors during authorization

MessageBox.Show(ex.Message, "Authorization Error");


}

if (ex is AdpRunTimeException)

{

// TO DO: add your logic to handle the errors during runtime

MessageBox.Show(ex.Message, "Initialization Error");


}

}

else if (ex is AdpWarningException)

{


MessageBox.Show(ex.Message, "Warning");

}

}

4.2.2 Visual Basic (WPF and WinForms)

The VB code sample below includes an authorization call and a catch for each of the SDK library warning and error exception classes. The sample uses an Authorized



Debug ID.

Try





txtResult.Text = "Hello World"



If TypeOf ex Is InitializationException Then

‘ TO DO: Initialization error message and logic

MsgBox(ex.Message)


If TypeOf ex Is UnauthorizedException Then

‘ TO DO: Initialization error message and logic

MsgBox(ex.Message)


If TypeOf ex Is AdpRuntimeException Then

‘ TO DO: Runtime error message and logic

MsgBox(ex.Message)


End If


' TO DO: Warning message and logic

MsgBox(ex.Message)

End If

End Try



4.3 Instrumentation The Intel AppUpSM Developer Program portal allows you to collect usage statistics for your applications. The Intel AppUpSM center aggregates this information and passes it to My Dashboard on the Intel AppUpSM Developer Program portal. If the application is offline, the information is cached and sent later when the application is online.

NOTE: The final decision on whether to gather and send this information to the Intel AppUpSM center lies with the end user. They must explicitly agree to the collection and transmittal of this usage data. If they say no, this data is discarded. Your application must support this explicit end-user opt in choice. Even if they say yes, no individual user or machine identifying information is collected; all data is aggregated.

The SDK supports the following Instrumentation events to measure application usage:

• Application Begin Event – Triggers sending a Begin Event message to the Intel AppUpSM center for the application.

• Application End Event – Triggers sending an End Event message to the Intel AppUpSM center for the application.

The Application Constructor call shown in Section 3, Getting Started, includes an implied Begin Event parameter. When the application constructor runs, it automatically triggers a Begin Event. During application shutdown, the code automatically triggers an End Event.

The combination of a BeginEvent call followed (eventually) by an EndEvent call results in an application usage record being generated. A BeginEvent call with no EndEvent call results in no application usage record being generated. The following subsections show how to explicitly trigger a Begin Event and an End Event for C# and VB, respectively.

4.3.1 C# (WPF and WinForms)

Before explicitly including Begin Event in your application, you must define the object as a member variable of the class where the BeginEvent call will be inserted, as outlined below in red:



public partial class AdpHelloWorldWindow : Window

{

com.intel.adp.Application app;

public AdpHelloWorldWindow()

{

InitializeComponent();

try

{

app = new AdpApplication(new AdpApplicationId(0x11111111, 0x11111111, 0x11111111, 0x11111111), false);

}

/// catches for exceptions and warnings

}

}

Next, disable the automatic Begin Event that the application constructor runs by default. This is accomplished by using a longer form of the Application Constructor call with a Boolean false as a parameter after the GUID, as outlined above in blue.



Then you can include the explicit event triggers in your application. To explicitly trigger a Begin Event, include the following BeginEvent call and catch sequence in your application at the point where you wish to trigger the event:

try

{

app.BeginEvent();

}


{


{

// TO DO: add your logic to handle the errors at run time

MessageBox.Show(ex.Message, "Fatal Error");


}


{



}

}



To explicitly trigger an End Event, include the following EndEvent call and catch sequence in your application at the point where you wish to trigger the event:

try

{

app.EndEvent();

}


{


{

// TO DO: add your logic to handle the errors at run time

MessageBox.Show(ex.Message, "Fatal Error");


}


{



}

}

4.3.2 Visual Basic (WPF and WinForms)

This subsection shows syntax and code samples only. Please read the previous subsection on C# to understand the implications of the Boolean parameters in the call.

To explicitly include a Begin Event in the VB call, use the longer form of the Application Constructor call and include a Boolean false parameter after the GUID as follows (the example uses a Debug ID):



Try

Dim app As New AdpApplication(New AdpApplicationId(&H11111111, &H11111111, &H11111111, &H11111111), false)

‘catches for exceptions and warnings

End try

To explicitly trigger a Begin Event, include the following BeginEvent call and catch sequence in your application at the point where you wish to trigger the event:

Try

app.BeginEvent()



' TO DO: add your logic to handle the errors at run time

MsgBox(ex.Message)



‘ TO DO: add your logic to handle the warnings

MsgBox(ex.Message)

End If

End Try

To explicitly trigger an End Event, include the following EndEvent call and catch sequence in your application at the point where you wish to trigger the event:

Try

app.EndEvent()



' TO DO: add your logic to handle the errors at run time

MsgBox(ex.Message)



‘ TO DO: add your logic to handle the warnings

MsgBox(ex.Message)

End If

End Try



4.4 Crash Reporting Even when you follow best practices with respect to error handling, applications sometimes encounter unexpected situations and crash. To facilitate debug in these situations, the SDK library supports Crash Reporting to provide a snapshot of the state of the application when it does crash.

The Intel AppUpTM SDK library supports Crash Reporting to provide application context information when crashes occur. Default crash reports are automatically enabled when the application constructor runs; you do not have to explicitly enable this capability. However, you must explicitly disable default Crash Reporting when implementing customized Crash Reporting. (Customized Crash Reporting is covered at the end of this subsection.)

When a crash occurs, crash information is first stored locally on disk. Then a process wakes up to create and send the crash report to the Intel AppUpSM Developer Program portal. The crash information stored on disk is a subset of the report sent to the Intel AppUpSM Developer Program portal. When the process runs, the process adds information to what is stored on disk to create the final report. This process also periodically sweeps the crash reporting area, looking for unsent crash reports.

NOTE: Since the stability of the system cannot be assumed, there is no guarantee that a crash report will be generated. To maximize the success of Crash Reporting, the SDK library attempts to write crash information to disk first and limits the amount of information in the report. When implementing custom Crash Reporting, you should also follow this policy by keeping your custom report fields and logic to a minimum.

NOTE: Crash reports are intended only for application crashes. They are not intended as an error logging vehicle. Abuses will be monitored.

For default Crash Reporting, all information in the report is pre-defined by the SDK library code. (If you desire additional or different information than provided in the default crash report, you must implement custom Crash Reporting, which is covered at the end of this subsection.)

4.4.1 Default Crash Report

Default crash reports are viewable via My Dashboard on the Intel AppUpSM Developer Program portal. The figure below shows a default crash report from My Dashboard on the portal. This information includes application context information, runtime environment information, SDK identification information, and a core stack dump. The complete report can be viewed by clicking on the Details link for a specific report.



4.4.2 Customizing Crash Reports

Customized Crash Reporting allows you to provide different information than default Crash Reporting. Customized Crash Reporting is implemented by defining a crash report class MyCrashReport derived from the SDK DefaultCrashReport class. Then setting MyCrashReport (or any other name derived from DefaultCrashReport) in the source code automatically disables default Crash Reporting.

The table below lists the possible fields in a crash report, with the Source column defining the source (SDK or Developer) of the information for the respective field. As a developer, you can modify the fields where the Source is listed as Developer. Fields are modified by overriding the default field.

Custom crash reports are set immediately after the SDK Application Constructor call so that crash reports can include data as early in application execution as is reasonably possible.

NOTE: It is your responsibility to ensure that custom Crash Reports do not include any data that violates Intel Privacy rules. See http://appdeveloper.intel.com for details.


http://appdeveloper.intel.com/


Custom Crash Report Fields and Sources

Crash Report Fields My Dashboard Column Source

No (but included in Details) Application Name SDK

No (but included in Details) Application ID SDK

ModuleName Module (and in Details) Developer

LineNumber Line (and in Details) Developer

No (but included in Details) Developer Category

Message Messages (and in Details) Developer

No (but included in Details) ErrorData Developer

No (but included in Details) SDK API Level SDK

Runtime Runtime (and in Details) SDK

No (but included in Details) Runtime version SDK

OS OS (and in Details) SDK

No (but included in Details) OS version SDK

Timestamp Timestamp (and in Details) SDK

Up to 20 custom fields (reserved for future use) Developer

The fields with the greatest flexibility for customization are listed below:

• The Category field allows you to create categories to sort your crash reports on the Intel AppUpSM Developer Program portal. For example, you may wish to create categories called “MEMORY”, “IO”, “USER ERROR”, etc.

• The Error Data field allows you to create your own stack dumps or long error messages to help you understand why your application crashed.

NOTE: Some crashes can lead to a client system eventually halting. In these cases, the time to store a crash report on the client system may be limited. To maximize obtaining crash information, you should consider the tradeoffs between the amount of information to include in a custom crash report versus a potentially narrow window of time to store the information on the client system.

4.4.2.1 Custom Crash Report Code for C#

The following example shows the framework to set and define a custom crash report for C#. Note that the crash report is set immediately after the Application Constructor call. An Authorized Debug ID is used for this example.



try

{

app = new AdpApplication(new AdpApplicationId(0x11111111, 0x11111111, 0x11111111, 0x11111111), false);



// Set my own crash report

app.SetCrashReport(new MyCrashReport());

}

public class MyCrashReport : DefaultCrashReport

{

/// <summary>

/// This method is provided to populate the AbstractCrashReport::_message member variable

/// </summary>

public override void PopulateMessage()

{

this._message = this.UnhandledException.Message;

}

/// <summary>

/// This method is provided to populate the AbstractCrashReport::_category member variable.

/// </summary>

public override void PopulateCategory()

{

this._category = this.UnhandledException.GetType().ToString();

}

(continued on next page)



/// <summary>

/// This method is provided to populate the AbstractCrashReport::_errorData member variable.

/// </summary>

public override void PopulateErrorData()

{

if (this._ex.StackTrace.Length > AdpConstants.ADP_MAX_ERR_DATASIZE)

this._errorData = this.UnhandledException.StackTrace.Substring(0, AdpConstants.ADP_MAX_ERR_DATASIZE - 1);

else

this._errorData = this.UnhandledException.StackTrace;

}

/// <summary>

/// This method is provided to populate the AbstractCrashReport::_customField member variable.

/// </summary>

public override void PopulateCrashReportFields()

{

if (this._customField != null)

this._customField.Clear();

ADP_CrashReportField x;

x.name = "MyReportFieldName";

x.value = "MyReportFieldValue";

this._customField.Add(x);

}

}

4.4.2.2 Custom Crash Report Code for Visual Basic

The following example shows the framework to set and define a custom crash report for Visual Basic. Note that the crash report is set immediately after the Application Constructor call. An Authorized Debug ID is used for this example.



Try

app = New AdpApplication(New AdpApplicationId(&H11111111, &H11111111, &H11111111, &H11111111), False)


‘ once you obtain it from Intel AppUp(SM) Developer Program web portal


app.SetCrashReport(New MyCrashReport())

Class MyCrashReport

Inherits DefaultCrashReport

''' <summary>

''' This method is provided to populate the AbstractCrashReport::_message member variable

''' </summary>

''' <remarks></remarks>

Public Overrides Sub PopulateMessage()

Me._message = Me.UnhandledException.Message

End Sub

End Class

4.5 Using the Intel AppUp™ Software Debugger The SDK includes the Intel AppUp™ Software Debugger, which emulates the Application Services of the Consumer Client on your system, without requiring the full client or access to hardware. The Intel AppUp™ Software Debugger allows testing of authorization, error handling, crash reporting, and instrumentation.

With the Intel AppUpTM SDK Plug-in 1.0 for Visual Studio 2008 software installed and the Intel AppUpTM SDK code included, you can start and stop the Intel AppUp™ Software Debugger and Visual Studio debugger at the same time. The installed default is to display Intel AppUp™ Software Debugger trace information in a dedicated Visual Studio Output tab and in a dedicated Intel AppUp™ Software Debugger window.



The following methods start the Intel AppUp™ Software Debugger and Visual Studio debugger:

• Visual Studio Start Debugger icon

• F5 key

• Visual Studio Start Debugger menu item

The following methods stop the Visual Studio debugger and Intel AppUp™ Software Debugger:

• Visual Studio Stop Debugger icon

• SHIFT+F5 key

• Visual Studio Stop Debugger menu item

The figure below shows the Intel AppUp™ Software Debugger window with some debug data displayed. Data includes basic SDK version and level information, API level compatibility status, and application GUID authorization information. Additional information may be displayed, depending on what SDK calls are used by your application and how the Intel AppUp™ Software Debugger responds.




The Clear button clears the current contents of the Intel AppUp™ Software Debugger window. Contents of the dedicated Visual Studio Output window are not affected.

The Exit screen closes the Intel AppUp™ Software Debugger window. The close icon in the upper corner of the window also closes the debugger window.

NOTE: The Intel AppUpSM center will not run properly if the Intel AppUp™ Software Debugger is running. You must exit the Intel AppUp™ Software Debugger before running the Intel AppUpSM center.

§

SDK Developer Guide for .NET

Documents

Transcript of SDK Developer Guide for .NET