Object metadata includes HTTP headers and user metadata. This topic describes how to configure, modify, and query object metadata.

Sample code

The following code provides an example on how to configure, modify, and query object metadata:

using Aliyun.OSS;
using Aliyun.OSS.Common;

// Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
var endpoint = "yourEndpoint";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access Object Storage Service (OSS) because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
var accessKeyId = "yourAccessKeyId";
var accessKeySecret = "yourAccessKeySecret";
// Specify the bucket name. 
var bucketName = "examplebucket";
// Specify the full path of the object. The full path cannot contain the bucket name. 
var objectName = "exampleobject.txt";
// Specify the full path of the local file that you want to upload. By default, if you do not specify the full path of the local file, the local file is uploaded from the path of the project to which the sample program belongs. 
var localFilename = "D:\\localpath\\examplefile.txt";
// Create an OSSClient instance. 
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
    using (var fs = File.Open(localFilename, FileMode.Open))
        // Create the metadata of the object. You can configure the HTTP headers of the object. 
        var metadata = new ObjectMetadata()
            // Specify the object type. 
            ContentType = "text/html",
            // Specify the expiration time of the cache in GMT. 
            ExpirationTime = DateTime.Parse("2025-10-12T00:00:00.000Z"),
        // Specify the length of the object content to upload. If the actual object length is greater than the specified length, the object is uploaded based on the specified length. If the object is smaller than the specified length, the object is uploaded based on the actual length. 
        metadata.ContentLength = fs.Length;
        // Specify the caching behavior of the website when the content is downloaded. 
        metadata.CacheControl = "No-Cache";
        // Set the value of mykey1 for user metadata to myval1. 
        metadata.UserMetadata.Add("mykey1", "myval1");
        // Set the value of mykey2 for user metadata to myval2. 
        metadata.UserMetadata.Add("mykey2", "myval2");
        var saveAsFilename = "Filetest123.txt";
        var contentDisposition = string.Format("attachment;filename*=utf-8''{0}", HttpUtils.EncodeUri(saveAsFilename, "utf-8"));
        // Provide a default object name when the requested content is stored as a object. 
        metadata.ContentDisposition = contentDisposition;
        // Upload the object and configure object metadata. 
        client.PutObject(bucketName, objectName, fs, metadata);
        Console.WriteLine("Put object succeeded");
        // Query object metadata. 
        var oldMeta = client.GetObjectMetadata(bucketName, objectName);
        // Configure the metadata of the destination object. 
        var newMeta = new ObjectMetadata()
            ContentType = "application/octet-stream",
            ExpirationTime = DateTime.Parse("2035-11-11T00:00:00.000Z"),
            // Specify the encoding format that is used when the object is downloaded. 
            ContentEncoding = null,
            CacheControl = ""
        // Configure user metadata. 
        newMeta.UserMetadata.Add("author", "oss");
        newMeta.UserMetadata.Add("flag", "my-flag");
        newMeta.UserMetadata.Add("mykey2", "myval2-modified-value");
        // Modify object metadata by using the ModifyObjectMeta method. 
        client.ModifyObjectMeta(bucketName, objectName, newMeta);
catch (Exception ex)
    Console.WriteLine("Put object failed, {0}", ex.Message);


  • For the complete sample code that is used to configure, modify, and query object metadata, visit GitHub.
  • For more information about the API operation that you can call to configure object metadata in simple upload, see PutObject.
  • For more information about the API operation that you can call to modify object metadata in a copy task, see CopyObject.
  • For more information about the API operation that you can call to query object metadata, see GetObjectMeta.