Docs

layout	docs
title	C# SDK 使用指南

C# SDK 使用指南

此 C# SDK 适用于.net framework>2.0版本，基于七牛云存储官方API 构建。使用此 SDK 构建您的网络应用程序，能让您以非常便捷地方式将数据安全地存储到七牛云存储上。无论您的网络应用是一个网站程序，还是包括从云端（服务端程序）到终端（手持设备应用）的架构的服务或应用，通过七牛云存储及其 SDK，都能让您应用程序的终端用户高速上传和下载，同时也让您的服务端更加轻盈。

安装

NuGet安装方式：

如果您的Visual Studio没有安装NuGet，请先[安装](http://docs.nuget.org/docs/start-here/installing-nuget)它,然后在项目中添加引用，使用NuGet管理程序包，在其中搜索qiniu即可。

源码下载:

git clone http://github.com/qiniu/csharp-sdk

DLL引用方式:

下载DLL文件，右键<项目>-<引用>文件夹，在弹出的菜单中点击"添加引用"选项后弹出"添加引用"对话框，选择”浏览"Qiniu.DLL文件,点击确定

项目引用方式：

下载项目文件，右键解决方案，在弹出的菜单中点击"添加"->"现有项目"，然后在弹出的对话框中选择 Qiniu.csproj"文件，点击确定。接下来与DLL引用方式类似，在"添加引用”对话框选择"项目"选项卡后选中Qiniu项目即可。

其它:

C# SDK引用了第三方的开源项目 Json.NET,因此，您需要在项目中引用它(如果使用NuGet管理dll，刚不需要手工加载Json.NET)

项目地址：http://json.codeplex.com。

初始化

配置密钥

服务端使用。

要接入七牛云存储，您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得：

在获取到 Access Key 和 Secret Key 之后，您可以在您的程序中调用如下两行代码进行初始化对接, 要确保ACCESS_KEY 和 SECRET_KEY 在调用所有七牛API服务之前均已赋值：

using Qiniu.Conf;
qiniu.conf.ACCESS_KEY = "<YOUR_APP_ACCESS_KEY>"
qiniu.conf.SECRET_KEY = "<YOUR_APP_SECRET_KEY>"

或者，编译配置文件app.conf或者web.conf等文件，添加以下配置项：

<appSettings>
    <add key="USER_AGENT" value="" />
    <add key="ACCESS_KEY" value="" />
    <add key="SECRET_KEY" value="" />
    <add key="RS_HOST" value="" />
    <add key="UP_HOST" value="" />
    <add key="RSF_HOST" value="" />
    <add key="PREFETCH_HOST" value="" />
  </appSettings>

添加完成后，在程序启动的时候调用Qiniu.Conf.Config.Init()进行初始化。

资源管理接口

服务端使用。

基本的数据结构定义：

// 摘要:
//    对bucket、key进行封装
public class EntryPath
{
	public EntryPath(string bucket, string key);

	public string Base64EncodedURI { get; }
	//
	// 摘要:
	//     七牛云存储空间名
	public string Bucket { get; }
	//
	// 摘要:
	//     文件key
	public string Key { get; }
	//
	// 摘要:
	//     bucket+ ":"+ key
	public string URI { get; }
}
// 摘要:
//     二元操作路径
public class EntryPathPair
{
	// 摘要:
	//     二元操作路径构造函数
	// 参数:
	//   bucket:
	//     源空间名称，目标空间名称
	//   keySrc:
	//     源文件key
	//   keyDest:
	//     目标文件key
	public EntryPathPair(string bucket, string keySrc, string keyDest);
	//
	// 摘要:
	//     二元操作路径构造函数
	// 参数:
	//   bucketSrc:
	//     源空间名称
	//   keySrc:
	//     源文件key
	//   bucketDest:
	//     目标空间名称
	//   keyDest:
	//     目标文件key
	public EntryPathPair(string bucketSrc, string keySrc, string bucketDest, string keyDest);

	// 摘要:
	//     bucketDest+":"+keyDest
	public string URIDest { get; }
	//
	// 摘要:
	//     bucketSrc+":"+keySrc
	public string URISrc { get; }
}

查看单个文件属性信息

//example
using Qiniu.RS

/// <summary>
/// 查看单个文件属性信息
/// </summary>
/// <param name="bucket">七牛云存储空间名</param>
/// <param name="key">文件key</param>
public static void Stat(string bucket, string key)
{
    RSClient client = new RSClient();
    Entry entry = client.Stat(new EntryPath(bucket, key));
    if (entry.OK)
    {
		Console.WriteLine("Hash: " + entry.Hash);
		Console.WriteLine("Fsize: " + entry.Fsize);
		Console.WriteLine("PutTime: " + entry.PutTime);
		Console.WriteLine("MimeType: " + entry.MimeType);
		Console.WriteLine("Customer: " + entry.Customer);
	}
	else
	{
		Console.WriteLine("Failed to Stat");
	}
}

复制单个文件

//example

/// <summary>
/// 复制单个文件
/// </summary>
/// <param name="bucketSrc">需要复制的文件所在的空间名</param>
/// <param name="keySrc">需要复制的文件key</param>
/// <param name="bucketDest">目标文件所在的空间名</param>
/// <param name="keyDest">标文件key</param>
public static void Copy(string bucketSrc, string keySrc, string bucketDest, string keyDest)
{
	RSClient client = new RSClient();
	CallRet ret = client.Copy(new EntryPathPair(bucketSrc, keySrc, bucketDest, keyDest));
	if (ret.OK)
	{
		Console.WriteLine("Copy OK");
	}
	else
	{
		Console.WriteLine("Failed to Copy");
	}
}

移动单个文件

//example

/// <summary>
/// 移动单个文件
/// </summary>
/// <param name="bucketSrc">需要移动的文件所在的空间名</param>
/// <param name="keySrc">需要移动的文件</param>
/// <param name="bucketDest">目标文件所在的空间名</param>
/// <param name="keyDest">目标文件key</param>
public static void Move(string bucketSrc, string keySrc, string bucketDest, string keyDest)
{
	Console.WriteLine("\n===> Move {0}:{1} To {2}:{3}", 
	bucketSrc, keySrc, bucketDest, keyDest);
	RSClient client = new RSClient();
	new EntryPathPair(bucketSrc, keySrc, bucketDest, keyDest);
	CallRet ret = client.Move(new EntryPathPair(bucketSrc, keySrc, bucketDest, keyDest));
	if (ret.OK)
	{
		Console.WriteLine("Move OK");
	}
	else
	{
		Console.WriteLine("Failed to Move");
	}
}

删除单个文件

//example

/// <summary>
/// 删除单个文件
/// </summary>
/// <param name="bucket">文件所在的空间名</param>
/// <param name="key">文件key</param>
public static void Delete(string bucket, string key)
{
    Console.WriteLine("\n===> Delete {0}:{1}", bucket, key);
    RSClient client = new RSClient();
    CallRet ret = client.Delete(new EntryPath(bucket, key));
    if (ret.OK)
    {
		Console.WriteLine("Delete OK");
    }
	else
	{
	Console.WriteLine("Failed to delete");
	}
}

批量操作

当您需要一次性进行多个操作时, 可以使用批量操作.

批量获取文件属性信息

//example

public static void BatchStat(string bucket, string[] keys)
{
	RSClient client = new RSClient();
	List<EntryPath> EntryPaths= new List<EntryPath>();
	foreach(string key in keys)
	{
		Console.WriteLine("\n===> Stat {0}:{1}", bucket, key);
		EntryPaths.Add(new EntryPath(bucket,key));
	}
	client.BatchStat(EntryPaths.ToArray()); 
}

批量复制文件

//example

public static void BatchCopy(string bucket, string[] keys)
{
	List<EntryPathPair> pairs = new List<EntryPathPair>();
	foreach (string key in keys)
	{
		EntryPathPair entry = new EntryPathPair(bucket, key, Guid.NewGuid().ToString());
		pairs.Add(entry);
	}
	RSClient client = new RSClient();
	client.BatchCopy(pairs.ToArray());
}

批量移动文件

//example

public static void BatchMove(string bucket, string[] keys)
{
	List<EntryPathPair> pairs = new List<EntryPathPair>();
	foreach (string key in keys)
	{
		EntryPathPair entry = new EntryPathPair(bucket, key, Guid.NewGuid().ToString());
		pairs.Add(entry);
	}
	RSClient client = new RSClient();
	client.BatchMove(pairs.ToArray());
}

批量删除文件

//example

public static void BatchDelete(string bucket, string[] keys)
{
	RSClient client = new RSClient();
	List<EntryPath> EntryPaths = new List<EntryPath>();
	foreach (string key in keys)
	{
		Console.WriteLine("\n===> Stat {0}:{1}", bucket, key);
		EntryPaths.Add(new EntryPath(bucket, key));
	}
	client.BatchDelete(EntryPaths.ToArray());
}

资源列表

服务端使用。

资源列表接口允许用户列出空间下的所有文件信息。使用资源列表接口如果引入Qiniu.RSF命名空间。

	using Qiniu.RSF;
	RSFClient client = new RSFClient();
	client.listPrifix("<bucketName>", "<prefix>", "<marker>", 500);

或者,

public static void List (string bucket)
{
	RSF.RSFClient rsf = new Qiniu.RSF.RSFClient(bucket);
	rsf.Prefix = "test";
	rsf.Limit = 100;
	List<DumpItem> items;
	while ((items=rsf.Next())!=null)
	{
		//todo
	}
}

上传下载接口

服务端或客户端使用。

上传策略

PutPolicy类用于定制上传策略，关于上传策略完整的说明，请参考上传策略（PutPolicy）。

uptoken 实际上是用 AccessKey/SecretKey对上传策略进行数字签名的字符串,用于上传接口。

string bucketName = "test";
PutPolicy put = new PutPolicy(bucketName);
string uptoken = put.Token();

文件上传

注意：如果您只是想要上传已存在您电脑本地或者是服务器上的文件到七牛云存储，可以直接使用七牛提供的 qrsync 上传工具。文件上传有两种方式，一种是以普通方式直传文件，简称普通上传，另一种方式是断点续上传，断点续上传在网络条件很一般的情况下也能有出色的上传速度，而且对大文件的传输非常友好。

普通上传

普通上传的接口在 qiniu.io 里，如下：

上传本地文件

/// <summary>
/// 上传文件测试
/// </summary>
/// <param name="bucket"></param>
/// <param name="key"></param>
/// <param name="fname"></param>
public static void PutFile(string bucket, string key, string fname)
{
	var policy = new PutPolicy(bucket, 3600);
	string upToken = policy.Token();
	PutExtra extra = new PutExtra ();
	IOClient client = new IOClient();
	client.PutFile(upToken, key, fname, extra);
}

注意： key必须采用utf8编码，如使用非utf8编码访问七牛云存储将反馈错误

断点续上传

上传本地文件,示例如下:

public static void ResumablePutFile(string bucket, string key, string fname)
{
	Console.WriteLine("\n===> ResumablePutFile {0}:{1} fname:{2}", bucket, key, fname);
	PutPolicy policy = new PutPolicy(bucket, 3600);
	string upToken = policy.Token();
	Settings setting = new Settings();
	ResumablePutExtra extra = new ResumablePutExtra();
	ResumablePut client = new ResumablePut(setting, extra);
	client.PutFile(upToken, fname, Guid.NewGuid().ToString());
}

ResumablePut采用分快上传，各快之间采用并行上传,可以通过注册ResumablePutExtra以下两个事件监听当前上传进度以及成功情况：

public event EventHandler<PutNotifyEvent> Notify;
public event EventHandler<PutNotifyErrorEvent> NotifyErr;

文件下载

七牛云存储上的资源下载分为公有资源下载和私有资源下载。

私有（private）是 Bucket（空间）的一个属性，一个私有 Bucket 中的资源为私有资源，私有资源不可匿名下载。

新创建的空间（Bucket）缺省为私有，也可以将某个 Bucket 设为公有，公有 Bucket 中的资源为公有资源，公有资源可以匿名下载。

公有资源下载

如果在给bucket绑定了域名的话，可以通过以下地址访问。

[GET] http://<domain>/<key>

其中是bucket所对应的域名。七牛云存储为每一个bucket提供一个默认域名。默认域名可以到七牛云存储开发者平台中，空间设置的域名设置一节查询。用户也可以将自有的域名绑定到bucket上，用户可以通过自有域名访问七牛云存储。

注意： key必须采用utf8编码，如使用非utf8编码访问七牛云存储将返回错误

私有资源下载

私有资源必须通过临时下载授权凭证(downloadToken)下载，如下：

[GET] http://<domain>/<key>?e=<deadline>&token=<downloadToken>

注意，尖括号不是必需，代表替换项。
私有下载链接可以使用 SDK 提供的如下方法生成：

using Qiniu.RS;
public static void MakeGetToken(string domain, string key)
{
	string baseUrl = GetPolicy.MakeBaseUrl(domain, key);
	string private_url = GetPolicy.MakeRequest(baseUrl);
}

数据处理接口

服务端或客户端使用。

七牛支持在云端对图像, 视频, 音频等富媒体进行个性化处理。使用数据处理接口需要引入Qiniu.FileOp命名空间。

using Qiniu.FileOp;

图像

查看图像属性

	string domain = "domain";
	string key = key;
	Console.WriteLine("\n===> FileOp.ImageInfo");
	//生成base_url
	string url = Qiniu.RS.GetPolicy.MakeBaseUrl(domian, key);
	//生成fop_url
	string imageInfoURL = ImageInfo.MakeRequest(url);
	//对其签名，生成private_url。如果是公有bucket此步可以省略
	imageInfoURL = GetPolicy.MakeRequest(imageInfoURL);
	ImageInfoRet infoRet = ImageInfo.Call(imageInfoURL);
	if (infoRet.OK)
	{
		Console.WriteLine("Format: " + infoRet.Format);
		Console.WriteLine("Width: " + infoRet.Width);
		Console.WriteLine("Heigth: " + infoRet.Height);
		Console.WriteLine("ColorModel: " + infoRet.ColorModel);
	}
	else
	{
		Console.WriteLine("Failed to ImageInfo");
	}

查看图片EXIF信息

	string exifURL = Exif.MakeRequest(url);
	ExifRet exifRet = Exif.Call(exifURL);
	if (exifRet.OK)
	{
		Console.WriteLine("ApertureValue.val: " + exifRet["ApertureValue"].val);
		Console.WriteLine("ApertureValue.type: " + exifRet["ApertureValue"].type.ToString());
		Console.WriteLine("ExifInfo: " + exifRet.ToString());
	}
	else
	{
	    Console.WriteLine("Failed to ImageExif");
	}

生成图片预览

	ImageView imageView = new ImageView { Mode = 0, Width = 200, Height = 200, Quality = 90, Format = "gif" };
	string viewUrl = imageView.MakeRequest(url);
	viewUrl = GetPolicy.MakeRequest(viewUrl);
	Console.WriteLine("ImageViewURL:" + viewUrl);

图片高级处理(缩略、裁剪、旋转、转化)

	ImageMogrify imageMogr = new ImageMogrify
	{
		Thumbnail = "!50x50r",
		Gravity = "center",
		Rotate = 90,
		Crop = "!50x50",
		Quality = 80,
		AutoOrient = true
	};
	string mogrUrl = imageMogr.MakeRequest(url);
	mogrUrl = GetPolicy.MakeRequest(mogrUrl);
	Console.WriteLine("ImageMogrifyURL:" + mogrUrl);

图像水印接口

	//文字水印
	WaterMarker marker = new TextWaterMarker("hello,qiniu cloud!","","red");
	string MarkerUrl = marker.MakeRequest(url);
	//图片水印
	marker = new ImageWaterMarker("http://www.b1.qiniudn.com/images/logo-2.png");
	MarkerUrl = marker.MakeRequest(url);

贡献代码

Fork
创建您的特性分支 (git checkout -b my-new-feature)
提交您的改动 (git commit -am 'Added some feature')
将您的修改记录提交到远程 git 仓库 (git push origin my-new-feature)
然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

许可证

基于 MIT 协议发布:

www.opensource.org/licenses/MIT

Name		Name	Last commit message	Last commit date
parent directory ..
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

C# SDK 使用指南

安装

初始化

配置密钥

资源管理接口

查看单个文件属性信息

复制单个文件

移动单个文件

删除单个文件

批量操作

批量获取文件属性信息

批量复制文件

批量移动文件

批量删除文件

资源列表

上传下载接口

上传策略

文件上传

普通上传

断点续上传

文件下载

公有资源下载

私有资源下载

数据处理接口

图像

查看图像属性

查看图片EXIF信息

生成图片预览

图片高级处理(缩略、裁剪、旋转、转化)

图像水印接口

贡献代码

许可证

FilesExpand file tree

Docs

Directory actions

More options

Directory actions

More options

Latest commit

History

Docs

Folders and files

parent directory

README.md

C# SDK 使用指南

安装

初始化

配置密钥

资源管理接口

查看单个文件属性信息

复制单个文件

移动单个文件

删除单个文件

批量操作

批量获取文件属性信息

批量复制文件

批量移动文件

批量删除文件

资源列表

上传下载接口

上传策略

文件上传

普通上传

断点续上传

文件下载

公有资源下载

私有资源下载

数据处理接口

图像

查看图像属性

查看图片EXIF信息

生成图片预览

图片高级处理(缩略、裁剪、旋转、转化)

图像水印接口

贡献代码

许可证