XRPictureBox.ImageUrl Property

Bindable. Specifies a path to the image that the XRPictureBox control displays.

Namespace: DevExpress.XtraReports.UI

Assembly: DevExpress.XtraReports.v24.1.dll

NuGet Package: DevExpress.Reporting.Core

Declaration

C#

[DefaultValue("")]
[SRCategory(ReportStringId.CatData)]
public string ImageUrl { get; set; }

VB.NET

<SRCategory(ReportStringId.CatData)>
<DefaultValue("")>
Public Property ImageUrl As String

Property Value

Type	Default	Description
String	String.Empty	A path to the image displayed in the picture box.

Remarks

You can set the ImageUrl property in the Picture Box control’s smart tag:

Supported image formats: BMP, JPG, JPEG, GIF, TIF, TIFF, PNG, ICO, DIB, RLE, JPE, JFIF, EMF, WMF, SVG.

You cannot load physical images from the web server’s file directory. This rule is due to security considerations. To allow the “file://“ protocol in image URLs, use the AccessSettings class to apply necessary access rules.

You can assign an absolute or relative path to the ImageUrl property.

Specify an Absolute Path

An absolute path is the path to the local file or an image URL. To retrieve an image using a URL from a web server, anonymous access is used.

Specify a Relative Path

A relative path refers to the location relative to the base directory. The following table shows which folder is considered to be the base directory:

Application in Visual Studio (Design Time or Runtime)	Deployed Application
The application project directory	The application directory

Before deployment, you must configure the application to ensure that relative paths are resolved correctly. Follow the steps below that describe how to configure the application on different platforms.

Any Platform

For all resource files (image or document), do the following:

• Set the Copy to Output Directory property to Copy Always.
• Set the Build Action property to Content.

Desktop

To specify paths relative to another directory (not the application BaseDirectory), set the global DXResourceDirectory variable:

C#

// Set the resource directory to the MyResources folder in the user profile.
string dataPath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), "MyResources");
AppDomain.CurrentDomain.SetData("DXResourceDirectory", dataPath);

VB.NET

' Set the resource directory to the MyResources folder in the user profile.
Dim dataPath As String = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), "MyResources")
AppDomain.CurrentDomain.SetData("DXResourceDirectory", dataPath)

ASP.NET Web Forms & MVC

You have two options – either use the DirectoryAccessRule class or set the DXResourceDirectory global variable.

DirectoryAccessRule

• An application includes Web Reporting controls.
  Implement the following code snippet in your application to allow access to a directory that contains resources (images or documents), since Reporting controls only allow access to URLs.

  C#

  using System;
  using DevExpress.Security.Resources;
  // ...
  public class Global_asax : System.Web.HttpApplication {
  
    protected void Application_Start(object sender, EventArgs e) {
        // Set access rules to data
        string dataPath = Server.MapPath("MyResources");
        AccessSettings.StaticResources.TrySetRules(DirectoryAccessRule.Allow(dataPath));
    }
    // ...
  }
  

  VB.NET

    Imports DevExpress.Security.Resources;
    ' ...
    Public Class [Global]
    Inherits System.Web.HttpApplication
  
  Protected Sub Application_Start(ByVal sender As Object, ByVal e As EventArgs)
    ' Set access rules to data
    Dim dataPath As String = Server.MapPath("MyResources")
    AccessSettings.StaticResources.TrySetRules(DirectoryAccessRule.Allow(dataPath))
  End Sub
  ' ...
  End Class
  

• An application prints or exports reports from code and does not include Web Reporting controls.
  There is no need to set directory access rules.

DXResourceDirectory

• An application includes Web Reporting controls.
  There is no need to set this variable. Reporting controls resolve relative paths based on the application directory.

• An application prints or exports reports from code and does not contain Web Reporting controls. Use the following code snippet:

  C#

  public class Global : System.Web.HttpApplication {
  
    protected void Application_Start(object sender, EventArgs e) {
        // Set the resource directory
        string contentPath = Server.MapPath("");
        AppDomain.CurrentDomain.SetData("DXResourceDirectory", contentPath);
    }
    // ...
  }
  

  VB.NET

  Public Class [Global]
      Inherits System.Web.HttpApplication
  
    Protected Sub Application_Start(ByVal sender As Object, ByVal e As EventArgs)
      ' Set the resource directory
      Dim contentPath As String = Server.MapPath("")
      AppDomain.CurrentDomain.SetData("DXResourceDirectory", contentPath)
    End Sub
    ' ...
  End Class
  

ASP.NET Core

You have two options – either use the DirectoryAccessRule class or set the DXResourceDirectory global variable.

DirectoryAccessRule

• An application includes Web Reporting controls.
  Implement the following code snippet in your application to allow access to a directory that contains resources (images or documents), since Reporting controls only allow access to URLs.

  using DevExpress.Security.Resources;
  
  //...
  
  var app = builder.Build();
  
  // Set access rules to data
  string dataPath = System.IO.Path.Combine(contentPath, "Data");
  string dataPath2 = System.IO.Path.Combine(contentPath, "wwwroot\\Resources");
  AccessSettings.StaticResources.TrySetRules(DirectoryAccessRule.Allow(contentPath));
  AccessSettings.StaticResources.TrySetRules(DirectoryAccessRule.Allow(dataPath, dataPath2));
  
  app.Run();
  

• An application prints or exports reports from code and does not include Web Reporting controls.
  There is no need to set directory access rules.

DXResourceDirectory

• An application includes Web Reporting controls.
  There is no need to set this variable. Reporting controls resolve relative paths based on the application directory.

• An application prints or exports reports from code and does not include Web Reporting controls. Use the following code snippet:

  var app = builder.Build();
  
  // Set the resource directory
  string contentPath = env.ContentRootPath;
  AppDomain.CurrentDomain.SetData("DXResourceDirectory", contentPath);
  
  app.Run();
  

Web Report Designer

When you edit a report in the Web Report Designer, the relative path to the image is calculated based on the domain used by your application. If you switch to preview mode, the image path is calculated as described earlier in this section.

Use Expressions

The ImageUrl property is bindable. You can invoke the Expression Editor and specify an expression whose value is the path to the image:

Bind to the Report Data Source Field

Select the control in the Report Designer, click the smart tag, and expand the drop-down list in the Expression editor below the Image Source field. In the following image, the URL that specifies the image location is obtained from the PhotoPath data source field:

Click the ellipsis button to invoke the Expression Editor. Use this editor to construct an expression. For more information, review the following help topic: Bind Report Controls to Data Using Expression Bindings.

Assign an Image

If you want to store an image in the report layout (REPX file), use the XRPictureBox.ImageSource property instead of the ImageUrl property.

• If you set the ImageUrlproperty’s value, the XRPictureBox.ImageSource property is set to null (Nothing in Visual Basic).
• If you set the XRPictureBox.ImageSource property’s value, the ImageUrl property is set to Empty.

Related GitHub Examples

The following code snippet (auto-collected from DevExpress Examples) contains a reference to the ImageUrl property.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

C#

web-forms-dashboard-add-custom-information-to-exported-dashboard/CS/WebDashboard_CustomExport/Default.aspx.cs#L42

XRPictureBox icon = new XRPictureBox();
icon.ImageUrl = Server.MapPath(@"~/App_Data/Images/dxlogo.png");
icon.HeightF = 50;

VB.NET

web-forms-dashboard-add-custom-information-to-exported-dashboard/VB/WebDashboard_CustomExport/Default.aspx.vb#L41

Dim icon As New XRPictureBox()
icon.ImageUrl = Server.MapPath("~/App_Data/Images/dxlogo.png")
icon.HeightF = 50