Accessing files in a web application

When working with web apps you can access files on the server as described in these topics:

You may also need to make files available for upload or download. The WebFile class is used to make files available for download or to process files that were uploaded using the File Uploader control.

Downloading files

To start a download on a WebFile, you use the System.GotoURL method to show its URL:

System.GotoURL(MyWebFile.URL)

Keep in mind that MyWebFile must remain in scope in order for the download to complete.

In general, the easiest way to create a WebFile is to use a FolderItem as the starting point:

Var localFile As FolderItem
localFile = New FolderItem("localfile.txt")

' mTextFile is a property of the web page
' so that it does not go out of scope
' while the file is downloading.
mTextFile = WebFile.Open(localFile)

System.GotoURL(mTextFile.URL)

The above code ends up loading the file from disk into memory for each session that initiates the file download. This could quickly use up a lot of memory on your web server.

A better approach is to store a single reference to the WebFile on the global App class. This single reference can be used by all sessions so that multiple copies are not created in memory.

Var localFile As FolderItem
localFile = New FolderItem("localfile.txt")

' App.TextFile is a property of App
' so that it does not go out of scope
' while the file is downloading and so that
' it can be reused by multiple sessions.
App.TextFile = WebFile.Open(localFile)

System.GotoURL(App.TextFile.URL)

The URL property gets a URL that is specific to the Session while using the same instance of the WebFile, saving RAM on the server.

Both of the above code samples are using the default method of the Opening event to load the entire file into memory. To save even more memory on your web server, you can instead have the file read directly from disk (in 64K chunks) by specifying False as the second parameter:

Var localFile As FolderItem
localFile = New FolderItem("localfile.txt")

' App.TextFile is a property of App
' so that it does not go out of scope
' while the file is downloading.
' The False parameter loads the file from
' disk in 64K chunks instead of loading it all
' into memory at once.
mTextFile = WebFile.Open(localFile, False)

System.GotoURL(App.TextFile.URL)

But an in-memory WebFile can also be useful, especially if you are creating a file to directly download.

You create a WebFile in memory and supply it with data by using the Data property:

' mTextFile is a property of the web page
mTextFile = New WebFile
mTextFile.MimeType = "text/plain"

' Ensure the browser downloads the file rather
' than trying to display it.
mTextFile.ForceDownload = True
mTextFile.FileName = "TextFile.txt"

mTextFile.Data = "Hello, world!"

' This causes the file to be downloaded
System.GotoURL(mTextFile.URL)

The above code also demonstrates the usage of the MimeType to specify the type of data contained in the WebFile and the ForceDownload property to ensure the browser always downloads the file. Some browsers may always try to display certain file types (such as text, PDF, etc), however.

Uploading files

To upload files to the server using a web app, you can use the WebFileUploader control described in File Uploader. This control allows the user to add one or more files to be uploaded. When the upload starts (by calling the Upload method), all the files are sent to the web app on the server where you can process them in the UploadFinished event handler.

Uploaded files larger than 256K are written directly to the temporary folder if it is writeable. The file is kept in memory if the temporary folder is not writeable or the file is 256K or smaller.

For files kept in memory, be aware of the maximum available RAM you have on your web server.

Once the file are uploaded, if the temporary folder is writeable the files in memory are also copied to disk and the UploadCompleted event handler is called. If the temporary folder was not writeable then all files are kept in memory.

Regardless, you must process the files in the UploadCompleted event handler in order to save them. Files in the temporary folder are deleted and ones in memory are released when the UploadCompleted event handler returns.

The code below processes each uploaded file (which is a WebUploadedFile) in memory and saves its data to an actual file on disk by using a FolderItem and BinaryStream.

Var bs As BinaryOutputStream
Var f As FolderItem

For Each file As WebUploadedFile In Files
  f = New FolderItem(file.Name)
  Try
    bs = BinaryStream.Create(f, True)
    bs.Write(file.Data)
    bs.Close
  Catch e As IOException
    ' Error, skip file
  End Try
Next

However, it is simpler and uses less memory to just call the Save method to save the file to a permanent location:

Var saveFile As FolderItem

For Each file As WebUploadedFile In Files
  saveFile = New FolderItem(file.Name)
  Try
    file.Save(saveFile)
  Catch e As IOException
    ' File Error, skip file
    Continue
  End Try
Next

See also

FolderItem, WebFile classes; File Uploader topic