DocumentViewerDocument Property

Gets or sets the document to load and display in the document viewer.

This property can be set to:

  • A plain string which contains a physical/virtual path
    (e.g. "c:\SomeFolder\SomeFile.ext", "/SomeFolder/SomeFile.ext", "~/SomeFolder/SomeFile.ext").

    This is parsed as FileSystemFileProvider with PhysicalLocation. Note that virtual paths can only be resolved in a web application.
    and on Linux paths starting with "/" are physical paths and not virtual paths.

  • A plain string which contains a URL.
    (e.g. "http://example.com/SomeFolder/SomeFile.ext").

    This is parsed as UrlFileProvider. HTTP and HTTPS (SSL) links are supported.

  • A FileProvider instance created with one of the builtin file providers
    (e.g. FileSystemFileProvider, UrlFileProvider, DataUrlFileProvider, StreamFileProvider, MemoryFileProvider, DatabaseFileProvider, AssemblyResourceFileProvider, TemporaryFileProvider).

    You can also override FileProvider base class to implement your custom file provider.

  • A provider string which defines a specific file provider
    (e.g. "Type=FileSystem; File=SomeFile.ext; Location='Type=Physical; Path=c:\SomeFolder'").

The document viewer only needs a readable file provider as it only calls GetInfo and OpenRead.

Definition

Namespace: GleamTech.DocumentUltimate.AspNet.UI
Assembly: GleamTech.DocumentUltimate (in GleamTech.DocumentUltimate.dll) Version: 6.6.1
C#
public FileProvider Document { get; set; }

Property Value

FileProvider

Example

Setting document in code:

C#
//Setting a physical path string:
//See below for other path string examples.
documentViewer.Document = @"c:\SomeFolder\Document.docx";

//Setting a virtual path string:
//See below for other path string examples.
documentViewer.Document = "~/SomeFolder/Document.docx";

//Setting a URL string:
//See below for other path string examples.
documentViewer.Document = "http://example.com/SomeFolder/Document.docx";

//Setting a Data URL string:
//See below for other path string examples.
documentViewer.Document = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";

//Setting a file provider instance:
//See below for other file provider examples (UNC Path, AmazonS3, AzureBlob, Database etc.).
documentViewer.Document = new FileSystemFileProvider
{
    File = "Document.docx",
    Location = new PhysicalLocation
    {
        Path = @"c:\SomeFolder"
    }
};

//Setting a provider string:
//See below for other provider string examples (UNC Path, AmazonS3, AzureBlob, Database etc.).
documentViewer.Document = @"Type=FileSystem; File=Document.docx; Location='Type=Physical; Path=c:\SomeFolder'";

Setting document in ASPX markup:

ASPX
  <%-- 
Setting a physical path string:
See below for other path string examples.
--%>
    <GleamTech:DocumentViewerControl runat="server" 
        Width="800" 
        Height="600" 
        Document="c:\SomeFolder\Document.docx" />

  <%-- 
Setting a virtual path string:
See below for other path string examples.
--%>
    <GleamTech:DocumentViewerControl runat="server" 
        Width="800" 
        Height="600" 
        Document="~/SomeFolder/Document.docx" />

  <%-- 
Setting a URL string:
See below for other path string examples.
--%>
    <GleamTech:DocumentViewerControl runat="server" 
        Width="800" 
        Height="600" 
        Document="http://example.com/SomeFolder/Document.docx" />

  <%-- 
Setting a provider string:
See below for other provider string examples.
--%>
    <GleamTech:DocumentViewerControl runat="server" 
        Width="800" 
        Height="600" 
        Document="Type=FileSystem; File=Document.docx; Location='Type=Physical; Path=c:\SomeFolder'" />

  Notes to Callers

Below are the examples for setting a FileProvider parameter/property.

Setting a plain string:

C#
FileProvider fileProvider;

//Setting a physical path string:
//This is parsed as a FileSystemFileProvider instance with a PhysicalLocation instance.
fileProvider = @"c:\SomeFolder\SomeFile.ext";

//Setting a virtual path string:
//This is parsed as a FileSystemFileProvider instance with a PhysicalLocation instance
//and virtual path is resolved on access.
//Note that virtual paths can only be resolved in a web application
//and on Linux paths starting with "/" are physical paths and not virtual paths.
fileProvider = "~/SomeFolder/SomeFile.ext";

//Setting a URL string:
//This is parsed as a UrlFileProvider instance.
fileProvider = "http://example.com/SomeFolder/SomeFile.ext";

//Setting a Data URL string:
//This is parsed as a DataUrlFileProvider instance.
fileProvider = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";

Setting a physical file provider:

C#
FileProvider fileProvider;

//Setting a physical file provider via a FileSystemFileProvider instance:
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new PhysicalLocation
    {
        //Path can also be virtual path string like "~/SomeFolder" in a web application.
        Path = @"c:\SomeFolder"
    }
};

//Setting a physical file provider via a provider string (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Type=Physical; Path=c:\SomeFolder'";

//---------------------------------------

//Setting a physical file provider via a FileSystemFileProvider instance, to connect as a specific user:
//UserName can be specified as "Domain\User", "User@Domain" (UPN format), "Machine\User", "User" (local user).
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new PhysicalLocation
    {
        Path = @"\\server\share", //a UNC path or a local path
        UserName = "USERNAME",
        Password = "PASSWORD"
    }
};

//Setting a physical file provider via a provider string, to connect as a specific user (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Path=\\server\share; User Name=USERNAME; Password=PASSWORD'";

//---------------------------------------

//Setting a physical file provider via a FileSystemFileProvider instance, to connect as the authenticated user:
//If Windows Authentication is used in IIS for this site, location can be specified like this
//to connect as the already authenticated user: 
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new PhysicalLocation
    {
        Path = @"\\server\share", //a UNC path or a local path
        AuthenticatedUser = AuthenticatedUser.Windows
    }
};

//Setting a physical file provider via a provider string, to connect as the authenticated user:
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Path=\\server\share; Authenticated User=Windows'";

Setting an Azure Blob file provider:

C#
FileProvider fileProvider;

//Setting an Azure Blob file provider via a FileSystemFileProvider instance:
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new AzureBlobLocation
    {
        //Leave Path empty to connect to the root of the container. 
        //For connecting to subfolders, Path should be specified as a relative path (eg. "some/folder")
        //Path = "some/folder",

        //Get these values from your Azure Portal (Storage Account -> Access Keys -> Connection String)
        Container = "CONTAINER",
        AccountName = "XXX",
        AccountKey = "XXX"
    }
};

//Setting a an Azure Blob file provider via a provider string (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Type=AzureBlob; Container=CONTAINER; Account Name=XXX; Account Key=XXX'";

Setting an Amazon S3 file provider:

C#
FileProvider fileProvider;

//Setting an Amazon S3 file provider via a FileSystemFileProvider instance:
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new AmazonS3Location
    {
        //Leave Path empty to connect to the root of the bucket. 
        //For connecting to subfolders, Path should be specified as a relative path (eg. "some/folder")
        //Path = "some/folder",

        BucketName = "BUCKET",
        Region = "eu-central-1",
        AccessKeyId = "XXX",
        SecretAccessKey = "XXX",
    }
};

//Setting an Amazon S3 file provider via a provider string (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Type=AmazonS3; Bucket Name=BUCKET; Region=eu-central-1; Access Key Id=XXX; Secret Access Key=XXX'";

Setting a URL file provider:

C#
FileProvider fileProvider;

//Setting a URL file provider via a UrlFileProvider instance:
fileProvider = new UrlFileProvider
{
    File = "http://example.com/SomeFolder/SomeFile.ext"
};

//Setting a URL file provider via a provider string (same as above):
fileProvider = "Type=Url; File=http://example.com/SomeFolder/SomeFile.ext";

Setting a Data URL file provider:

C#
FileProvider fileProvider;

//Setting a Data URL file provider via a UrlFileProvider instance:
fileProvider = new DataUrlFileProvider
{
    File = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
};

//Setting a Data URL file provider via a provider string (same as above):
fileProvider = "Type=DataUrl; File='data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'";

Setting a stream file provider:

C#
FileProvider fileProvider;

//Setting a stream file provider via a StreamFileProvider instance:
fileProvider = new StreamFileProvider("SomeFolder/SomeFile.ext", yourStream);

//Optional parameters (used for detailed file info, e.g. for generating better cache keys)
fileProvider = new StreamFileProvider(
    "SomeFolder/SomeFile.ext", 
    yourStream,
    yourFileDateModified,
    yourFileSize //Provide size only if your stream is not seekable
);

Setting a memory file provider:

C#
FileProvider fileProvider;

//Setting a memory file provider via a MemoryFileProvider instance:
//Create from an existing byte array (byte[])
fileProvider = new MemoryFileProvider("SomeFolder/SomeFile.ext", yourByteArray);

//Create from an existing MemoryStream
fileProvider = new MemoryFileProvider("SomeFolder/SomeFile.ext", yourMemoryStream);

//Optional parameters (used for detailed file info, e.g. for generating better cache keys)
fileProvider = new MemoryFileProvider(
    "SomeFolder/SomeFile.ext", 
    yourMemoryStream,
    yourFileDateModified
);

//Create with empty MemoryStream
//Note that this instance should be written (filled with data via OpenWrite method) before being read
fileProvider = new MemoryFileProvider("SomeFolder/SomeFile.ext");

Setting a database file provider:

C#
FileProvider fileProvider;

//Setting a database file provider via a DatabaseFileProvider instance:
fileProvider = new DatabaseFileProvider
{
    File = "SomeFolder/SomeFile.ext",
    ConnectionString = "Data Source=(local); Initial Catalog=SomeDb; Integrated Security=SSPI",
    //ProviderName = "System.Data.SqlClient" //This is default value

    Table = "SomeTable", //Default value is "File"

    //Mandatory fields:
    KeyField = "Path", //Default value is "Id"
    ContentField = "Content",//Default value is "Content"

    //Optional fields: (used for detailed file info, e.g. for generating better cache keys)
    //NameField = "Name",
    //DateModifiedField = "DateModified",
    //SizeField = "Size",
};

//Setting a database file provider via a provider string (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = "Type=Database; File=SomeFolder/SomeFile.ext; Connection String='Data Source=(local); Initial Catalog=SomeDb; Integrated Security=SSPI'; Table=SomeTable; Key Field=Path; Content Field=Content";

//---------------------------------------

/*

Sample SQL script to create a table in the database:

CREATE TABLE [File] (
    [Id] [int] IDENTITY(1, 1) PRIMARY KEY,
    [Path] [nvarchar](500) NOT NULL UNIQUE,
    [Name] [nvarchar](100),
    [DateModified] [smalldatetime],
    [Size] [bigint],
    [Content] [varbinary](max)
);

*
*/

Setting an assembly resource file provider:

C#
FileProvider fileProvider;

//Setting an assembly resource file provider via a AssemblyResourceFileProvider instance:
fileProvider = new AssemblyResourceFileProvider
{
    File = @"SomeFolder\SomeFile.ext",
    Assembly = typeof(SomeType).Assembly,
    BaseNamespace = typeof(SomeType).Namespace
};

//Setting an assembly file provider via a provider string (same as above):
fileProvider = @"Type=AssemblyResource; File=SomeFolder\SomeFile.ext; Assembly=SomeAssembly; Base Namespace=Some.Namespace";

Setting a temporary file provider:

C#
FileProvider fileProvider;

//Setting a temporary file provider via a TemporaryFileProvider instance:
//Note that this instance should be written (filled with data via OpenWrite method) before being read
fileProvider = new TemporaryFileProvider("SomeFolder/SomeFile.ext");

Setting a custom file provider:

C#
FileProvider fileProvider;

//Setting a custom file provider:
fileProvider = new CustomFileProvider
{
    File = @"SomeFolder\SomeFile.ext",
    Parameters = new Dictionary<string, string>
    {
        {"parameter1", "value1"}
    }
};
C#
public class CustomFileProvider: FileProvider
{
    public override string File { get; set; }

    //Return true if DoGetInfo method is implemented, and false if not.
    public override bool CanGetInfo => true;

    //Return true if DoOpenRead method is implemented, and false if not.
    public override bool CanOpenRead => true;

    //Return true if DoOpenWrite method is implemented, and false if not.
    public override bool CanOpenWrite => false;

    //Return true only if File identifier is usable across processes/machines.
    public override bool CanSerialize => false;

    protected override FileProviderInfo DoGetInfo()
    {
        //Return info here which corresponds to the identifier in File property.

        //When this file provider is used in DocumentViewer:
        //This method will be called every time DocumentViewer requests a document.
        //The cache key and document format will be determined according to the info you return here.

        string fileName = File;
        DateTime dateModified = DateTime.Now;
        long size = 81920;

        return new FileProviderInfo(fileName, dateModified, size);

        //throw new NotImplementedException();
    }

    protected override Stream DoOpenRead()
    {
        //Open and return a readable stream here which corresponds to the identifier in File property.

        //You can make use of Parameters dictionary which was passed when this provider was initialized.
        //var someParameter = Parameters["parameter1"];

        //When this file provider is used in DocumentViewer:
        //This method will be called only when original input document is required, 
        //For example if DocumentViewer already did the required conversions and cached the results, 
        //it will not be called.

        return readableStream;

        //throw new NotImplementedException();
    }

    protected override Stream DoOpenWrite()
    {
        //Open and return a writable stream here which corresponds to the identifier in File property.

        throw new NotImplementedException();
    }
}

See Also