SDK Developer Guide For

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

Intel AppUp™ Software Development Kit
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

About this Document
Revision History
Document Revision Description Revision Date

Number Number
323985 001 Initial document release to support SDK V1.0 August 2010
Developer Guide for .NET technology 3

Contents
1 About this Document ................................................................ 5

1.1 Intended Audience .................................................................................5
1.2 Using this Developers Guide.....................................................................5
1.3 Conventions and Symbols ........................................................................6
1.4 Related Information ................................................................................6
2 Overview .................................................................................. 7
2.1 Intel AppUpSM Developer Program .............................................................7
2.2 SDK Contents ........................................................................................8
2.3 Development Flow ................................................................................ 10
3 Getting Started ....................................................................... 12

3.1 Hello World in C# / WPF ........................................................................ 12
3.2 Hello World in C# / WinForms ................................................................ 16
3.3 Hello World in Visual Basic / WPF ............................................................ 18
3.4 Hello World in Visual Basic / WinForms .................................................... 20
4 Advanced Information ............................................................ 23

4.1 API Levels ........................................................................................... 23
4.2 Error and Warning Handling ................................................................... 24
4.2.1 C# (WPF and WinForms) .......................................................... 25
4.2.2 Visual Basic (WPF and WinForms) .............................................. 26
4.3 Instrumentation ................................................................................... 28
4.3.1 C# (WPF and WinForms) .......................................................... 28
4.3.2 Visual Basic (WPF and WinForms) .............................................. 31
4.4 Crash Reporting ................................................................................... 33
4.4.1 Default Crash Report ............................................................... 33
4.4.2 Customizing Crash Reports ....................................................... 34
4.5 Using the Intel AppUp™ Software Debugger ............................................. 38

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

This type style
output, or part of a program example. The text appears in lowercase unless
uppercase is significant.
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.

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.

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.

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
previously for C# / WPF. The syntax for VB is different, as shown below.
Dim app As New AdpApplication(New AdpApplicationID(0x12341234, 0x56785678,

0x12341234, 0x56785678))
/ WPF.

as for C# / WPF.
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
&H11111111, &H11111111))
' Note: replace "&H11111111, &H11111111, &H11111111, &H11111111" with the
' 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
previously for C# / WPF. The syntax for VB is different, as shown below.
Dim app As New AdpApplication(New AdpApplicationId0x12341234, 0x56785678,

0x12341234, 0x56785678))
/ WPF.

as for C# / WPF.

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));
/// Note: replace "0x11111111, 0x11111111, 0x11111111, 0x11111111" with the
}
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
&H11111111, &H11111111))
' Note: replace "&H11111111, &H11111111, &H11111111, &H11111111" with the actual
application ID
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
&H11111111, &H11111111), false)
‘catches for exceptions and warnings
End try
To explicitly trigger a Begin Event, include the following BeginEvent call and catch
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
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.

Custom Crash Report Fields and Sources
Crash Report Fields My Dashboard Column Source
Application Name No (but included in Details) SDK
Application ID No (but included in Details) SDK
ModuleName Module (and in Details) Developer
LineNumber Line (and in Details) Developer
Category No (but included in Details) Developer
Message Messages (and in Details) Developer
ErrorData No (but included in Details) Developer
SDK API Level No (but included in Details) SDK
Runtime Runtime (and in Details) SDK
Runtime version No (but included in Details) SDK
OS OS (and in Details) SDK
OS version No (but included in Details) 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);
/// Note: replace "0x11111111, 0x11111111, 0x11111111, 0x11111111" with the
// 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)
' Note: replace "&H11111111, &H11111111, &H11111111, &H11111111" with the actual
application ID
‘ 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

Загружено:

Сведения о документе

Исходное описание:

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

SDK Developer Guide For

Загружено:

Авторское право:

Доступные форматы

Intel AppUp™ Software

Copyright © 2010 Intel Corporation

All Rights Reserved

Document Number: 323985-001US

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

Document Number: 323985-001US

Disclaimer and Legal Information

2 Document Number: 323985-001US

Document Revision Description Revision Date

Developer Guide for .NET technology 3

1 About this Document ................................................................ 5

3 Getting Started ....................................................................... 12

4 Advanced Information ............................................................ 23

4 Document Number: 323985-001US

1 About this Document

1.1 Intended Audience

• C# for WPF (Windows Presentation Foundation) applications

1.2 Using this Developers Guide

Developer Guide for .NET technology 5

1.3 Conventions and Symbols

Conventions and Symbols Used in This Document

Indicates an element of syntax, reserved word, keyword, filename, computer

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

1.4 Related Information

6 Document Number: 323985-001US

• Intel AppUpSM Developer Program

2.1 Intel AppUpSM Developer Program

Developer Guide for .NET technology 7

The following paragraphs summarize this interaction:

• Developers prepare their applications for submission to the Intel AppUpSM

2.2 SDK Contents

• Intel AppUpTM software libraries for C# and Visual Basic

The figure below shows the different elements of the SDK.

8 Document Number: 323985-001US

Intel AppUp™ Software Debugger

Development Process Integration

Developer Portal Integration

Developer Guide for .NET technology 9

2.3 Development Flow

• Enroll in the Intel AppUpSM Developer Program, by creating an account on the

10 Document Number: 323985-001US

Developer Guide for .NET technology 11

3.1 Hello World in C# / WPF

Step 1: Add SDK Library as Reference

Step 2: Declare SDK Namespace

12 Document Number: 323985-001US

Step 3: Insert SDK Authorization Code Using Authorized Debug ID

Developer Guide for .NET technology 13

Step 4: Test Application with Intel AppUp™ Software Debugger

14 Document Number: 323985-001US

• Visual Studio Start Debugger icon

• Visual Studio Stop Debugger icon

Step 5: Get and Swap In a Production ID

AdpApplication app = new AdpApplication(new AdpApplicationId(0x12341234,

Developer Guide for .NET technology 15

Step 6: Create an Installation Package

Step 7: Pre-Validate the Installation Package

Intel validates application packages submitted to the Intel AppUpSM Developer

Step 8: Submit the Application

3.2 Hello World in C# / WinForms

Step 1: Add SDK Library as Reference

16 Document Number: 323985-001US