Sending E-mail When Data Changes

Let’s begin by looking at how to send a message when an engineer closes an issue. This method requires you to write code in your Issue entity’s Updated method.

To carry out this example, open the Issue table in the table designer. Click on the “Write Code” button, and select the Updated method. Now enter the code that’s shown in Listing 15-1.

Listing 15-1.  Sending E-mail When Users Update Data

VB:
File:HelpDeskVBServerUserCodeApplicationDataService.vb
  
Imports System.Net.Mail
  
Private Sub Issues_Updated(entity As Issue)
  
   ' 1 Test if the issue has changed to a closed status                          
   If entity.Details.Properties.IssueStatus.OriginalValue IsNot Nothing AndAlso
       (Not entity.Details.Properties.IssueStatus.OriginalValue.StatusDescription
           = "Closed") AndAlso
        entity.IssueStatus IsNot Nothing AndAlso
        (entity.IssueStatus.StatusDescription = "Closed") Then
  
        Dim message As New MailMessage()                                         
        message.From = New MailAddress("[email protected]")
        message.To.Add(entity.User.Email)                                        
        message.Subject = "Issue Updated"
        message.Body =
           "The status of your Issue has changed. Issue ID " & entity.Id         
  
        Dim client As New SmtpClient("relay.yourmailserver.net", 25)             
  
        'Set the details below if you need to send credentials
        'client.Credentials =
            ' new System.Net.NetworkCredential("yourUsername", "yourPassword")
        'client.UseDefaultCredentials = false
        client.Send(message)                                                     
  
    End If
  
End Sub
  
C#:
File:HelpDeskCSServerUserCodeApplicationDataService.cs
  
using System.Net.Mail;
  
partial void Issues_Updated(Issue entity)
{
    //1 Test if the issue has changed to a closed status                         
    if (entity.Details.Properties.IssueStatus.OriginalValue !=null &&
        entity.Details.Properties.IssueStatus.OriginalValue.StatusDescription
           != "Closed" &&
        entity.IssueStatus != null &&
        entity.IssueStatus.StatusDescription == "Closed")
    {
        MailMessage message = new MailMessage();                                 
        message.From = new MailAddress("[email protected]");
        message.To.Add(entity.User.Email);                                       
        message.Subject = "Issue Updated";
        message.Body =
            "The status of your Issue has changed. Issue ID " +
             entity.Id.ToString();                                               
  
        SmtpClient client = new SmtpClient("relay.yourmailserver.net", 25);      
  
        //Set the details below if you need to send credentials
        //client.Credentials = new System.Net.NetworkCredential(
        //     "yourusername", "yourpassword");
        //client.UseDefaultCredentials = false;
        client.Send(message);                                                    
    }
}

The first part of the code checks if the user has changed the issue status to closed . It does this by checking that the original status isn’t “closed,” and then tests whether or not the new status is “closed.” Next, the code uses the following objects in the System.Net.Mail namespace to send the e-mail message:

• MailMessage : This object represents an e-mail message. It allows you to set e-mail properties like the recipient address, subject, and message body. This code retrieves the e-mail address of the user that’s been assigned to the issue , and it appends the issue id to the message body .
• SmtpClient : This class represents the object that sends the e-mail. You must initialize this object with the SMTP Server URL and port number. You can optionally set authentication credentials if your server requires this. For the SMTP Server setting, you can supply either a server name or an IP address. The method that allows you to send the e-mail is called Send . There’s also a method called SendAsync that allows you to send your message asynchronously.

The MailMessage object includes several extra properties that you can set. For example, you can CC additional recipients by using a property called CC. Table 15-2 shows a full list of properties that you can use.

Making Your E-mail Code Reusable

If you want to send e-mail from several places in your application, a helper class saves you from having to duplicate your code. To create a helper class, switch your LightSwitch project to File View and create a new class in your Server project. A good place to create this class is in your UserCode folder. Name your class SMTPMailHelper, and add the code that’s shown in Listing 15-2.

Listing 15-2.  SMTP Mail Helper Class and Method

VB:
File:HelpDeskVBServerUserCodeSMTPMailHelper.vb
  
Imports System.Net
Imports System.Net.Mail
Imports System.IO
  
Public Module SmtpMailHelper
   Const SMTPServer As String = "relay.yourmailserver.net"
   Const SMTPUserId As String = "myUsername"
   Const SMTPPassword As String = "myPassword"
   Const SMTPPort As Integer = 25
  
   Public Sub SendMail(sendFrom As String,                                     
    sendTo As String,
    subject As String,
    body As String,
    attachment As Byte(),
    filename As String)
  
      Dim fromAddress As New MailAddress(sendFrom)
      Dim toAddress As New MailAddress(sendTo)
      Dim mail As New MailMessage()                                            
  
      mail.From = fromAddress
      mail.To.Add(toAddress)
      mail.Subject = subject
      mail.Body = body
      If body.ToLower().Contains("<html>") Then                                
         mail.IsBodyHtml = True                                                
      End If
  
      Dim smtp As New SmtpClient(SMTPServer, SMTPPort)
  
      If attachment IsNot Nothing AndAlso                                      
         Not String.IsNullOrEmpty(filename) Then
            Using ms As New MemoryStream(attachment)
               mail.Attachments.Add(New Attachment(ms, filename))
               smtp.Send(mail)
            End Using
      Else
         smtp.Send(mail)
      End If
  
   End Sub
  
End Module
  
C#:
File:HelpDeskCSServerUserCodeSMTPMailHelper.cs
  
using System.Net;
using System.Net.Mail;
using System.Configuration;
using System.IO;
  
namespace LightSwitchApplication.UserCode
{
   public static class SmtpMailHelper
   {
      const string SMTPServer = "relay.yourmailserver.net";
      const string SMTPUserId = "myUsername";
      const string SMTPPassword = "myPassword";
      const int SMTPPort = 25;
  
      public static void SendMail(string sendFrom,                            
        string sendTo,
        string subject,
        string body,
        byte[] attachment,
        string filename)
      {
         MailAddress fromAddress = new MailAddress(sendFrom);
         MailAddress toAddress = new MailAddress(sendTo);
         MailMessage mail = new MailMessage();                                
  
         mail.From = fromAddress;
         mail.To.Add(toAddress);
         mail.Subject = subject;
         mail.Body = body;
         if (body.ToLower().Contains("<html>"))                               
         {
            mail.IsBodyHtml = true;                                           
         }
  
         SmtpClient smtp = new SmtpClient(SMTPServer, SMTPPort);
  
         if (attachment != null && !string.IsNullOrEmpty(filename))           
         {
            using (MemoryStream ms = new MemoryStream(attachment))
            {
               mail.Attachments.Add(new Attachment(ms, filename));
               smtp.Send(mail);
            }
         }
         else
         {
            smtp.Send(mail);
         }
      }
   }
}

This class defines a method called SendMail that contains the logic that sends an SMTP mail message. You’ll find out how to call this method in Listing 15-4.

This first part of this code creates a new message by creating a new instance of a MailMessage object . It then sets the value of the sender, recipient, subject, and e-mail body properties.

The next part of the code checks if the message body contains an HTML tag . If so, it sets the format of your e-mail message to HTML . This line of code allows you to author HTML e-mails, simply by including an HTML tag at the start of your message body. The advantage of HTML is that it allows you to apply additional formatting, such as font sizes, boldification, and coloration to your e-mail message.

The code then checks if you’ve supplied a file name and attachment . If you have done so, it attaches the file to your e-mail message. The final part of this code sends your message by calling the SmtpClient object’s Send method.

If you want to use this code in multiple LightSwitch projects, you can reuse the helper class by compiling it into a separate DLL and adding a reference to it in your Server project.

Using Configuration Settings to Save Credentials

The code in Listing 15-2 hard-codes the e-mail settings such as the SMTP server, authentication credentials, and port number. These details can change over time, so it makes good sense to save these settings in a place that you can easily modify after deployment. One option is to store these settings is in a user-defined table. The AppOption table that you saw in Chapter 7 is specifically designed for this purpose. But because you’ve already seen plenty of examples of how to retrieve data from tables, you’ll now see a different approach for storing configuration settings. This method uses custom Application Settings that are defined in your Server project. After you deploy your application, you can set these values by editing your application’s Web.config file. You’ll find the Web.config file in the root of your published application.

To create these Application Settings, right-click your Server project and open the properties window for your project. Switch to the Settings tab, and create a set of application-scoped settings to store your e-mail credentials, as shown in Figure 15-2.

You can now modify the code in your helper class to use these configuration settings. Listing 15-3 highlights the changes that you would make to your SmtpMailHelper class.

Listing 15-3.  Configuration Settings Code

VB:
File:HelpDeskVBServerUserCodeSMTPMailHelper.vb
  
Imports System.Configuration
  
Private ReadOnly SMTPServer As String = My.Settings.SMTPServer
Private ReadOnly SMTPUserId As String = My.Settings.SMTPUsername
Private ReadOnly SMTPPassword As String = My.Settings.SMTPPassword
Private ReadOnly SMTPPort As Integer = My.Settings.SMTPPort
  
C#:
File:HelpDeskCSServerUserCodeSMTPMailHelper.cs
  
using System.Configuration;
  
private static readonly string SMTPServer =
        LightSwitchApplication.Properties.Settings.Default.SMTPServer;
private static readonly string SMTPUserId =
        LightSwitchApplication.Properties.Settings.Default.SMTPUsername;
private static readonly string SMTPPassword =
        LightSwitchApplication.Properties.Settings.Default.SMTPPassword;
private static readonly int SMTPPort =
        LightSwitchApplication.Properties.Settings.Default.SMTPPort;

This code uses the functionality that’s provided by .NET’s System.Configuration namespace to retrieve the application setting values. Unlike C#, VB makes it slightly easier for you to access your configuration settings by exposing your values through an object called My.Settings.

Triggering Server E-mail from an Onscreen Button on the Client

If you want to send an e-mail from a client method that’s unrelated to data, the way to do this is to create an “operation table” that allows you to mimic the steps that you performed in the earlier example. This would allow you to create a button or a link on your screen that triggers an e-mail.

The first step is to create the table that’s shown in Figure 15-3. This table contains the fields that are needed to send an e-mail, such as the recipient e-mail address, e-mail body, and subject.

When you insert a row into this table, the code in the Inserting method sends the e-mail, just like the previous example. You can therefore send a message by simply adding rows to this table. Listing 15-4 shows the code that you’ll need to add to the Inserting method for this table. This code takes advantage of the SmtpMailHelper class that you created in Listing 15-2.

Listing 15-4.  Sending E-mail by Inserting Records into the EmailOperation Table

VB:
File:HelpDeskVBServerUserCodeApplicationDataService.vb
  
Private Sub EmailOperations_Inserting(entity As EmailOperation)
  
   SmtpMailHelper.SendMail(
      entity.SenderEmail,
      entity.RecipientEmail,
      entity.Subject,
      entity.Body,
      entity.Attachment,
      entity.AttachmentFileName)
End Sub
  
C#:
File:HelpDeskCSServerUserCodeApplicationDataService.cs
  
partial void EmailOperations_Inserting (EmailOperation entity)
{
    LightSwitchApplication.UserCode.SmtpMailHelper.SendMail(
    entity.SenderEmail,
    entity.RecipientEmail,
    entity.Subject,
    entity.Body
    entity.Attachment,
    entity.AttachmentFileName);
}

VB:
File:HelpDeskVBClientUserCodeUserDetail.vb
  
Private Sub SendEmail_Execute()
  
   Using tempWorkspace As New DataWorkspace()                                                
      Dim newEmail =
          tempWorkspace.ApplicationData.EmailOperations.AddNew()                             
      With newEmail
         .RecipientEmail = User.Email
         .SenderEmail = "[email protected]"
         .Subject = SubjectProperty
         .Body = BodyProperty
      End With
  
      Try
         tempWorkspace.ApplicationData.SaveChanges()                                         
  
         ' If you want, you can write some code here to create a record in an audit table
         newEmail.Delete()                                                                   
         tempWorkspace.ApplicationData.SaveChanges()
         ShowMessageBox("Your email has been sent")
  
      Catch ex As Exception
         ShowMessageBox(ex.Message)
      End Try
  
   End Using
End Sub
   
C#:
File:HelpDeskCSClientUserCodeUserDetail.cs
  
partial void SendEmail_Execute()
{
    using (var tempWorkspace = new DataWorkspace())                                          
    {
        EmailOperation newEmail =
           tempWorkspace.ApplicationData.EmailOperations.AddNew();                           
  
        newEmail.RecipientEmail = User.Email;
        newEmail.SenderEmail = "[email protected]";
        newEmail.Subject = SubjectProperty;
        newEmail.Body = BodyProperty;
  
        try
        {
            tempWorkspace.ApplicationData.SaveChanges();                                     
  
            //If you want, you can write some code here to create a record in an audit table
            newEmail.Delete();                                                               
            tempWorkspace.ApplicationData.SaveChanges();
            this.ShowMessageBox("Your email has been sent");
  
        }
        catch (Exception ex)
        {
            this.ShowMessageBox(ex.Message);
        }
    }
}

File:HelpDeskVBHTMLClientUserCodeAddEditUser.js
  
myapp.AddEditUser.SendEmail_execute = function (screen) {
  
    var tempWorkspace = new msls.application.DataWorkspace();                    
    var newEmail = new myapp.EmailOperation(
        tempWorkspace.ApplicationData.EmailOperations);                          
  
    newEmail.RecipientEmail = screen.User.Email;                                 
    newEmail.SenderEmail = "[email protected]";
    newEmail.Subject = screen.SubjectProperty;
    newEmail.Body = screen.BodyProperty;
  
    return tempWorkspace.ApplicationData.saveChanges().then(function () {        
        newEmail.deleteEntity();
        return tempWorkspace.ApplicationData.saveChanges().then(function () {    
            msls.showMessageBox("Your email has been sent");
        });
    });
}

Sending E-mails with File Attachments

The SendMail helper method that you created in Listing 15-2 allows you to include e-mail attachments. This section shows you how to modify the Silverlight UserDetail screen to allow users to add file attachments. This example uses the Silverlight File Open dialog. You’ll remember from Chapter 7 that Silverlight file dialogs don’t work well in browser applications. You can use a custom control to overcome this obstacle, and this section shows you how. Here are the steps to create this example:

1. Open your UserDetail screen.
2. Click on the “Add Data” button, and add a local string property called FileUploadButton. Make sure to uncheck the “Is Required” check box.
3. Drag your FileUploadButton property from the Screen Member list onto your screen. LightSwitch automatically creates a TextBox control for this property. Use the drop-down list to change the control type from a TextBox to a Custom Control.
4. Open the property sheet for the FileUploadButton control, and click on the “change” link to open the Add Custom Control dialog. Set the control type to System.Windows.Controls.Button. You can refer to Chapter 11 if you want to find out more about this process.
5. Click on the “Write Code” button, and select the UserDetail_InitializeDataWorkspace method. Now enter the code that’s shown in Listing 15-7.

Listing 15-7.  Screen Code to Send E-mail Attachments

VB:
File:HelpDeskVBClientUserCodeUserDetail.vb
  
Imports System.Runtime.InteropServices.Automation
Imports Microsoft.LightSwitch.Threading
  
Private Sub UserDetail_InitializeDataWorkspace(
   saveChangesTo As List(Of Microsoft.LightSwitch.IDataService))
  
   AddHandler Me.FindControl("FileUploadButton").ControlAvailable,               
      Sub(sender As Object, e As ControlAvailableEventArgs)
  
         CType(e.Control, Button).Content = "Send Message With Attachment"       
  
         AddHandler CType(e.Control, Button).Click,                              
            Sub(sender2 As Object, e2 As RoutedEventArgs)
  
               Dim dlg As New OpenFileDialog()                                   
               If dlg.ShowDialog().GetValueOrDefault(False) = True Then
                  Dim data As Byte()
                     Using stream As FileStream = dlg.File.OpenRead()
                        data = New Byte(stream.Length - 1) {}
                        stream.Read(data, 0, data.Length)
                     End Using
  
                     Dim filename = dlg.File.Name
  
                     'send the email here
                     Me.Details.Dispatcher.BeginInvoke(                          
                        Sub()
  
                           Using dw As New DataWorkspace()
  
                              Dim newEmail =
                                 dw.ApplicationData.EmailOperations.AddNew()
                              With newEmail
                                 .RecipientEmail = User.Email
                                  .SenderEmail = "[email protected]"
                                  .Subject = SubjectProperty
                                  .Body = BodyProperty
                                  .Attachment = data
                                  .AttachmentFileName = filename
                              End With
  
                              Try
                                 dw.ApplicationData.SaveChanges()
                                 ' If you want, you can write some code here to
                                 ' create a record in an audit table
                                 newEmail.Delete()
                                 dw.ApplicationData.SaveChanges()
                              Catch ex As Exception
                                 ShowMessageBox(ex.Message)
                              End Try
                           End Using
  
                        End Sub
                     )
  
               End If
            End Sub
        End Sub
End Sub
  
C#:
File:HelpDeskCSClientUserCodeUserDetail.cs
  
using Microsoft.LightSwitch.Threading;
using System.Windows.Controls;
using System.Windows;
  
partial void UserDetail_InitializeDataWorkspace(
   List<IDataService> saveChangesTo)
{
    var control = this.FindControl("FileUploadButton");
  
    control.ControlAvailable +=                                                  
    (object sender, ControlAvailableEventArgs e) =>
    {
        var fileButton = (Button)e.Control;
        fileButton.Content = "Send Message With Attachment";                     
  
        fileButton.Click +=                                                      
            (object sender2, RoutedEventArgs e2) =>
            {
                OpenFileDialog dlg = new OpenFileDialog();                       
                if (dlg.ShowDialog().GetValueOrDefault(false) == true)
                {
                    byte[] data;
                    using (FileStream stream = dlg.File.OpenRead())
                    {
                        data = new byte[stream.Length];
                        stream.Read(data, 0, data.Length);
                    }
  
                    string filename = dlg.File.Name;
                    //send the email here
                    this.Details.Dispatcher.BeginInvoke(() =>                    
                    {
                        using (var dw = new DataWorkspace())
                        {
                            EmailOperation newEmail =
                               dw.ApplicationData.EmailOperations.AddNew();
                            newEmail.RecipientEmail = User.Email;
                            newEmail.SenderEmail = "[email protected]";
                            newEmail.Subject = SubjectProperty;
                            newEmail.Body = BodyProperty;
                            newEmail.Attachment = data;
                            newEmail.AttachmentFileName = filename;

                            try
                            {
                                dw.ApplicationData.SaveChanges();
                                //If you want, you can write some code here to
                                //create a record in an audit table
                                newEmail.Delete();
                                dw.ApplicationData.SaveChanges();
                            }
                            catch (Exception ex)
                            {
                                this.ShowMessageBox(ex.Message);
                            }
                        }
                    });
                };
        };
    };
}

Chapter 7 showed you how to open Silverlight file dialogs from a button on a desktop application’s screen. LightSwitch executes command code on the screen’s logic thread, but the code that opens the file dialog needs to run on the UI thread. This is because file dialogs are UI elements that interact with the user. In a desktop application, you can open the Silverlight file dialogs by invoking your code on the UI thread. But for browser applications that don’t run with “elevated trust,” this technique won’t work. However, in the case of a custom Silverlight button, LightSwitch executes the code that handles the click event on the UI thread. This characteristic allows you to open Silverlight file dialogs by adding your code to the method that handles your custom button’s click event.

The code in this listing accesses the underlying Silverlight custom button by obtaining an IContentItem reference and handling the ControlAvailable event . Once the code obtains a reference to the Silverlight button, it sets the button’s text and adds the code that handles the button’s click event .

The code that handles the button’s click event opens the Silverlight file open dialog and reads the content of the selected file into a byte array. The next part of the code creates a new record in the EmailOperation table, and calls the SaveChanges method to call the code that sends the e-mail. Because SaveChanges is a data operation that could take a long time to complete, the code invokes this logic on the screen’s logic thread to prevent the process from locking up the UI.

Using mailto in a Silverlight Client

Once you’ve built a mailto hyperlink, you can call it from a Silverlight application’s screen command.

To see this in action, switch your project to File View and add a reference to the System.Windows.Browser.dll assembly in your Client project. Open the UserDetail screen, and add the code that’s shown in Listing 15-11.

Listing 15-11.  Sending E-mail by Using a mailto Hyperlink

VB:
File:HelpDeskVBClientUserCodeUserDetail.vb

Public Sub OpenDefaultMailClient(
   ByVal toAddress As String,
   ByVal subject As String,
   ByVal body As String)                                                   
  
   subject = System.Uri.EscapeDataString(subject)                          
   body = System.Uri.EscapeDataString(body)
  
   Dim url As String = String.Format(
      "mailto:{0}?subject={1}&body={2}", toAddress, subject, body)         
   Dim uri As Uri = New Uri(url)
  
   If AutomationFactory.IsAvailable Then                                   
      Dim shell = AutomationFactory.CreateObject("Shell.Application")
      'shell.ShellExecute(url) if Option Strict is Off
      CompilerServices.Versioned.CallByName(
         shell, "ShellExecute", CallType.Method, url)                      
    Else
       Microsoft.LightSwitch.Threading.Dispatchers.Main.BeginInvoke(
          Sub()
             System.Windows.Browser.HtmlPage.Window.Navigate(
                uri, "_blank")                                             
          End Sub
        )
    End If
End Sub
  
C#:
File:HelpDeskCSClientUserCodeUserDetail.cs
  
public static void OpenDefaultMailClient (
    string toAddress, string subject, string body)                         
{
    subject = Uri.EscapeDataString(subject);                               
    body = Uri.EscapeDataString(body);
  
    string url = string.Format(
        "mailto:{0}?subject={1}&body={2}", toAddress, subject, body);      
    Uri uri = new Uri(url);
  
    if (AutomationFactory.IsAvailable)                                     
    {
        var shell = AutomationFactory.CreateObject("Shell.Application");
        shell.ShellExecute(url);                                           
    }
    else
    {
        Microsoft.LightSwitch.Threading.Dispatchers.Main.BeginInvoke(() =>
        {
            System.Windows.Browser.HtmlPage.Window.Navigate(
               uri, "_blank");                                             
        });
    }
}

This code defines a method called OpenDefaultMailClient that allows you to open the mail client that’s installed on the client.  If you want to call this code from multiple places, you can create a helper class in your Client project, and create the OpenDefaultMailClient method as a shared/static method within this class, just like the OutlookMailHelper class from Listing 15-9.

The OpenDefaultMailClient method allows you to supply the subject, body, and recipient address to add to your message.

When you send e-mails using this technique, you need to encode any special characters that might appear in your hyperlink. For example, the & symbol needs to be replaced with %25 because & is the character that separates the arguments in the mailto string. The code toward the top of the method encodes the Subject and Body values by calling the Uri.EscapeDataString method . The next part of the code builds the content of the mailto link .

The next line of code checks where your application is running . If it’s running on the desktop, the code uses the shell command to open the default e-mail client . Otherwise, it uses the HtmlPage object from the System.Windows.Browser namespace instead . This code needs to be invoked on the main UI thread.

The final step is to call your OpenDefaultMailClient method from a screen. To do this, add a button to your UserDetail screen and name it SendByDefaultClient. Once you’ve created this button, add the code that’s shown in Listing 15-12.

Listing 15-12.  Screen Code to Use the Default Client

VB:
File:HelpDeskVBClientUserCodeUserDetail.vb
  
Private Sub SendByDefaultClient_Execute()
    OpenDefaultMailClient(User.Email,
    SubjectProperty, BodyProperty)                                          
End Sub
  
C#:
File:HelpDeskCSClientUserCodeUserDetail.cs
  
partial void SendByDefaultClient_Execute()
{
    OpenDefaultMailClient(
        User.Email,
        SubjectProperty,
        BodyProperty);                                                      
}

This code in the SendByDefaultClient method calls the OpenDefaultMailClient method, and supplies the e-mail address, subject, and message body values that are shown on the screen . This completes this code sample, and you can now run your screen.

Using mailto in the HTML Client

The mailto technique also works in HTML client applications. In this section, you’ll find out how to apply this method to a screen that’s designed to show information about your application, such as version numbers and contact details. First, create a Browse Data Screen and leave the screen data drop-down set to “None.” Name your screen About, and add a new button to your screen. When the “Add Button” dialog appears, select the radio option to “Write my own method” and name your method EmailAdministrator. Figure 15-9 shows how your screen now looks.

Now right-click your EmailAdministrator method, click on the “Edit Execute Code” option, and add the JavaScript that’s shown in Listing 15-13.

Listing 15-13.  Sending E-mail by Using a mailto Hyperlink

File:HelpDeskVBHTMLClientUserCodeAbout.js
  
myapp.About.EmailAdministrator_execute = function (screen) {
    var emailTo = "[email protected]";                       
    var subject = "Helpdesk Mobile App Enquiry";
    var body  = "I have an enquiry about the Helpdesk App.";
  
    var url = "mailto:" + emailTo +
        "?subject=" + encodeURIComponent(subject) +                
        "&body=" + encodeURIComponent(body);
  
    document.location.href = url;                                  
};

The first part of this code creates variables to store the recipient , subject, and body values of your e-mail. In practice, you could set these values from data or local properties. The next part of the code builds the mailto URL. Notice how it calls JavaScript’s encodeURLComponent function to encode any special characters in the subject or body parts of your URL. Although there aren’t any special characters in this example, the listing includes the encodeURLComponent call to demonstrate how to carry out this task. The final piece of this code opens the URL by setting the address of the current browser page to the mailto address .

Figure 15-10 shows how the screen looks on an Android device, and illustrates how the Android mail client opens when you click on the “Email Administrator” button. It’s useful to note that this technique may not work on all mobile devices or browsers, so it’s important to test your application on your intended device.

Using AJAX from the HTML Client

The first part of this section shows you how to make AJAX (Asynchronous JavaScript and XML) calls from HTML client applications. This technique allows you to call many different types of web resources and create much more versatile applications. To demonstrate this technique, this example shows you how to create an ASP.NET handler that sends an e-mail. This handler allows you to supply e-mail address, subject, and body values. Once you’ve added your handler, the second part of this example shows you how to call it from your LightSwitch application.

To create the server-side part of this example, switch your project to “File View.” Navigate to your Server project, right-click your Web project, and add a new “Generic Handler.” Name your handler SendMail.ashx. This creates a code file that includes a method stub for the ProcessRequest method. Modify the code in this method, as shown in Listing 15-14.

Listing 15-14.  SendMail Handler Code

VB:
File:HelpDeskVBServerWebSendMail.ashx.vb
  
Sub ProcessRequest(ByVal context As HttpContext) Implements
  IHttpHandler.ProcessRequest
   '1  Is the user authenticated? Does he belong in the Manager Role?        
   'context.User.Identity.IsAuthenticated
   'context.User.IsInRole("Manager")
  
   If context.Request.Params("emailTo") IsNot Nothing AndAlso                
      context.Request.Params("subject") IsNot Nothing AndAlso
      context.Request.Params("body") IsNot Nothing Then
        Try
           Dim senderEmail As String = "[email protected]"
           SmtpMailHelper.SendMail(senderEmail,                              
              context.Request.Params("emailTo").ToString(),
              context.Request.Params("subject").ToString(),
              context.Request.Params("body").ToString(), Nothing, Nothing)
           context.Response.Write("Email Sent")
        Catch ex As Exception
           context.Response.Write(ex.Message)                                
        End Try
    Else
        context.Response.Write("EmailTo, Subject, and Body required")
    End If
End Sub
  
C#:
File:HelpDeskCSServerWebSendMail.ashx.cs
  
public void ProcessRequest(HttpContext context)
{
   //1 Is the user authenticated? Does he belong in the Manager Role?          
   //context.User.Identity.IsAuthenticated
   //context.User.IsInRole("Manager")
  
    if (context.Request.Params["emailTo"] != null &&                           
        context.Request.Params["subject"] != null &&
        context.Request.Params["body"] != null)
    {
        try
        {
            string senderEmail = "[email protected]";
            LightSwitchApplication.UserCode.SmtpMailHelper.SendMail(           
                senderEmail,
                context.Request.Params["emailTo"].ToString(),
                context.Request.Params["subject"].ToString(),
                context.Request.Params["body"].ToString(), null, null);
            context.Response.Write("Email Sent");
        }
        catch (Exception ex)
        {
            context.Response.Write(ex.Message);                                
        }
    }
    else
    {
        context.Response.Write("EmailTo, Subject, and Body required");
    }
}

This code uses the SMTPMailHelper class that’s shown in Listing 15-2, so you’ll need to create this class if you haven’t done so already.

The first part of this code includes a comment that contains the syntax that allows you to find out whether the user is authenticated or belongs in a user-defined role called “Manager” . It’s a good idea to include some access-control checks, and you’ll find more about this in Chapters 16 and 17. The next part of the code checks that the request includes the recipient e-mail address, subject, and body . If any of this data is missing, the code returns a message to the caller. Otherwise, the code sends the e-mail by calling the SMTPMailHelper class’s SendMail method . If an error occurs, the catch block returns the error to the caller.

This completes the server side code. To create the client-side code that carries out the AJAX request, open the AddEditUser screen that you created earlier. Right-click your SendEmail method, click on the “Edit Execute Code” option, and replace the code from the earlier example with the code that’s shown in Listing 15-15.

Listing 15-15.  Calling the SendEmail Handler Page via AJAX

File:HelpDeskVBHTMLClientUserCodeAddEditUser.js
  
myapp.AddEditUser.SendEmail_execute = function (screen) {
  
    return new msls.promiseOperation(function (operation) {                                
        var emailTo = screen.User.Email;
        var mailUrl = "../Web/SendMail.ashx" +                                             
            "?emailTo=" + emailTo +
            "&subject=" + encodeURIComponent(screen.SubjectProperty) +
            "&body=" + encodeURIComponent(screen.BodyProperty);
  
        $.ajax({                                                                           
            type: 'post',
            data: {},
            url: mailUrl,
            success: function success(result) {
                operation.complete();                                                      
                msls.showMessageBox(result);                                               
            } ,
            error: function err(jqXHR, textStatus, errorThrown) {                            
                operation.error(errorThrown);                                              
            }
        });
    });
}

The function that’s shown in this listing returns a promise object. It does this by wrapping the logic in a call to the msls.promiseOperation method . The promise object enables the LightSwitch runtime to place the screen into a “busy” mode, as shown in the screenshot on the left in Figure 15-11. If you didn’t wrap your code inside a call to msls.promiseOperation, your application wouldn’t show any progress indication.

The next part of this code creates the URL that points to your e-mail handler and sets the emailTo, subject, and body arguments . The next line of code calls this URL by calling jQuery’s ajax method. This method allows you to supply a function that runs when the AJAX request succeeds. The code in this function calls the operation parameter’s complete method , and then and calls the showMessageBox method to show the result from the server. If the server returns a “404 not found,” or if the process encounters some other type of error, you can handle this condition by supplying an error function to your jQuery’s ajax call . The definition of this function contains three parameters. In the event of an error, the third parameter, errorThrown, allows you to access the textual part of the HTTP status such as “Internal Server Error” or “Not found.” The code in the error function calls the operation parameter’s error method to allow the LightSwitch runtime to manage the error condition.

Note that your code must call either the operation.complete or operation.error method. If you don’t do this, LightSwitch never closes the blacked-out “busy” screen and prevents your user from carrying out any further actions in your application.

This example shows you the general pattern that allows you to make an AJAX call. To find out more, take a look at the ajax method documentation that you’ll find on the jQuery web site http://api.jquery.com/jQuery.ajax/.

Calling Web Services from the Silverlight Client

Calling web services from your Silverlight client allows you to extend the capabilities of your application. In addition to calling services that other companies or developers have created, you can also call web services to execute custom server-side code that you’ve written yourself. To demonstrate how this works, this section shows you how to create a WCF web service that sends e-mail. You’ll then learn how to consume this service from your Silverlight client.

It’s important to note that in the case of browser applications, Silverlight’s default security policy prevents it from communicating with web services that are hosted on servers other than the server from which your application originated from. To save you from having to make additional configuration changes to run your code, the following example shows you how to add a WCF web service to your application’s existing ASP.NET middle tier.

VB:
File:HelpDeskVBServerIMailService.vb
  
Imports System.ServiceModel
  
<ServiceContract()>
Public Interface IMailService
  
   <OperationContract()>
   Function SendMail(
      emailTo As String, subject As String, body As String) As String
  
End Interface
  
C#:
File:HelpDeskCSServerIMailService.cs
  
using System.ServiceModel;
  
namespace LightSwitchApplication
{
    [ServiceContract]
    public interface IMailService
    {
        [OperationContract]
        string SendMail(
           string emailTo, string subject, string body);
    }
}

VB:
File:HelpDeskVBServerMailService.svc.vb
  
Imports System.ServiceModel.Activation
  
<AspNetCompatibilityRequirements(                                               
    RequirementsMode:=AspNetCompatibilityRequirementsMode.Required)> _
Public Class MailService
   Implements IMailService
  
   Public Function SendMail (
      emailTo As String, subject As String, body As String
         ) As String Implements IMailService.SendMail
      Try
         Dim senderEmail As String = "[email protected]"
         SmtpMailHelper.SendMail(                                               
            senderEmail, emailTo, subject, body,
            Nothing, Nothing) ' optional - add email attachment here...
         Return ("Email Sent")
      Catch ex As Exception
         Return ex.Message
      End Try
    End Function
  
End Class
  
C#:
File:HelpDeskCSServerMailService.svc.cs
  
using System;
using System.ServiceModel.Activation;
  
namespace LightSwitchApplication
{
    [AspNetCompatibilityRequirements(                                            
        RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed)]
    public class MailService : IMailService
    {
        public string SendMail(
           string emailTo, string subject, string body)
       {
            try
            {
                string senderEmail = "[email protected]";
                LightSwitchApplication.UserCode.SmtpMailHelper.SendMail(         
                   senderEmail, emailTo, subject, body,
                   null, null); // optional - add email attachment here...
                return ("Email Sent");
            }
            catch (Exception ex)
            {
                return ex.Message;
            }
        }
    }
}

File:HelpDeskVBServerWeb.config
  
<system.serviceModel>
  
  <serviceHostingEnvironment
    aspNetCompatibilityEnabled="true"
    multipleSiteBindingsEnabled="true" />
  <behaviors>
    <serviceBehaviors>
      <behavior>
        <dataContractSerializer maxItemsInObjectGraph="6553600" />
        <serviceMetadata httpGetEnabled="true" />                          
      </behavior>
    </serviceBehaviors>
  </behaviors>
  <bindings>
    <webHttpBinding>
      <binding maxReceivedMessageSize="6553600" >
      </binding>
    </webHttpBinding>
    <basicHttpBinding>                                                     
      <binding name="MailServiceBinding" >
        <security mode="TransportCredentialOnly">
          <transport clientCredentialType="Windows" />
        </security>
      </binding>
    </basicHttpBinding>
  </bindings>
  
  <services>
    <service name="LightSwitchApplication.MailService">                    
      <endpoint address="MailService.svc"
          binding="basicHttpBinding"
          bindingConfiguration="MailServiceBinding"
          contract="LightSwitchApplication.IMailService" />
    </service>
  </services>
  
</system.serviceModel>

VB:
File:HelpDeskVBClientUserCodeUserDetail.vb
  
Imports Microsoft.LightSwitch.Threading
Imports System.ServiceModel
  
Private Sub SendWithWebService_Execute()
  
   Microsoft.LightSwitch.Threading.Dispatchers.Main.BeginInvoke(
      Sub()
         Dim serverUrl As Uri = System.Windows.Application.Current.Host.Source            
  
         Details.Dispatcher.BeginInvoke(
            Sub()
               'serverUrl.AbsoluteUri returns a URL like this:
               '    http://localhost:49715/Client/Web/HelpDesk.Client.xap
               Dim rootUrl =                                                              
                     serverUrl.AbsoluteUri.Substring(
                     0, serverUrl.AbsoluteUri.IndexOf("/Client/Web/"))
  
                Dim binding = New System.ServiceModel.BasicHttpBinding()
  
                'example endPoint url:
                '  endPointhttp://localhost:49715/MailService.svc
                Dim endPoint =                                                            
                   New EndpointAddress(rootUrl + "/MailService.svc ")
  
                Dim proxy As MailService.MailServiceClient =                              
                   New MailService.MailServiceClient(binding, endPoint)
  
                AddHandler proxy.SendMailCompleted,                                       
                   Sub(sender As Object, e As MailService.SendMailCompletedEventArgs)
                      Me.Details.Dispatcher.BeginInvoke(
                         Sub()
                            ShowMessageBox(e.Result.ToString())
                         End Sub
                      )
                    End Sub
  
                 proxy.SendMailAsync(User.Email, SubjectProperty, BodyProperty)           
  
              End Sub
           )
      End Sub
   )
End Sub
  
C#:
File:HelpDeskCSClientUserCodeUserDetail.cs
  
using System.ServiceModel;
using Microsoft.LightSwitch.Threading;
  
partial void SendWithWebService_Execute()
{
    Microsoft.LightSwitch.Threading.Dispatchers.Main.BeginInvoke(() =>
    {
        Uri serverUrl = System.Windows.Application.Current.Host.Source;                   
  
        this.Details.Dispatcher.BeginInvoke(() =>
        {
            //serverUrl.AbsoluteUri returns a URL like this:
            //    http://localhost:49715/Client/Web/HelpDesk.Client.xap
            string rootUrl =                                                     
               serverUrl.AbsoluteUri.Substring(
                  0, serverUrl.AbsoluteUri.IndexOf("/Client/Web/"));
  
            var binding = new System.ServiceModel.BasicHttpBinding();

            //example endPoint url:
            //   http://localhost:49715/MailService.svc/MailService.svc
            var endPoint =                                                       
               new EndpointAddress(rootUrl + "/MailService.svc/MailService.svc");
  
            MailService.MailServiceClient proxy =                                
                new MailService.MailServiceClient(binding, endPoint);
  
            proxy.SendMailCompleted +=                                           
                (object sender, MailService.SendMailCompletedEventArgs e) =>
                {
                    this.Details.Dispatcher.BeginInvoke(() =>
                    {
                        this.ShowMessageBox(e.Result.ToString());
                    });
                };
  
            proxy.SendMailAsync(User.Email, SubjectProperty, BodyProperty);      
  
        });
        }
    );
}