Using XFileEE with FileUpEE in .NET requires an understanding of the limitations of using a client-side ActiveX contol along with server-side ASP.NET code. XFile requires a mix of client-side and server-side code to process an upload. This C# sample will demonstrate and explain how to use this combination of code to use an ASP.NET page with code behind and an html progress indicator to perform an upload with XFileEE and FileUpEE.

Setting up the sample

1. Extract the zip file to a directory called "FileUpEEandXFileEE-CS".
2. Right click on that directory, and choose Properties.
3. On the Web Sharing tab, select "Share this folder" and click OK on the dialog that pops up.
4. Open FileUpEEandXFileEE-CS.csproj in Visual Studio .NET.
5. Add a Reference to FileUpEe.dll, FileUpEeModule.dll and MimeClient.dll, usually located in "C:\Program Files\SoftArtisans\FileUpEE\dotnet". (Make sure FileUpEe.dll and MimeClient.dll are the same versions as the FileUpEE COM dlls that are registered on the system.)
6. Edit the web.config file, changing the Version property in the FileUpEeModule tag to match the version of FileUpEeModule.dll that you added. (It currently says "Version=5.0.7.519".)
7. Copy SAXFileEE.cab to the root directory, usually located in "C:\Program Files\SoftArtisans\FileUpEE\XFile".
8. Rebuild the Project.
9. Run the sample by opening http://localhost/FileUpEEandXFileEE-CS/XFileEE-Upload.uplx in a web browser.

Basic concepts

When you post an upload with XFile, XFile is actually spawning a separate HTTP Request containing the files (and any form elements that were added to XFile). This Request is then processed by server-side code that uses FileUpEE. XFile receives this Response from the server, and then client-side code is used to display this Response. This sample returns a Response which is the entire original page but with some modifications based on the upload that took place. The original page is overwritten with this new page.

The pages in this sample

XFileEE-Upload.uplx
Contains XFile, ASP.NET WebForm server controls, and client-side JavaScript for initializing XFile and starting the upload. It also contains a hidden panel which will be used to display the results of the upload.

XFileEE-Upload.aspx.cs
Contains C# server-side code which sets the form values the first time it is loaded. It also contains the code to process the upload from XFile.

XFileProgress.html
Displays XFile's progress indicator when the upload is in progress. This page also contains client-side code that controls the start of the upload and writes the response back to the opening page.

How it works

The series of events that occurs is as follows:

1. XFileEE-Upload.uplx is loaded
   
   When you load XFileEE-Upload.uplx in a browser, the .aspx.cs code is first run on the server. An appURL string is generated, containing the URL for which XFile is supposed to post the upload to -- in our case this same page. (This appURL is not required. It's simply a technique to automatically generate a full URL to the server-side code that can be used for XFile's CurrentURL property.) The WebForm contols are then populated with some default values.
    
2. XFileEE-Upload.uplx is rendered
   
   When XFileEE-Upload.uplx is rendered in the browser, the client-side window_onload() method is run, which sets the CurrentURL property of XFile, telling it where to post the file upload to -- this same page.
    
3. User interaction
   
   Now the user can interact with the page, adding files to XFile for upload and modifying the form element values.
    
4. User starts the upload
   
   The user then clicks "Start Upload", which is a client-side HTML button. (It cannot be a WebForms button or an HTML button with run-at=server. Server-side buttons always trigger a post-back and we do not want that.) The client-side btnUpload_onclick() method is run, which adds all the form elements to XFile's form collection, opens the progress page, and disables the upload button.
    
5. Progress page opens
   
   The XFileProgress.html page is now open, and runs client-side JavaScript which links XFile's request stream to XFile's progress indicator so that accurate progress indication may occur. This client-side code then displays the progress indicator and starts the upload.
    
6. Upload is processed server-side
   
   At this point a separate instance of XFileEE-Upload.uplx is loaded on the server, receiving the request stream from XFile that contains the uploaded files and form elements. Since this page is passed a querystring value (IsUpload=true), it runs the ProcessUpload() method. (This querystring can be any name and/or value. This is just what we named it in this sample. It is simply set as part of the CurrentURL property.) ProcessUpload() instantiates FileUpEE, sets the upload directory for the files to be saved in, and then saves the files to that location. It also parses through the form elements that were sent through XFile and writes out information about them to a panel on the page which is hidden by default. You can customize this code to do whatever needs to happen with these elements (save their values to a database, etc.).
    
7. Results of the upload are returned
   
   The response from the separate instance of XFileEE-Upload.uplx that was just processed on the server will not be sent back to a client browser, since it was called by XFile. Instead, this response containing the additional upload result information is returned back to XFile. The client-side script on the progress indicator page continues where it left off (at line 20) and overwrites the entire current page in the brower window that spawned the progress indicator (our original XFileEE-Upload.uplx page) with this newly generated page containing the upload results. It does this by reading the response that XFile has received from the server and replacing original page with it. The progress window then closes itself once this is done.

Conclusion

We have demonstrated how to use the same aspx and code-behind to process an upload using XFile. We've returned the response as a complete HTML page, and overwritten the original page with it. There are some other ways to handle an upload in .NET using XFile, but the important things to remember are:

• You can use server-side WebForm or HTML contols EXCEPT for the button that will start the upload. These contols can be populated from the server-side ASP.NET code, but the controls cannot have the AutoPostBack property set to true. A postback would cause XFile to lose its current state (all the files selected would be cleared).
   
• The client-side JavaScript is really what controls the upload. An onClick event should spawn a progress indicator page which then starts the upload. This client-side JavaScript then controls what happens to the response that XFile receives from the server once the upload is complete.