MailMessage.GetHtmlAndSaveRelatedFiles Method (String, VirtualMappingType, MessageFolderBehavior)

MailMessageGetHtmlAndSaveRelatedFiles Method (String, VirtualMappingType, MessageFolderBehavior)

Prepares the HTML body of the message for displaying in a web application: saves all embedded objects to a temporary location, replaces their Content-ID's with their virtual paths in the temporary location, and returns the modified HTML body as a string.

Namespace: MailBee.Mime
Assembly: MailBee.NET (in MailBee.NET.dll) Version: 12.5.0 build 687 for .NET 4.5

Syntax

Copy

public string GetHtmlAndSaveRelatedFiles(
	string virtualPath,
	VirtualMappingType mappingType,
	MessageFolderBehavior folderMode
)

Public Function GetHtmlAndSaveRelatedFiles ( 
	virtualPath As String,
	mappingType As VirtualMappingType,
	folderMode As MessageFolderBehavior
) As String

Parameters

virtualPath: Type: SystemString
The virtual path to the MailMessage.Parser.WorkingFolder of the message. If mappingType is NonWeb, this parameter value is ignored, and the developer can leave it a null reference (Nothing in Visual Basic).
mappingType: Type: MailBee.MimeVirtualMappingType
The mode of mapping physical paths to virtual paths.
folderMode: Type: MailBee.MimeMessageFolderBehavior
Specifies whether to create and use a unique message folder in the MailMessage.Parser.WorkingFolder. Ignored when mappingType value is Base64 or StaticInMemory.

Return Value

Type: String
A string containing the HTML body which is altered in such a way so that all Content-ID references (cid:) are replaced with paths to the related files as they were saved by this method.

Exceptions

Exception	Condition
MailBeeInvalidArgumentException	virtualPath is a null reference (Nothing in Visual Basic) and mappingType is not NonWeb.
MailBeeException	An error occurred and ThrowExceptions is true.

Remarks

This method can be used by the web application developer to display an HTML-formatted mail message with embedded pictures in the browser. In addition to the basic functionality provided by GetHtmlAndSaveRelatedFiles overload, this method is also capable of:

Using virtual paths instead of physical paths when referencing embedded objects in HTML body. This is important for web applications where files are saved to disk using physical paths but referenced in HTML body using virtual paths.

Creating a unique message folder in MailMessage.Parser.WorkingFolder and storing all message files there instead of placing all the files into MailMessage.Parser.WorkingFolder itself. This is important when multiple clients can use the system simultaneously and thus multiple messages can be stored in MailMessage.Parser.WorkingFolder at the same time. The name of this folder is an SHA1 digest of MessageID of the message. Since Message-ID's are unique, any particular message folder name is unique as well. Having unique subfolder for each message guarantees there will be no any collisions in multi-user environment.

Note
If folderMode is CreateOnly, the unique folder will be created and filled with the message files, but not deleted after the MailMessage object destruction. This is useful in web applications where all objects get automatically deleted once a response to the client has been generated. In this case, the message files/folder must retain after MailMessage destruction, and should only be deleted when the user has finished viewing the message (the user requested another page or the current session timed out). To remember which temporary folder to delete later, the application should save the names of the created unique folder in Session, database, or any other store which retains its data between round-trips to the server. To get this name, the developer can call MailMessage.Parser.GetMessageFolder method after the unique folder has been created during GetHtmlAndSaveRelatedFiles(String, VirtualMappingType, MessageFolderBehavior) method call.

Note

If folderMode is CreateOnly, the unique folder will be created and filled with the message files, but not deleted after the MailMessage object destruction. This is useful in web applications where all objects get automatically deleted once a response to the client has been generated. In this case, the message files/folder must retain after MailMessage destruction, and should only be deleted when the user has finished viewing the message (the user requested another page or the current session timed out). To remember which temporary folder to delete later, the application should save the names of the created unique folder in Session, database, or any other store which retains its data between round-trips to the server. To get this name, the developer can call MailMessage.Parser.GetMessageFolder method after the unique folder has been created during GetHtmlAndSaveRelatedFiles(String, VirtualMappingType, MessageFolderBehavior) method call.

Direct base64 embedding of images into the HTML body. This is the simplest method because you don't have to worry about temporary folderss, virtual paths and so on. Set mappingType to Base64 to activate this mode (other parameters will be ignored) or just use GetHtmlWithBase64EncodedRelatedFiles method instead.

mappingType specifies how physical paths to embedded pictures (and other inline attachments related in an HTML body and saved into temporary location by this method) are mapped into URI's placed into SRC elements of corresponding HTML tags.

For instance, if there is an HTML message with the following properties:

the HTML body contains <IMG SRC="cid:pic1">
the message contains the inline attachment picture.gif with ContentID (CID) pic1
the WorkingFolder is C:\Inetpub\wwwroot
the MessageID is <576201c5f939$0bfb96cb$19d717af@domain.com>

then GetHtmlAndSaveRelatedFiles("http://www.domain.com/", mappingType, MessageFolderBehavior.DoNotCreate) method call will replace cid:pic1 with the following value:

mappingType	IMG SRC value
NonWeb	C:\Inetpub\wwwroot\picture.gif
Static	http://www.domain.com/picture.gif
Dynamic	See description below
StaticInMemory	http://www.domain.com/1 (2, 3, etc)

If mappingType is Dynamic, the virtualPath parameter must point to a downloader page. Downloader page is a dynamic web page (such as an ASP.NET script) which should accept message_id and file_id parameters, grab file_id file in message_id folder and send its binary contents to the client. This allows the developer to save all inline attachments in the folder which is not directly visible from the web, and use the downloader script to push the file contents to the client. The downloader script can also check user credentials or SessionID to validate the user and do not return the attachment content if the user does not pass the authentication or session check.

message_id folder is the name of a unique message folder where all the files of the mail message are saved. If folderMode is DoNotCreate, the message files are saved directly in WorkingFolder, and message_id is an empty string.

file_id is a Filename of the inline attachment being referenced.

Thus, in Dynamic mode, MailBee replaces Content-ID (CID) with:
virtualPath + "message_id=" + SHA1Digest(Message-ID) + "&file_id=" + InlineAttachmentFilename.

For instance, GetHtmlAndSaveRelatedFiles("http://www.domain.com/download.aspx?session_id=12345&", VirtualMappingType.Dynamic, MessageFolderBehavior.CreateOnly) method call will replace cid:pic1 with http://www.domain.com/download.aspx?session_id=12345&message_id=D41D8CD98F00B204E9800998ECF8427E&file_id=picture.gif.

For more info on , refer to method.

Examples

This sample saves the email message as HTML file along with its related files (if any).

Note
You can also use SaveHtmlAndRelatedFiles(String) method to save messages as HTML pages. URI is a synonym of an URL.

Note

You can also use SaveHtmlAndRelatedFiles(String) method to save messages as HTML pages.

URI is a synonym of an URL.

Copy

using System.IO;
using MailBee;
using MailBee.Mime;

class Sample
{
    static void Main(string[] args)
    {
        // Load the message from file.
        MailMessage msg = new MailMessage();
        msg.LoadMessage(@"C:\Docs\TestMail.eml");

        // Set the folder where all related files should be saved.
        msg.Parser.WorkingFolder = @"C:\Temp";

        // Generate a web page at the specified location.
        using (StreamWriter sw = new StreamWriter(@"C:\Temp\web_page.htm", false))
        {
            sw.Write(msg.GetHtmlAndSaveRelatedFiles(@"C:\Temp",
                VirtualMappingType.NonWeb, MessageFolderBehavior.CreateAndDelete));
        }
    }
}

Imports System.IO
Imports MailBee
Imports MailBee.Mime

Module Sample
    Sub Main(ByVal args As String())
        ' Load the message from file.
        Dim msg As New MailMessage
        msg.LoadMessage("C:\Docs\TestMail.eml")

        ' Set the folder where all related files should be saved.
        msg.Parser.WorkingFolder = "C:\Temp"

        ' Generate a web page at the specified location.
        Dim sw As StreamWriter
        Try
            sw = New StreamWriter("C:\Temp\web_page.htm", False)
            sw.Write(msg.GetHtmlAndSaveRelatedFiles("C:\Temp", _
                VirtualMappingType.NonWeb, MessageFolderBehavior.CreateAndDelete))
        Finally
            If Not sw Is Nothing Then
                sw.Close()
            End If
        End Try
    End Sub
End Module

Reference

MailMessage Class

GetHtmlAndSaveRelatedFiles Overload

MailBee.Mime Namespace

MailMessageSaveHtmlAndRelatedFiles(String)

MailMessageGetHtmlWithBase64EncodedRelatedFiles

MessageParserConfigPlainToHtmlMode

MessageParserConfigWorkingFolder

VirtualMappingTypeStaticInMemory

MailMessageGetHtmlAndRelatedFilesInMemory(String)