Automating smart object replacement helps you create variations of the same Photoshop template with different images. With Aspose.PSD for .NET you can load a PSD, locate smart object layers, replace their embedded contents with a new image, and save the updated document. The following examples use inline, runnable code that focuses on common cases.

Prerequisites

  • .NET 6 or later
  • NuGet: Aspose.PSD
dotnet add package Aspose.PSD

Replace the first smart object in a PSD

This example loads a PSD, finds the first SmartObjectLayer, replaces its contents with a PNG or JPEG, updates the layer, and saves the PSD and a preview PNG.

// File: Program.cs
using System;
using System.IO;
using System.Linq;
using Aspose.PSD;
using Aspose.PSD.FileFormats.Psd;
using Aspose.PSD.FileFormats.Psd.Layers.SmartObjects;
using Aspose.PSD.ImageOptions;

class Program
{
    static void Main()
    {
        var inputPsd      = "template.psd";
        var replacement   = "replacement.png"; // any raster format supported by Aspose.PSD
        var outputPsd     = "output.psd";
        var outputPreview = "output-preview.png";

        if (!File.Exists(inputPsd) || !File.Exists(replacement))
        {
            Console.WriteLine("Missing input files.");
            return;
        }

        using (var psd = (PsdImage)Image.Load(inputPsd))
        {
            // Find the first smart object layer
            var smart = psd.Layers.OfType<SmartObjectLayer>().FirstOrDefault();
            if (smart == null)
            {
                Console.WriteLine("No smart object layer found in PSD.");
            }
            else
            {
                // Load the replacement raster and replace contents
                using var newContent = (RasterImage)Image.Load(replacement);

                // Replace embedded contents and update the smart object
                smart.ReplaceContents(newContent);
                smart.UpdateModifiedContent();
            }

            // Save updated PSD
            psd.Save(outputPsd);

            // Optional preview export
            psd.Save(outputPreview, new PngOptions());
        }

        Console.WriteLine("Done.");
    }
}

Notes

  • ReplaceContents replaces the embedded content of the smart object.
  • UpdateModifiedContent refreshes the layer rendering after replacement.
  • Saving a PNG preview helps you validate the result without opening Photoshop.

Replace a smart object by layer name

Use this pattern when your template has multiple smart objects and you want to target a specific one by display name.

using System.Linq;
using Aspose.PSD;
using Aspose.PSD.FileFormats.Psd;
using Aspose.PSD.FileFormats.Psd.Layers.SmartObjects;

static void ReplaceByName(string psdPath, string layerName, string replacementPath, string outputPsd)
{
    using var psd = (PsdImage)Image.Load(psdPath);

    var smart = psd.Layers
                   .OfType<SmartObjectLayer>()
                   .FirstOrDefault(l => string.Equals(l.DisplayName, layerName, StringComparison.OrdinalIgnoreCase));

    if (smart == null)
        throw new InvalidOperationException($"Smart object layer '{layerName}' not found.");

    using var newContent = (RasterImage)Image.Load(replacementPath);

    smart.ReplaceContents(newContent);
    smart.UpdateModifiedContent();

    psd.Save(outputPsd);
}

Call it like this:

ReplaceByName("template.psd", "Product Image", "new-photo.jpg", "output.psd");

Replace all smart objects in a PSD

This example loops through all smart object layers and replaces each one with the same image. You can extend it to map each smart object to a different file.

using System.Linq;
using Aspose.PSD;
using Aspose.PSD.FileFormats.Psd;
using Aspose.PSD.FileFormats.Psd.Layers.SmartObjects;

static void ReplaceAll(string psdPath, string replacementPath, string outputPsd)
{
    using var psd = (PsdImage)Image.Load(psdPath);
    using var newContent = (RasterImage)Image.Load(replacementPath);

    var smartLayers = psd.Layers.OfType<SmartObjectLayer>().ToList();
    if (smartLayers.Count == 0)
        throw new InvalidOperationException("No smart object layers found.");

    foreach (var smart in smartLayers)
    {
        smart.ReplaceContents(newContent);
        smart.UpdateModifiedContent();
    }

    psd.Save(outputPsd);
}

Handling linked smart objects

If a smart object is linked to an external file, you can replace the link target by pointing it to a new image on disk. After updating the link, call UpdateModifiedContent.

using System.Linq;
using Aspose.PSD;
using Aspose.PSD.FileFormats.Psd;
using Aspose.PSD.FileFormats.Psd.Layers.SmartObjects;

static void ReplaceLinked(string psdPath, string newLinkedFilePath, string outputPsd)
{
    using var psd = (PsdImage)Image.Load(psdPath);

    var linked = psd.Layers
                    .OfType<SmartObjectLayer>()
                    .FirstOrDefault(l => l.IsLinked);

    if (linked == null)
        throw new InvalidOperationException("No linked smart object layer found.");

    // Point the layer to a new external file
    linked.SetLinkedFile(newLinkedFilePath);

    // Refresh layer rendering
    linked.UpdateModifiedContent();

    psd.Save(outputPsd);
}

Notes

  • Use IsLinked to detect linked smart objects.
  • SetLinkedFile updates the external path used by the layer.
  • The linked file must be a supported raster format.

Best practices

  • Image sizes: For best quality, match replacement image aspect ratio and resolution to the original smart object bounds.
  • Color management: Keep color profiles consistent across templates and replacement assets.
  • Batch automation: Reuse a loaded RasterImage when replacing many layers to reduce I/O and memory churn.
  • Validation: Export a PNG preview after replacement to confirm alignment and scaling before distributing PSDs.
  • Fallbacks: If a document has no smart objects, fail fast with a clear error or skip the file in batch mode.

With these patterns you can build reliable PSD templating pipelines that replace smart objects at scale and save updated deliverables without opening Photoshop.

More in this category