Implementating HSS Interlink

NOTE: The documentation below is for v2.0, for v3.0 and examples demonstrating the newest features, please see the demo projects included in the source code. The basics of the server side handling and pipeline are still the same as well as the web configuration.


For the quick start sample go here 

For a sample of downloading without showing a Dialog go here

For details on how to integrate with Microsoft LightSwitch go here

To begin implementing HSS Interlink on the server side, we must first create our Upload and Download File Handlers.

HSS Interlink on the server side, works by providing built in HttpHandlers which in turn look for your implemented File Handlers, which are located via app settings in your web config.

You begin by creating a new server side class (either directly in your web site or in a separate library) and inherit from the appropriate Base File Handler.

this assumes you've already created a new Silverlight Application Project called TestClient

interlink_download11.png


For this example we will start with the download handler, then the web config changes and then finish up with the upload handler and close with the Client Side Dialogs.

Download Handler

Basically there are two methods for sending files back to the caller, SendFile and SendFileAsAttachment. But we have four distinct abstract methods to implement that allow for custom
logic to be performed for the difference protocol steps.

The steps (abstract methods) are:

  1. OpenFileInline - download the file using the standard http inline disposition
  2. OpenFileAsAttachment - download the file using the standard http attachment disposition
  3. GetSingleFile - download the file using the standard http inline disposition, but the requestor will handle the save operation
  4. GetMultipleFiles - download all the files as a single file, using the standard http inline disposition, but the requestor will handle the save operation
  5. OnError -  called when an error is encountered providing you an opportunity to log the event and return your desired HTTP Response Code


Here we define our file download handler class.
NOTE: to change the default temp folder, you can do so in your constructor.
interlink_download2.png 


OpenFileInline this method is called when a request is received and the desired output should be to
open the file directly in the browser. So, fetch the file and then call the base class method 'SendFile'.
Typically this is done with images or PDF documents.

image


OpenFileAsAttachment this method is called when a request is received and the desired output should be to
open the file in the browser and prompt the user to 'save as'. So, fetch the file and then call the base class method 'SendFileAsAttachment'.
image

GetSingleFile this method is called when a request is received and the desired output should be to
simply get the the requested file. Here we fetch the file and then call the base class method 'SendFile'.
image

GetMulitpleFiles
this method is called when a request is received and the desired output should be to
simply get the one or more requested files. Here we zip the requested files into a single file and then
call the base class method 'SendFile'.
image

IsAuthorized
before the above methods are called, we can validate the request by overriding the IsAuthorized method
to ensure the user is allowed to receive the file.
image

OnError Called when an error is encountered providing you an opportunity to log the event and return your desired HTTP Response Code
image
This wraps up implementing our server side download handler implementation.

Next we make the download handler available by creating entries in our web config, as follows...


Http Handlers

HSS Interlink by default provides the necessary HTTP Handlers to receive and process requests. You must register the HTTP Handlers by creating handler mappings in your web config.
You can also specify different handler Uri's but the HSS Interlink Client assumes FileUpload.ashx and FileDownload.ashx as the defaults.

You can reuse the Interlink Handlers by specifying a different path. You can also specify either the Sync or Async by specifying
either HSS.Interlink.Web.FileDownloadAsync or HSS.Interlink.Web.FileDownload as the handlers Type.

For IIS 7.X with Integration Mode, specify the handler in the <system.webServer> config section:

<handlers>
    <add name="FileDownload" verb="GET,POST" path="FileDownload.ashx" type="HSS.Interlink.Web.FileDownload, HSS.Interlink.Web"/>
    <add name="FileUpload" verb="GET,POST" path="FileUpload.ashx" type="HSS.Interlink.Web.FileUpload, HSS.Interlink.Web"/>
</handlers>


For IIS 7.X with Classic Mode, older versions and debugging with VStudio Dev Web Server (Cassini) use the following in the <system.web> config section

<httpHandlers>
    <add verb="GET,POST" path="FileDownload.ashx" type="HSS.Interlink.Web.FileDownload, HSS.Interlink.Web" />
    <add verb="GET,POST" path="FileUpload.ashx" type="HSS.Interlink.Web.FileUpload, HSS.Interlink.Web" />
</httpHandlers>

For more detail from MSDN see this article here 


File Handlers
You specify your custom file handler by creating an app setting entry as follows:
For a single HttpHandler as defined above, you can have one or more file handlers. From the Interlink client, you specify which file handler
should handle your download request.

NOTE: The value of the app setting should be the Qualified Assembly Type Name to ensure type resolution.

interlink_download9.png

So we've completed our download handler and are ready to begin serving download requests, now let's implement our upload handler.

Upload Handler

The upload handler has a built in protocol where by we call a few different methods to receive a file.

The protocol is:

  1. IsAuthorized - is called for each communication step within the process
  2. CheckFileExists - this method is called once in the beginning to confirm it's ok to upload this file and optional supports overwrite
  3. CreateNewFile - this method is called to begin the upload process by creating the (new empty) file
  4. AppendToFile - this method is called repeatedly to append one or more chunks of data to the file
  5. CancelUpload - this method is called once to signal the user has requested to cancel the upload, in which case you should delete the file
  6. UploadComplete - this method is called once to signal the that the client is done sending all of it's chunks and to optionally provide a final response or result
  7. OnError - called when an error is encountered providing you an opportunity to log the event and delete the local file if desired


Again we begin by defining our new File Upload Handler class.
NOTE: to change the default temp folder, you can do so in your constructor.

 

 

image

CheckFileExists here you simply confirm whether the requested file already exists
interlink_download12.png

CreateNewFile here we simply create a new empty file
interlink_download13.png

AppendToFile here we simply append the bytes received to the file (each chunk is hashed and validated with in the Interlink baseHandler)
interlink_download14.png

CancelUpload here we simply delete the file
interlink_download15.png

UploadComplete and finally the upload has completed. No action is required, but you could perform other operations here and optional provide a response or result.
Untitled

IsAuthorized again, same as with the download handler, each call is first authorized by a call to IsAuthorized
interlink_download7.png 
OnError Called when an error is encountered providing you an opportunity to log the event and delete the local file if desired

// The default value for purging is 5 minutes.
// If your uploads take longer than 5 minutes
// you WILL have to modify this to be longer
// than your anticipated longest individual
// file upload duration.

image


This wraps up implementing our server side upload handler implementation.

Same as with the download handler you make the upload handler available by creating entries in your web config as shown above.

Silverlight Client

File Download

From the Silverlight application you can download a file a few different ways:

Save to a file stream

string fileName = "serverSideFileName"; // The file to download from the server
var ddialog = new DownloadFileDialog(saveFileDialog.SafeFileName, saveFileDialog.OpenFile(), fileName);
ddialog.Show()

or multiple files

string[] fileNames = new string[] { "serverSideFileName1", "serverSideFileName2" }; // The files to download from the server
var ddialog = new DownloadFileDialog(saveFileDialog.SafeFileName, saveFileDialog.OpenFile(), fileNames);
ddialog.Show()

or using the Static Method

string fileName = "serverSideFileName";
DownloadFileDialog.DownloadFile(saveFileDialog.SafeFileName, saveFileDialog.OpenFile(), fileName);

or

string[] fileNames = new string[] { "serverSideFileName1", "serverSideFileName2" }; // The files to download from the server
DownloadFileDialog.DownloadFiles(saveFileDialog.SafeFileName, saveFileDialog.OpenFile(), fileNames);


To change the default File Handler you can specify

string fileHandler = "customFileHandler"; //must match your web config
string fileName = "serverSideFileName"; // The file to download from the server
var ddialog = new DownloadFileDialog(saveFileDialog.SafeFileName, saveFileDialog.OpenFile(), fileName);
ddialog.HandlerKey = fileHandler;
ddialog.Show()

You can change the default HttpHandler from it's default value of "/FileDownload.ashx", by setting the DownloadUri property prior to downloading

string fileHandler = "customFileHandler"; //must match your web config
string fileName = "serverSideFileName"; // The file to download from the server
var ddialog = new DownloadFileDialog(saveFileDialog.SafeFileName, saveFileDialog.OpenFile(), fileName);
ddialog.HandlerKey = fileHandler;
ddialog.DownloadUri = "/customHttphandler";_ //must match your web config
ddialog.Show()


To download a file directly to the browser you can use the static method OpenFile
DownloadFileDialog.OpenFileInline(serverSideFileName);

To download a file directly to the browser as an attachment you can also use the static method OpenFileAsAttachment
DownloadFileDialog.OpenFileAsAttachment(serverSideFileName);



File Upload


UploadFileDialog udialog = new UploadFileDialog(GetMetadata)

The GetMetadata callback allows you to specify additional information that you want to include in the upload of a file.
You access the metadata from your UploadHandler by examining the property this.Metadata.

  1. udialog.BrowseAndShow();
  2. udialog.Show();
  3. udialog.Show(files);


Sample GetMetadata Func callback
interlink_download17.png


For question or comments please use the codeplex discussion or issues list.

Last edited Jun 15, 2012 at 6:18 AM by hyspdrt, version 39

Comments

hyspdrt Jan 15, 2012 at 7:40 PM 
This could be several things, such as your URL path etc. Please use the discussion list for support better support assistance.

Can you provide more details as to your environment? This error is typical of when your web app is a sub-app - http://url.com/yourapp/fileupload.ashx versus http://ur.com/fileupload.ashx

saoudi Jan 3, 2012 at 11:48 AM 
I tried the code in my project and download the game works very well for me against the party upload generates an error:
The remote server Returned an error: NotFound.
Does anyone know where does the problem?