【Xamarin挖墙脚系列：Xamarin.Android的API设计准则】

原文:【Xamarin挖墙脚系列：Xamarin.Android的API设计准则】

前言

楼主也是看着Xamarin的官方文档来的。基本也是照猫画虎。英语勉强凑合。翻译的不对的地方，大家多多指教。（这些东西估计弄不完整，呵呵所以别报太高的期望，楼主也很忙）

原文地址：http://developer.xamarin.com/guides/android/advanced_topics/api_design/

API Design

PDF for offline use:

• Download PDF

Let us know how you feel about this.

Overview

In addition to the core Base Class Libraries that are part of Mono, Xamarin.Android ships with bindings for various Android APIs to allow developers to create native Android applications with Mono.

At the core of Xamarin.Android there is an interop engine that bridges the C# world with the Java world and provides developers with access to the Java APIs from C# or other .NET languages.

除了一些基本的核心的BCL类库是Mono的组成部分，Xamarin.Android 这个类库为各个版本的Android APIs做了完整的绑定，这就允许使用Mono的开发人员开发原生的安卓程序。Xamarin.Android的设计核心是为C#等其他.net语言的开发者提供了通向Java世界的桥梁。

Design Principles

（略了，一些无非痛痒的东西，就直接忽略了，就挑重要的说）

Assemblies

Xamarin.Android includes a number of assemblies that constitute the MonoMobile Profile. The Assemblies page has more information.

The bindings to the Android platform are contained in the Mono.Android.dll assembly. This assembly contains the entire binding for consuming Android APIs and communicating with the Android runtime VM.

Xamarin.Android 项目包含了许多支撑Mono开发移动应用的组件程序集。其中，Mono.Android.dll提供了对Android平台的对应的SDK的一对一的影射绑定。这个程序集中，包含了所有的安卓API，实现可以与Android虚拟机通信交互。

Binding Design

Collections

The Android APIs utilize the java.util collections extensively to provide lists, sets, and maps. We expose these elements using the System.Collections.Generic interfaces in our binding. The fundamental mappings are:

Collection mappings

Java Type	System Type	Helper Class
java.util.Set<E>	ICollection<T>	Android.Runtime.JavaSet<T>
java.util.List<E>	IList<T>	Android.Runtime.JavaList<T>
java.util.Map<K,V>	IDictionary<TKey,TValue>	Android.Runtime.JavaDictionary<K,V>
java.util.Collection<E>	ICollection<T>	Android.Runtime.JavaCollection<T>

We have provided helper classes to facilitate faster copyless marshaling of these types. When possible, we recommend using these provided collections instead of the framework provided implementation, like List<T> or Dictionary<TKey, TValue>. The Android.Runtime implementations utilize a native Java collection internally and therefore do not require copying to and from a native collection when passing to an Android API member.

You can pass any interface implementation to an Android method accepting that interface, e.g. pass a List<int> to theArrayAdapter<int>(Context, int, IList<int>) constructor. However, for all implementations except for the Android.Runtime implementations, this involves copying the list from the Mono VM into the Android runtime VM. If the list is later changed within the Android runtime (e.g. by invoking the ArrayAdapter<T>.Add(T) method), those changes will not be visible in managed code. If a JavaList<int> were used, those changes would be visible.

Rephrased, collections interface implementations that are not one of the above listed Helper Classes only marshal [In]:

 // This fails:
 var badSource  = new List<int> { , ,  };
 var badAdapter = new ArrayAdapter<int>(context, textViewResourceId, badSource);
 badAdapter.Add ();
 if (badSource.Count != ) // true
     throw new InvalidOperationException ("this is thrown");

 // this works:
 var goodSource  = new JavaList<int> { , ,  };
 var goodAdapter = new ArrayAdapter<int> (context, textViewResourceId, goodSource);
 goodAdapter.Add ();
 if (goodSource.Count != ) // false
     throw new InvalidOperationException ("should not be reached.");

我觉得这段很重要，但是篇幅有点长，不一一翻译了。意思是：虽然Mono项目提供了对Java对应的API的影射绑定，但是，在实际应用中，我们推荐使用 Android.Runtime 命名空间下对应的集合类，这些辅助类可以让我们既能实现对集合的复杂操作

又可以跟android运行时交互。也就是在ADT 安卓运行时操作这些事例的时候，在托管代码 Mono 中也可以被影响。如果使用System.Collection下的集合，那么这些集合其实在ADT中是被进行了复制操作。转化成了对应的ADT下的类型

注意：这样就不能进行两边的双向通知。比如上面的那个例子。UI组件接受的参数接受任意的集合类型，但是，如果使用的是List IList，那么当UI组件中的元素发送变化的时候，并不能通知托管代码中的集合。相反，使用JavaList是可以的。所以：针对集合的操作，推荐使用Android.Runtime 下面的集合工具类。

Properties

Java methods are transformed into properties, when appropriate:

• The Java method pair T getFoo() and void setFoo(T) are transformed into the Foo property. Example: Activity.Intent .
• The Java method getFoo() is transformed into the read-only Foo property. Example: Context.PackageName .
• Set-only properties are not generated.

• Properties are not generated if the property type would be an array.

就是把类中的 【属性】成员  set foo() get foo() 设计为 C#中的 {get;set}

只读成员 设计为C#的  read only

只读成员是非泛型的

除非是泛型的数组类型，否则属性不会是泛型成员属性。

Events and Listeners

UI中的组件的事件，对应到C#中的就是 委托！！！delegate 或者 Action 或者 Handler 委托类型的设计 。

var button = new Android.Widget.Button (context) {
    Text = string.Format ("{0} clicks!", this.count),
};
button.Click += (sender, e) => {
    button.Text = string.Format ("{0} clicks!", ++this.count);
};

Runnables

Java utilizes the java.lang.Runnable interface to provide a delegation mechanism. The java.lang.Thread class is a notable consumer of this interface. Android has employed the interface in the API as well. Activity.runOnUiThread() and View.post() are notable examples.

The Runnable interface contains a single void method, run(). It therefore lends itself to binding in C# as a System.Actiondelegate. We have provided overloads in the binding which accept an Action parameter for all API members which consume aRunnable in the native API, e.g. Activity.RunOnUiThread() and View.Post().

We left the IRunnable overloads in place instead of replacing them since several types implement the interface and can therefore be passed as runnables directly.

java.lang.Runnable 接口提供了委托实现机制。额，不清楚啥意思。应该是C#中的委托类型 ，是Java中的Runnable接口类型的的一种绑定。比如C#中的Action委托。

Inner Classes

（略）

Interfaces

接口类型

Java interfaces can contain three sets of members, two of which cause problems from C#:

1. Methods.
2. Types.
3. Fields.

这个比较操蛋的设计，Java语言中的接口类型可以有 方法 ，类型 Type，字段。但是Type 和字段是不允许出现在C#中的！所以，这种接口类型被转化成了两种候选方案

1 一个同名的接口类型，仅仅包含方法

2 一个静态的类型，包含所有的字段

（下面就略了）

Resources

所以的图片 布局 文件  String.xml文件，都放置到项目的此目录下。每次添加 或者重新命名文件，都会在 Resource.Designer.cs的类中，生成或修改对应的资源标识。

Constants and Enumerations

常亮和枚举

这些就更不用说了，完全一对一的从Android的API中，影射绑定到Mono.Android中了。