Object metadata includes HTTP headers and user metadata. This topic describes how to set metadata when you upload an object.

Usage notes

  • In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS by using other Alibaba Cloud services in the same region as OSS, use an internal endpoint For more information about the regions and endpoints supported by OSS, see Regions and endpoints.
  • In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or STS, see Initialization.
  • To configure object metadata, you must have the oss:PutObject permission. To query object metadata, you must have the oss:GetObject permission. For more information, see Attach a custom policy to a RAM user.

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 an 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 a simple upload task, 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 operations that you can call to query the metadata of an object, see GetObjectMeta and HeadObject.