MediaService

The MediaService acts as a "gateway" to Umbraco data for operations which are related to media.

Browse the API documentation for IMediaService interface.

• Namespace: Umbraco.Core.Services
• Assembly: Umbraco.Core.dll

All samples in this document will require references to the following dll:

• Umbraco.Core.dll

The Umbraco.Core.dll allows you to reference the Constants classes used in the below examples.

All samples in this document will require the following using statements:

using Umbraco.Core;
using Umbraco.Core.Models;
using Umbraco.Core.Services;

Getting the service

Services property

If you wish to use use the media service in a class that inherits from one of the Umbraco base classes (eg. SurfaceController, UmbracoApiController or UmbracoAuthorizedApiController), you can access the media service through a local Services property:

IMediaService mediaService = Services.MediaService;

Dependency Injection

In other cases, you may be able to use Dependency Injection. For instance if you have registered your own class in Umbraco's dependency injection, you can specify the IMediaService interface in your constructor:

public class MyClass
{

    private IMediaService _mediaService;
    
    public MyClass(IMediaService mediaService)
    {
        _mediaService = mediaService;
    }

}

Static accessor

If neither a Services property or Dependency Injection is available, you can also reference the static Current class directly:

IMediaService mediaService = Umbraco.Core.Composing.Current.Services.MediaService;

Samples

Creating a new folder

To create a new folder at the root of the media archive, your code could look like the following:

// Initialize a new media at the root of the media archive
IMedia folder = Services.MediaService.CreateMedia("My Folder", Constants.System.Root, Constants.Conventions.MediaTypes.Folder);

// Save the folder
Services.MediaService.Save(folder);

Alternatively, you can replace the Constants in the above sample with hardcoded values.

// Initialize a new media at the root of the media archive
IMedia folder = Services.MediaService.CreateMedia("My Folder", -1, "Folder");

// Save the folder
Services.MediaService.Save(folder);

For the CreateMedia method, the first parameter is the name of the folder to be created.

The second parameter is the ID of the parent media item. Constants.System.Root is a constant defined in Umbraco with the value of -1, which is used for indicating the root of the media archive. Instead of specifying the numeric ID of the parent, you may instead specify either a Guid ID or an IMedia instance representing the parent media.

The third parameter is the alias of the Media Type. As Umbraco comes with a Folder Type by default, we can use the Constants.Conventions.MediaTypes.Folder constant to specify that the alias of the Media Type is Folder.

In addition to the three mandatory parameters as shown above, you may also specify a numeric ID for a user to which the creation of the media should be attributed. If not specified, the media will be attributed to the user with ID -1, which corresponds to the built-in "Administrator" user.

Creating a new media from an uploaded file

The example below shows how to create a new file (in this case, an image) from a HTTP upload. For illustrative purposes the example is a Razor view.

@inherits Umbraco.Web.Mvc.UmbracoViewPage<IPublishedContent>

<form method="post" enctype="multipart/form-data">
    <input type="file" name="file" />
    <input type="submit" value="Upload Image" name="submit" />
</form>

@if (IsPost)
{

    // Get a reference to the uploaded file
    HttpPostedFileBase file = Request.Files["file"];

    // Did the user actually select a file?
    if (file != null)
    {

        // TODO: Add validation to prevent malicious file uploads
        
        // Initialize a new image at the root of the media archive
        IMedia media = Services.MediaService.CreateMedia("Hello", Constants.System.Root, Constants.Conventions.MediaTypes.Image);
        
        // Set the property value (Umbraco will automatically update related properties)
        media.SetValue(Services.ContentTypeBaseServices, Constants.Conventions.Media.File, "hello.jpg", file);
        
        // Save the media
        Services.MediaService.Save(media);

    }

}

Creating a new media item from a stream

Similar to specifying a HttpPostedFileBase as shown in the example above, you can instead specify a Stream for the contents of the file that should be created.

As an example, if you have a file on disk, you can open a new stream for a file on the disk, and then create a new media for that file in Umbraco:

// Open a new stream to the file
using (Stream stream = File.OpenRead("C:/path/to/my-image.jpg"))
{

    // Initialize a new image at the root of the media archive
    IMedia media = Services.MediaService.CreateMedia("My image", Constants.System.Root, Constants.Conventions.MediaTypes.Image);

    // Set the property value (Umbraco will handle the underlying magic)
    media.SetValue(Services.ContentTypeBaseServices, Constants.Conventions.Media.File, "my-image.jpg", stream);

    // Save the media
    Services.MediaService.Save(media);

}

Again Umbraco will make sure the necessary properties are updated.