The zip’s marker.png is a 16 × 8 blue rectangle.
dotnet add package RecursiveAI.OneDocument.SpreadsheetsRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OneDocument.Spreadsheets; using var book = Workbook.Create(); var sheet = book.Sheets.Add("Report"); var png = File.ReadAllBytes("marker.png"); sheet.AddPicture( png, "B2", 64, 32, "Blue marker"); book.SaveAs("picture.xlsx");
Writes picture.xlsx; the snippet prints nothing.
Unzip the example, then dotnet run.
Full program
The full program uses the same blue rectangle, saves the workbook and reopens it. It reads the saved drawing’s XML to show the cell anchor, dimensions and alternative text. The drawing coordinates are zero-based, so B2 is column 1, row 1.
using System.IO.Compression; using System.Xml.Linq; using RecursiveAI.OneDocument.Spreadsheets; using (var workbook = Workbook.Create()) { var sheet = workbook.Sheets.Add("Report"); int id = sheet.AddPicture(File.ReadAllBytes("marker.png"), "B2", 64, 32, "Blue marker"); workbook.SaveAs("picture.xlsx"); Console.WriteLine($"Shape id: {id}"); } using var reopened = Workbook.Open("picture.xlsx"); Console.WriteLine($"Sheet: {reopened.Sheets.Single(s => s.Name == "Report").Name}"); using var zip = ZipFile.OpenRead("picture.xlsx"); var drawingEntry = zip.Entries.Single(e => e.FullName.StartsWith("xl/drawings/drawing") && e.FullName.EndsWith(".xml")); using var drawingStream = drawingEntry.Open(); var drawing = XDocument.Load(drawingStream); XNamespace xdr = "http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing"; var from = drawing.Descendants(xdr + "from").Single(); Console.WriteLine($"Anchor: column {from.Element(xdr + "col")!.Value}, row {from.Element(xdr + "row")!.Value} (zero-based)"); var extent = drawing.Descendants(XName.Get("ext", "http://schemas.openxmlformats.org/drawingml/2006/main")).First(); Console.WriteLine($"Size: {extent.Attribute("cx")!.Value} x {extent.Attribute("cy")!.Value} EMU"); Console.WriteLine($"Alt text: {drawing.Descendants(xdr + "cNvPr").Single().Attribute("descr")!.Value}"); Console.WriteLine($"Drawing relationship: {zip.Entries.Any(e => e.FullName.StartsWith("xl/worksheets/_rels/"))}");
dotnet run prints:
Shape id: 1 Sheet: Report Anchor: column 1, row 1 (zero-based) Size: 609600 x 304800 EMU Alt text: Blue marker Drawing relationship: True
Unrecognized image bytes or a nonpositive size throw ArgumentException; a malformed cell address throws FormatException.
Variations
Keep the image’s proportions. Give only the width; the original 2:1 rectangle becomes 80 × 40 displayed pixels:
using RecursiveAI.OneDocument.Spreadsheets; using var book = Workbook.Create(); var sheet = book.Sheets.Add("Report"); int id = sheet.AddPicture(File.ReadAllBytes("marker.png"), "D4", widthPixels: 80, altText: "Blue marker"); book.SaveAs("proportional.xlsx"); Console.WriteLine($"Shape id: {id}");
Shape id: 1Related recipes
The short answer
To insert an image in an Excel worksheet in C#, read its bytes and call Worksheet.AddPicture(bytes, "B2", widthPixels, heightPixels, altText). Save the workbook as XLSX. The call returns a shape ID; it stores a media part and creates the worksheet drawing if needed.
The authoring documentation describes sizes as pixels at 96 dpi. The example uses an original PNG shipped in the download, so running it requires no external image source or image-generation package.
How do I insert an image in a worksheet?
Choose a sheet, a top-left cell and a displayed size. B2 is the anchor in the snippet at the top. The PNG is only 16 × 8 pixels, but the call asks for a displayed size of 64 × 32. Those values describe the picture’s placement, not a request to create a new raster image with more detail.
AddPicture accepts image bytes rather than a desktop bitmap object. For a file, File.ReadAllBytes supplies those bytes. If your application already holds a PNG in memory, pass that array directly. The pinned implementation recognizes PNG, JPEG, GIF and BMP headers; an arbitrary byte array is not enough.
Alternative text is a separate argument. “Blue marker” describes this example’s content. Choose text that describes your own picture instead of copying that label into a report with different content. The saved drawing stores the text in its picture properties, which the full program reads back.
The anchor is a drawing position, not a cell value. The implementation writes a twoCellAnchor with editAs="oneCell". This recipe does not claim that the image becomes an Excel in-cell image or that it will automatically resample when rows and columns change. The concrete output to expect is a drawing anchored at B2 with the requested dimensions.
How do I bulk insert an image into an Excel cell?
Use one AddPicture call per picture and provide the anchor for each call. Each call returns its own shape ID. Keep the workbook open while adding the pictures, then save after the last one. There is no bulk-image import call in this recipe, and placement is not inferred from a filename or a list of cell values.
Plan the displayed size alongside your worksheet layout. Supplying both dimensions lets you choose the exact displayed rectangle, but mismatched proportions can stretch the picture. Supplying only a width preserves the original proportions for the other dimension, as the variation demonstrates with the same blue rectangle. This is useful when inputs have different aspect ratios and should share a width without sharing a height.
Why won’t Excel let me insert an image?
For this file-writing API, check the input and arguments before diagnosing Excel itself. The pinned method refuses unrecognized image bytes, nonpositive dimensions and malformed cell addresses. It also requires a worksheet; it is not a generic insertion call for every kind of sheet. See the pinned implementation.
After saving, inspect the reopened workbook rather than assuming the input filename proves success. The full program shows the drawing anchor and extent from the actual XLSX, plus the presence of a worksheet relationship. If those values are correct but the picture looks stretched, change the requested dimensions or use the single-width variation; do not treat stretching as an image-decoding failure.