Shareware Starter Kit
Microsoft Visual Studio 2005
Note: Please configure the ASP .NET Development
Server as follows before proceeding.
- Open the Solution Explorer and
highlight the SharewareService project.
- Press F4 to display the
project properties box.
- Change Use dynamic ports to false.
- Update the Port number to 3978.
The Shareware Starter Kit (SSK) enables you to integrate
important shareware management features into most .NET applications. By providing highly customizable source code
for client and server components, the SSK can be tailored to meet your specific
needs. Including the provided classes
and forms in your application will provide you the following functionality:
·
Buy
Now Web Service
·
Activate
Now Web Service
·
Product
Registration Web Service
·
Product
Feedback Web Service
·
Exception
Handling Web Service
·
Multi-Threaded
Splash Screen
Contents
Product Registration Web Service
Buy Now Web Service (PayPal integration)
Buy Now Web Service (PayPal integration)
Product Registration Web Service
Exception Handling Web Service
How the Shareware Starter Kit Works
Application User Experience and Logic Layer
Obtaining a license from the SSK Server
Server Side Exception Forwarding
Enable functionality based on product activation
state and registration status.
Send emails from Web Service for user registration
and feedback
Adding exception specific handling
Application Configuration Settings
The SSK has been incorporated into the Sample application in
order to demonstrate how simple the integration process is. Most of the functionality provided with the
SSK can be added to your application with just a few lines of code.
Database User Setup and configuration (TBD)
To build
the application
- In Solution Explorer, click Sample app to select it. Press F5 to build the application.
NOTE It may be necessary to
manually modify the Visual Studio ASP .NET Development Server port number
depending on your development environment.
If the ASP.NET debugging host icon in the system tray does not read the
same port and path as the URL property for the SskWebService
reference in the client Project please see known issues below.
The form for the application appears. You can sample the SSK features by clicking the Buy Now, Submit Feedback, Register Product,
Simulate Exception, or Verify Licensing from the buttons in the toolbar
The following scenarios provide a more detailed look into
the SSK and its features.
Product Registration Web Service
To add
registration information
- Press
F5 to build the “Sample”
application. The form for the
application appears.
- On
the toolbar, click Register Product.
- Complete
all fields and click Submit.
The database file that is part of your web project is
updated with the
The data entered is written to the local database file by
the registration web service, where it is stored for future use.
To view
registration information
- Stop
debugging in Visual Studio.
- Stop
the ASP .NET Development Server
- In Solution Explorer, double-click the
App_Data folder in the web application
project.
- Double-click
SSK.mdf. The Server
Explorer window opens.
- In
this window, double-click Tables.
- Right-click
SSK_User
and choose Show Data Table.
To add
product feedback information
- Press
F5 to build the “Sample”
application. The form for the
application appears.
- On
the toolbar, click Submit Feedback.
- Complete
all fields and click Submit.
The database file that is part of your project is updated
with the information automatically anytime a user submits the feedback
form.
The data entered is written to the local database file by
the feedback web service, where it is stored for future use.
To view
product feedback information
- Stop
debugging in Visual Studio.
- Stop
the ASP .NET Development Server
- In Solution Explorer, double-click the
App_Data folder in the web application
project.
- Double-click
SSK.mdf. The Server
Explorer window opens.
- In
this window, double-click Tables.
- Right-click
SSK_User
and choose Show Data Table.
Buy Now Web Service (PayPal integration)
You can simulate a payment authorization within the database. This allows you to test the project without
activating a PayPal account or deploying the project to a public web server.
If you are running the project on a local host within the
web server provided with Visual Studio 2005 and you have not deployed your
application to another web server, follow the instructions below. If you have deployed your web application,
see Deployment.
NOTE It may be necessary to
manually modify the Visual Studio ASP .NET Development Server port number
depending on your development environment.
If the ASP.NET debugging host icon in the system tray does not read the
same port and path as the URL property for the SskWebService
reference in the client Project please see known issues below.
To simulate
integration with Pay Pal for testing purposes
- On
the form for the application, click the Buy Now icon. The Buy Now form opens.
- On
the form, choose Purchase a product
Key and click Next. The Test Payment Service window opens.
- In
this window, click Simulate Payment
to simulate an authorized payment from PayPal. The product activates.
- Minimize
the Test Payment Service window
to view product activation status.
- On
the toolbar click the Verify
Licensing button to see the new product activation level.
For further details on the Buy Now Web Service, see
Deployment.
If you are running the project on a local host within the
web server provided with Visual Studio 2005 and you have not deployed your
application to another web server, follow the instructions below. If you have deployed your web application, see
Deployment.
- In Solution Explorer, double-click
the Web Project.
- Double-click
App_Data.
- Double-click
SSK.mdf. The Server Explorer window opens.
- In
this window, right-click SSK_Coupon.
- Locate
and select Show Table Data. The SSK_Coupon
table opens.
- Select
the blank field in the ID column. The column fields populate as NULL.
- Press
TAB and enter the date in the Created_Date
column.
- Press
TAB and enter the coupon number
in the Coupon_Number
field.
- Press
TAB and enter the ID for the
requested license level from the SSK_License_Level_Price
table.
- The Used_Date field should
remain NULL. The ID field populates automatically.
- In Solution Explorer, click Sample App to select it and press F5. The form for the application appears.
- On the
form, click the Buy Now icon. The Buy Now Form opens.
- On
the form, click “Enter a product
key.” The Activate Now form
opens.
- In
the entry field, enter the Coupon Number from step 8. Click Submit. The Activate
Now window displays the message: “Thank you. Your product is now activated.”
- Click
Finish. The Activate Now window closes, and the
product is activated.
- Click
the SSK_Coupon
table in the editor window to display it.
The Used_Date
field for the coupon is populated.
Steps to use the Shareware Starter Kit™ Service
The Shareware Starter Kit™
Service is a free service provided for you the developer! It may be used to
develop and test your application without deploying the web service portion of
the project. Right now the site is in Beta, so the service is not recommended
for production use but may be used freely for development and testing.
In order to
use the Shareware Starter Kit™ Web Service and development website follow these
steps and visit www.sharewarestarterkit.com:
·
Create
an account( Link to account
creation).
- Confirm
your email address.
- Receive your developer token in email
and configure the client libraries with the developer token. The token is
configurable in the settings of the Client project. See the documentation
for configuring your shareware application to Configure
Your Token.
- Configure the Client project web
service URL to point to the web service
- If
you have changed the name of your product in the Client project
configuration settings, please visit the Product Configuration
page and update
your product name and licensing levels as necessary.
- Submit
some test data and view it online!
The Splash Screen is set to appear by default when the “Sample”
application is launched. You can easily customize this screen by
modifying the following parameters:
- Timeout: The Timeout value is measured in ms (milliseconds). When the timer reaches a specified
value, the form will close. You can
disable the Timeout and close the form manually by passing in 0 for the
Timeout parameter.
- Fade: This constant value controls the rate of opacity
change on the form. You can change
the speeds at which the form appears and disappears by modifying this
value.
- Fader Timer Interval: The Interval value is
measured in ms (milliseconds). Each
time this value is reached, the form opacity will change according to the
value specified in Fade.
To change
the behavior of the Splash Screen
- In Solution Explorer open the Sample project
and right-click Program.cs. Locate and select View Code. The file
opens in the editor window.
- Locate
in the file the call to SplashForm.showAsyncSplash within main().
- Modify
the values in showAsyncSplash
to the desired behavior.
- In
Solution Explorer, click Sample
to select it. Press F5. The splash form for the application
appears.
Buy Now Web Service (PayPal
integration)
The Buy Now Web Service integrates with PayPal to provide an
easy to use purchase and upgrade experience for your application. This service makes it possible to deploy your
application in a shareware or trial mode.
If your user decides to purchase your application, PayPal can be used as
the payment gateway for a seamless product activation or upgrade.
For further details on the Buy Now Web Service, see Buy Now
Service setup.
For technical details on the Buy Now Web Service, see System
Architecture.
Note Use of the PayPal Buy Now feature
requires a valid PayPal seller account and the web service project must be
deployed to a web server on the public internet.
If you choose not to use PayPal as the payment gateway for
your application, the Activate Now Web Service provides an alternate method to upgrade
or activate your application. You can
enter Coupons directly into the SSK database.
Coupons enable users to retrieve a product activation key that can be entered
directly into the Activate Now Form.
For further details on the Activate Now Web Service, see Activate
Now Service setup.
For technical details on the Activate Now Web Service, see System
Architecture.
Product Registration Web Service
The Product Registration Web Service allows you to collect
user registration
For further details on the Product Registration Web Service,
see Registration Service setup.
For technical details on the Product Registration Service,
see System Architecture.
The Product Feedback Web Service allows you to collect
application feedback, comments, and requests directly from the customers as
they use your application. The
For further details on the Product Feedback Web Service, see
Feedback Service Setup.
For technical details on the Product Feedback Service, see System
Architecture.
Exception Handling Web Service
The Exception Handling Web Service allows you to collect
For further details on the Exception Handling Web Service,
see User Exercises.
For technical details on the Exception Handling Service, see
System Architecture.
The Splash Screen is a form class that can be customized to
fit your needs. The multithreaded nature
of the Splash Screen allows additional application modules to be loaded on the
main application thread in the background, while still displaying application
load progress on the Splash Screen.
For further details on the Splash Screen, see Splash Screen
Setup.
For technical details on the Exception Handling Service, see
System Architecture.
How the Shareware
Starter Kit Works
The SSK client classes are separated into two components (Figure 1).
The first component includes the Shareware Helper classes. These classes handle the interaction between
the client data store, web services proxy, and the forms that depend upon these
classes.
The second component includes the Application User
Experience and Logic Layer, which is a collection of sample forms that show how
easily the SSK functionality can be imported.
These forms include working samples of registration
Figure 1
Application User Experience and
Logic Layer
The Application User Experience and Logic Layer comprise a
number of forms that can easily be imported into your application.
Buy Now Form
- Description: This class provides the application with the Buy Now
Web Service feature.
- Dependencies: Local data store, SSK licensing, PayPal, and ServerProcessing.cs.
For further details, see helper class descriptions.
Activate Now Form
- Description: This class
provides the application with the Activate Now Web Service feature as
described above.
- Dependencies: Local data store, SSK licensing, PayPal, and ServerProcessing.cs.
For further details, see helper class descriptions.
Register Form
- Description: This class provides the application with the Product
Registration Web Service feature.
- Dependencies: Local data store and ServerProcessing.cs. For further details, see helper class
descriptions.
Feedback Form
- Description: This class provides the application with the Product
Feedback Web Service feature.
- Dependencies: ServerProcessing.cs. For further details, see helper class
descriptions.
Exception Form
- Description: This class provides the application with the Product
Exception Web Service feature.
- Dependencies: ServerProcessing.cs. For further details, see helper class
descriptions.
Splash Form
- Description: This class provides the application with the Splash
Screen feature.
- Dependencies: None.
The UI Helper Classes handle the interaction between the
client data store, web services proxy, and the forms that depend upon these
classes.
Local Data Store
- Description: This class holds persistent state-data for the SSK. It uses the System.IsolatedStorage
classes as a repository for the SSK persistent data. For more detailed
–
Current
registration status
–
Current
activation status
–
Shareware
statistics (number of days in trial mode, number of uses in trial mode, date
shareware application installed, etc.)
–
Unique
machine identification
The Local Data Store is initialized with the Get Product
Configuration web service. This web
service returns all values necessary for initial operation of the SSK. Once the Local Data Store is initialized it
will persist in Isolated Storage. If the
data store is deleted or the default location changes for Isolated Storage the
system will return to the web service and get the latest product state data
from the server and refresh the data store.
For further details, see SSK developer
extensions.
·
Dependencies: System.XML and System.IslolatedStorage.
SSK Licensing
- Description: This class interprets a digitally signed product
activation key against a known server public key. If the key is valid, a product
activation level is returned.
- Dependencies: Local Data Store, System.Encryption
(RSA).
PayPal
- Description: This class handles the interaction with PayPal which
includes generating the PayPal invoice number and launching the PayPal
Internet Explorer window.
- Dependencies: None.
ServerProcessing
- Description: This class provides the web service interface and
connection logic to all other application classes.
- Dependencies: System.web.
The Server Classes comprise web service methods, a business
logic/server algorithm layer, a database access layer, and a SQL Express
database (Figure 2).
Figure 2
The scenarios listed below walk through the steps and
interactions that take place when the client and server portions of the SSK
communicate together. Figure 3 shows these interactions and
the flow of data from client to server.
Figure 3
Scenarios
The following scenarios demonstrate how the SSK Server is
used by the SSK client.
Obtaining a license from the SSK Server
There are two ways an application can request and obtain a license
from the SSK Server.
- BuyNow: The BuyNow form uses the functionality provided in the UIHelper namespace, which depends directly on ServerProcessing.cs.
This feature forwards the user to the PayPal website to collect
payment for the requested software license. When the software license is received
via the web service, the application is automatically activated.
To track the session, the application creates a GUID that identifies
each transaction during the license request process. A LicenseRequest object
is also created, which is sent to the server when a LicenseResponse
object is requested by calling the GetLicense web
server method.
When GetLicense is called, the web
service logs the LicenseRequest information in the SSK_License_Transaction table. The web service logic layer determines if the
PayPal user web session was successful.
If a special PayPal error condition occurs, as described in
the Exception section, the SSK Server sends specific information (text) to the application. This information is displayed to inform the
user of the special PayPal error condition.
If the PayPal web session was successful, a LicenseResponse
object is returned to the client. This LicenseResponse object contains the license information
required to activate the application.
The SSK Client periodically polls for a response from GetLicense on the SSK Server. When GetLicense
responds to the SSK Client, the SSK Server implements the transactions
described earlier in this section. If GetLicense does not respond to the SSK Client, the application
receives a NULL result for the GetLicense call. The SSK Client will continue polling for a response
until it exceeds a predefined period of time (you can set the ‘BuyNowPollNumInterval’ in the App.config
file of your application).
- ActivateNow: The SSK Client application
can also be activated with a coupon.
A coupon is a string that is stored in the SSK_Coupon
table that can be used to activate the application. This string is generated by the
application developer and sent (out of band) to a third party where it
obtains a license.
When your user enters a coupon, the process is similar to
that described earlier in the BuyNow section. The application generates a LicenseRequest object but instead of creating a GUID, the application
uses the predefined coupon string as the Invoice parameter. The server then searches the SSK_Coupon table to find the entry. If the entry is found, a LicenseResponse
object is generated on the SSK Server and returned to the application.
The ActivateNow feature can also activate
the application by using the InvoiceID provided in
the confirmation email sent by PayPal.
The user provides the InvoiceID string to GetLicense. This
activation method is useful when there is a lull in the PayPal response,
delaying payment authorizations being sent to the SSK Server. The application can be activated at a later
time using the InvoiceID, preventing the user from
having to process another PayPal transaction.
Server Side Exception Forwarding
By default, the SSK Server forwards unhandled exceptions to
the application (.NET Framework default).
The application receives a SoapException which
can be parsed in order to understand the original cause of the server exception.
ServerProcessing.cs has several uses of asynchronous
web services. As noted in the .NET
Framework documentation, the server side exceptions are forwarded to the client
and found in the Error property of System.ComponentModel.AsyncCompletedEventArgs. The SSK Client uses this exception model to
Submitting Issues, User Registration
and Client-side Exceptions
Similar to the GetLicense method
described earlier, the web service methods on the server side that implement
issue submittal, user registration information, and client side exceptions are SubmitIssue, RegisterUser, and SubmitException, respectively (Figure 4). The following are
the scenarios that use these web service methods:
Figure 4
- SubmitIssue: When your users want to
provide feedback, they can complete a feedback form. The information from this form (first
and last name, email address and comments) is stored in the SSK Server
database via the SubmitIssue web service.
- RegisterUser: When your users want to register
for updates and information related to the shareware application, they can
complete a Register form. The
information from this form (first and last name, address, city, state, zip
code, phone number and email address) is stored in the SSK Server database
via the RegisterUser web service.
- SubmitException: If an unhandled error occurs
while using the shareware application, an exception is thrown that is not
caught by the client code. The SSK is
able to catch the exception by using a global exception handler. When the exception is caught, the application
creates the exception form that calls the SubmitException
web service. In the SSK Server
database you can view the exception data for all users.
The SubmitException web service
method accepts the methodName where the exception
occurred, source file name, current stack trace, exception message and the
product name.
For further details on exception handling, see the developer
exercise.
Server
Note To use PayPal
integration, the web services application must be deployed to a publicly
available web server.
To deploy
to a publicly available web server
1. Create a valid PayPal seller account
and get verified.
2. Open the Web.Config
file in the web project and update the following keys:
a. Key “FromName”
should be the name of your company.
b. Key “FromEmail”
should be the email address for company..
c. Key “SMTP” should contain the SMTP
server accessible by the web server that you are going to deploy the web
project too.
3. Create a unique developerToken
in the SSK_DevToken table. This is used to identify product settings and
allow web service access and should be a GUID.
4. Enter your product information and
developer token into the SSK_Product table.
5. Enter your required product
configuration settings into the SSK_Product_Config_Settings
table.
6. Enter your payment settings into the
SSK_Product_Config_Settings table.
7. Enter your requested license levels
into the SSK_License_Level_Price table.
8. Ensure that all connections to the
SQL express database contained within the web project you wish to deploy are
closed.
9. Ensure that all debugging instances
of the web project you wish to deploy are closed.
10. Select the web project and click website->Publish
WebSite
11. Enter the fully qualified URL of the
server that you wish to publish the web project to.
NOTE
·
The
web server must have Front Page Extensions installed, enabled, and
configured.
·
The
default framework version for this machine must also be the current v2 .NET
framework.
·
The
account running IIS must have read access to the local RSA machine key store
located at .\Documents and Settings\All Users\Application
Data\Microsoft\Crypto\RSA\MachineKeys. Usually this
is NETWORK SERVICE for Windows Server 2003 or ASPNet
for XP.
Client
1. In the Client project right click on the SskWebService reference and update the URL to the deployed
location.
2. In the Client project double click on Settings.settings to open up the settings designer. Verify that the settings match those
configured on the server database, and that the URL matches what was entered
above.
Enable functionality based on
product activation state and registration status.
The
DataStore class can be utilized to enable features
and functionality based on the state of the product. For example suppose that you want to display
a reminder for your user to register upon application load. This is simple given the following lines of
code:
//create an instance of the DataStore class
DataStore ds = new DataStore();
//if the user is not registered then display a
reminder
If (!ds.UserRegistered)
{
//display a reminder to your user here
}
Another
example would be enabling advanced features on a per license level basis. Assuming we have the DataStore
instance already created, the only line of code necessary is the following:
//if the product is activated at a premium
level as configured in the server database
If (ds.GetProductState == ProductState.Activated &&
ds.GetLicenseLevel.LicenseLevel == “Premium”)
{
//enable your premium features here
}
Using
the same logic features can be restricted when the trial length set in the
Configuration
settings elapsed.
//detect the trial period has expired
If (ds.GetProductState == ProductState.ExpiredTrial)
{
Int numberOfDaysInstalled = ds.DaysElapsedSinceInstall;
//kindly ask the user to register or activate your
product here
}
Send emails from Web Service for
user registration and feedback
You can receive new feedback comments or registration
information by running a report against the SSK Server database. But, an easier way to gather this information
is to setup an automatic email generation from the database each time a new
user registers or leaves feedback. You
can use the MailMessage and SMTPMail
classes to construct and send emails from the SSK Server.
The SendMail.cs file in the web
service project sends your user an email confirmation upon activation. The following code illustrates how this email
is created using the SendMail.Send method.
public void Send(string subject, string
body, string to)
{
aMessage = new MailMessage();
aMessage.BodyFormat = MailFormat.Html;
aMessage.From = ConfigurationSettings.AppSettings["FromEmail"];
aMessage.Cc
= "";
aMessage.Bcc = "";
aMessage.Subject
= subject;
aMessage.Body = body;
System.Web.Mail.SmtpMail.SmtpServer = ConfigurationSettings.AppSettings["SMTP"];
aMessage.To
= to;
System.Web.Mail.SmtpMail.Send(aMessage);
}
Notice this method uses the FromEmail
and SMTPServer constants that are referenced in the
configuration file.
Note The values of these constants should
have been set when you installed the SSK Server. This exercise will not work if the values are
incorrect. For further detail, see
Application Configuration Settings.
The SendMail.SendMailApprovedLicense
method prepares the confirmation email that is sent to your user upon
activation. Concurrently, the software
license is approved and delivered to the application. This method is called from SharewareService.GetLicense
in the SharewareService.asmx.cs file.
You will build two additional methods for this exercise, SendMailUserActivated and SendMailUserComments. Each will call the Send method to complete
the email transmission.
The following code, similar to the code noted earlier, needs
to be inserted into SendMail.cs.
public void SendMailUserActivated(string invoice, string
userName, string timeDate)
{
string body;
string to = "<insert your email here>";
string subject = "User "+userName+" has activated using invoiceID "+invoice+".";
body = "<table
width=\"250\"><tr><td>";
body += "A user has activated your application.";
body += "<br><br>";
body += "</td></tr>";
body += "<tr><td>";
body += "UserName: " + userName + " <br>";
body += "Invoice ID: " + invoice + "<br>";
body += "Time/Date: " + timeDate + "<br>";
body += "</td></tr>";
body += "</table>";
try
{
Send(subject, body, to);
}
catch
{
//fail gracefully if the mail doesn't send
}
}
public void SendMailUserComments(string comment, string
userName, string timeDate)
{
string body;
string to = "<insert your email here>";
string subject = "User "
+ userName + " has sent you
comments/feedback.";
body = "<table width=\"250\"><tr><td>";
body += "A user has sent you comments.";
body += "<br><br>";
body += "</td></tr>";
body += "<tr><td>";
body += "UserName: " + userName + " <br>";
body += "Time/Date: " + timeDate + "<br><br>";
body += "Comments: " + comment + "<br>";
body += "</td></tr>";
body += "</table>";
try
{
Send(subject, body, to);
}
catch
{
//fail gracefully if the mail doesn't send
}
}
Notice you must insert an email address into the local
variable. This can be accomplished in
the next exercise, where you will retrieve the email address from the Web.config file.
At what point in the web service method should these methods
be called? Locate in the code instances
of the following:
- Granted License: Your user is granted the requested license, and
the time and invoice ID are available.
Your user is guaranteed to have a license if the code inside
the IF statement executes the call to VerifyLicenseAvailableInDB
inside the SharewareService.GetLicense method.
Insert the following code in the IF block. Notice only the bolded code is new.
//send out an email to the user with their license
information
SendMail sendUserMail = new
SendMail();
sendUserMail.SendMailApprovedLicense(invoice,
response.GetAuthenticatedLicenseAsString());
sendUserMail.SendMailUserActivated(invoice,
username, DateTime.Now.ToString());
- Received Comments: Comments are received by the server and the
user name, comments and time are available.
When the server executes the SharewareService.SubmitIssue
method, the user comments are received and stored in the database.
Insert the following code at the end of this method.
SendMail sendUserMail = new
SendMail();
sendUserMail.SendMailUserComments(description,
firstName + " " + lastName,
DateTime.Now.ToString());
Adding exception specific handling
When the
client application attempts to contact the server using a web service and the
user interface is being presenting (like when the user is activating the
application using Pay Pal) an exception may be thrown by the .NET Framework.
This can
also occur when the user tries to activate the application and there is no
active network connection. In this case,
the user interface will present a relatively cryptic error to the user. The goal of this developer exercise is to
catch this exception on the client and present the user with
If you look
at the UIHelper\ServerProcessing.cs in the Client
project, the implGetLicenseCompleted
is the method that gets called back when the asynchronous call to the GetLicense web service returns. If an exception were to occur in the client
proxy code (generated by the .NET Framework) or on the server side, the
exception is passed to the client via the args
parameter to the implGetLicenseCompleted method.
We’ll use
the scenario when the client machine doesn’t have a network connection to show
how the client code reacts to this special (or perhaps not so special)
case. Now that you’ve read most of the
code in the SSK, you’ll notice that it presents the exception to the client
user in the general case. This means
that unless you handle the exception by name, the exception message will be
presented to the user. In the case of
missing network connectivity, two exceptions will be caught by the client. Namely, System.Net.WebExceptionStatus.ProxyNameResolutionFailure
followed by System.Net.WebExceptionStatus.NameResolutionFailure
(shown below). The first exception tells
the user that the proxy is misconfigured and the
second exception tells us that the name (location) that is being resolved was
not available.
System.Net.WebExceptionStatus.ProxyNameResolutionFailure
System.Net.WebExceptionStatus.NameResolutionFailure
New code to
add an exception specific handler for the GetLicense
web service method:
if (args.Error.Message ==
"The proxy name could not be resolved,
verify correct "+
"proxy configuration" )
{
ProcessingFailed(this,
new ProcessingFailedEventArgs(
"Response: ‘Please
connect to the “+
“internet or verify your proxy
configuration’"));
}
else
SoapException(args.Error.Message);
The bolded
code is the new code that needs to be added to the args.Error
handler of the implGetLicenseCompleted
method.
Now that
you have implemented an exception specific handler, you can find other
exceptions where you would like to alert the end user. Another recommended location is the HandleCompleted
method where exceptions for registration and feedback submissions can be
handled. In the above example we use a
specific Exception.Message, however, another way to
find the specific exception could be done by triggering off of the type of args.Error and args.Error.InnerException.
Application
Configuration Settings
The application configuration settings shown below are the
default settings for the Shareware Starter Kit.
These settings reside in the app.config file
of your application, and can be changed by double clicking on the Settings.settings file within the Properties folder in the
client project.
<appSettings>
<!--
The
name of the product. This is used in the
license request to the server for comparison against the available products for
sale in the SSK database. It is also
built into the authorized product activation key that the server returns upon a
successful transaction. Every time the
product activation key is validated with the licensing classes it is compared
against this value.
-->
<setting
name="ProductName" serializeAs="String">
<value>Shareware Starter
Kit</value>
</setting>
<!--
This
is used to track the developer that is using the Shareware Server. The Shareware Starter Kit Web Services log
the developer token for every transaction, allowing each transaction to be
tracked by developer. By default it's
set to a test value. This value needs to
be changed when the developer starts using the live test servers. This setting must be present in the DevToken
Table of the server project database.
-->
<setting
name="DevToken" serializeAs="String">
<value>DevIDTest</value>
</setting>
<!--
This
is the maximum number of times the client will poll the server to see if a payment
transaction has been entered into the SSK server database. This only applies when the BuyNow form is
used. When this number of polls is
exceeded the user receives a message stating that their payment transaction did
not successfully complete.
-->
<setting
name="MaxPollNum" serializeAs="String">
<value>500</value>
</setting>
<!--
This
is the time in milliseconds that the client will wait before before polling the
server again. This only applies when the
BuyNow form is used
-->
<setting
name="DefaultPollingInterval" serializeAs="String">
<value>1000</value>
</setting>
<!--
This
is the time in milliseconds that the client will wait for a response from any
web service. If no response is received
in this time then the web service call is aborted.
-->
<setting name="AbortTimerLength"
serializeAs="String">
<value>30000</value>
</setting>
<!—
The URL the users will be directed to for product
purchase and payment. Testpayment
server.aspx is a test web page set up to simulate a payment system, and should
be replaced with the live URL of the chosen payment system before deployment.
-->
<setting name="PaymentURL"
serializeAs="String">
<value>http://service.sharewarestarterkit.com/testpaymentserver.aspx</value>
</setting>
<!—
The number of days the product can be used in
trial or shareware mode.
-->
<setting name="TrialLength"
serializeAs="String">
<value>30</value>
</setting>
<!—
The payment ID that identifies you to your
payment gateway provider.
-->
<setting name="PaymentAccountID"
serializeAs="String">
<value>sales@sharewarestarterkit.com</value>
</setting>
<!—
The payment item or SKU number that identifies
your product uniquely to your payment gateway provider
-->
<setting name="PaymentItemNumber"
serializeAs="String">
<value>SSK2005</value>
</setting>
<!—
This is the URL of the hosted web page that the
payment provider should send the payment
Completion and notification message to
-->
<setting name="PaymentNotifyURL"
serializeAs="String">
<value>http://service.sharewarestarterkit.com/ipnnotify.aspx</value>
</setting>
<!—
This setting is sent to the payment provider to
determine the currency type.
-->
<setting name="PaymentCurrency"
serializeAs="String">
<value>USD</value>
</setting>
<!—
This setting determines if the debug logging for
development purposes is enabled. This
setting should be set to false before distributing the application to users.
-->
<setting name="LoggingEnabled"
serializeAs="String">
<value>True</value>
</setting>
<!—
This is the setting to the web service URL. This is automatically set by right clicking
on the properties for the web reference and updating.
-->
<setting
name="Client_SskWebService_SharewareService"
serializeAs="String">
<value>http://localhost:3978/sharewareservice/SharewareService.asmx</value>
</setting>
<!—
If the server cannot be contacted on first
execution of the project this is the default name for the first license level.
-->
<setting name="LicenseLevel_1"
serializeAs="String">
<value>Shareware</value>
</setting>
<!—
If the server cannot be contacted on first execution
of the project this setting sets the first license level as the default
shareware license level. NOTE: This
setting should be mutually exclusing between all three default license levels.
-->
<setting
name="LicenseLevelIsTrialKey_1" serializeAs="String">
<value>True</value>
</setting>
<!—
If the server cannot be contacted on first
execution of the project this is the description for the default first license
level.
-->
<setting
name="LicenseLevelDescription_1" serializeAs="String">
<value>This is the default license level for
Shareware.</value>
</setting>
<!—
If the server cannot be contacted on first
execution of the project this is the price in dollars for the default first
license level. If this is the trial key
the price should be 0.
-->
<setting name="LicenseLevelPrice_1"
serializeAs="String">
<value>0</value>
</setting>
<!—
If the server cannot be contacted on first
execution of the project this is the default name for the second license level.
-->
<setting name="LicenseLevel_2" serializeAs="String">
<value>Standard</value>
</setting>
<!—
If the server cannot be contacted on first
execution of the project this setting sets the second license level to NOT be
the default shareware license level.
NOTE: This setting should be mutually exclusing between all three
default license levels.
-->
<setting name="LicenseLevelIsTrialKey_2"
serializeAs="String">
<value>False</value>
</setting>
<!—
If the server cannot be contacted on first
execution of the project this is the description for the default second license
level.
-->
<setting name="LicenseLevelDescription_2"
serializeAs="String">
<value>This is the default license level for Standard.</value>
</setting>
<!—
If the server cannot be contacted on first
execution of the project this is the price in dollars for the default second
license level.
-->
<setting name="LicenseLevelPrice_1"
serializeAs="String">
<value>.02</value>
</setting>
<!—
If the server cannot be contacted on first
execution of the project this is the default name for the third license level.
-->
<setting name="LicenseLevel_3"
serializeAs="String">
<value>Premium</value>
</setting>
<!—
If the server cannot be contacted on first
execution of the project this setting sets the third license level to NOT be
the default shareware license level.
NOTE: This setting should be mutually exclusing between all three
default license levels.
-->
<setting name="LicenseLevelIsTrialKey_3"
serializeAs="String">
<value>False</value>
</setting>
<!—
If the server cannot be contacted on first
execution of the project this is the description for the default third license
level.
-->
<setting name="LicenseLevelDescription_3"
serializeAs="String">
<value>This is the default license level for Premium.</value>
</setting>
<!—
If the server cannot be contacted on first
execution of the project this is the price in dollars for the default third
license level.
-->
<setting name="LicenseLevelPrice_3"
serializeAs="String">
<value>.03</value>
</setting>
- When
running the solution within the VS .NET IDE please confirm that the port
number assigned to the ASP .NET Development Server matches the settings in
the Client project settings designer.
For example, in http://localhost:34052/sharewareservice
the port number is 34052. This URL
is visible by clicking on the ASP .NET Development Server tray icon once
the Web Project is started. For the
Client web services to contact the server web services, the client must
contact the services on the correct port.
You may check the Client port settings by selecting properties for
the SskWebService reference and viewing the
URL.
- If
you receive the error “An attempt to
attach an auto-named database for file %path% \ssk.mdf
failed. A database with the same name exists, or specified file cannot be
opened, or it is located on UNC share.” Move the database file in the SharewareService application to another location such
as c:\ and change the connection string in web.config
to match the new location. For
example, change “AttachDBFilename=|DataDirectory|ssk.mdf” to “c:\ssk.mdf”.
- If
you receive the error “The
underlying connection was closed: An unexpected error occurred on a send.”
When attempting to transmit information via any feature that uses web
services, check that the following function is present in Client->Web
References->SskWebService->Reference.map->Reference.cs
or Reference.vb.
C#
protected override System.Net.WebRequest
GetWebRequest(Uri uri)
{
System.Net.HttpWebRequest webRequest
=
(System.Net.HttpWebRequest) base.GetWebRequest(uri);
webRequest.KeepAlive = false;
return webRequest;
}
VB .NET
Protected Overrides
Function GetWebRequest(ByVal
uri As Uri) As _ System.Net.WebRequest
Dim webRequest As System.Net.HttpWebRequest
= CType(MyBase.GetWebRequest(uri), System.Net.HttpWebRequest)
webRequest.KeepAlive = False
Return webRequest
End Function 'GetWebRequest
If the function is not present in Reference.CS/Reference.VB
you may add it to the class.
- The
web server must have Front Page Extensions installed, enabled, and
configured for the one-click publish deployment to work properly.
- The
default framework version for the deployment web server must also be the
current v2 .NET framework.
- The
account running IIS on the deployment web server must have read access to
the local RSA machine key store located at .\Documents and Settings\All
Users\Application Data\Microsoft\Crypto\RSA\MachineKeys. Usually this is NETWORK SERVICE.
- Before
deploying a web project all connections to the SQL express database must
be closed.
- Before
deploying a web project all debugging instances of the web project must be
closed.
Coupon: A coupon is similar in function to a PayPal transaction,
but may be entered directly into the database by any payment gateway.
PayPal Integration: PayPal is used as the payment gateway. Authorized PayPal transaction
PayPal invoice: A unique identifier used on the server to relate PayPal
transaction
PayPal transaction: A transaction between the end user and PayPal
representing a valid payment confirmation.
Shareware Starter Kit (SSK): A set of Web Services, client
forms, and helper classes that provide functionality common to shareware
applications
SSK Server: The web services and database portion of the SSK
SSK Client: The sample forms and helper classes for the client.
SSK Activation: The process of sending a license request to the activation
web service and receiving an authenticated license response back.