Общие сведения о единой APIUnified API Overview

Xamarin единый API делает возможным совместное использование кода в Mac и iOS и поддерживают 32- и 64-разрядных приложений, в одном двоичном файле.Xamarin's Unified API makes it possible to share code between Mac and iOS and support 32 and 64-bit applications with the same binary. На единый API используется по умолчанию в новых проектах Xamarin.iOS и Xamarin.Mac.The Unified API is used by default in new Xamarin.iOS and Xamarin.Mac projects.

Важно!

Классический API Xamarin, перед на единый API, является устаревшим.The Xamarin Classic API, which preceded the Unified API, has been deprecated.

  • Последняя версия Xamarin.iOS, для поддержки классический API (monotouch.dll) был Xamarin.iOS 9.10.The last version of Xamarin.iOS to support the Classic API (monotouch.dll) was Xamarin.iOS 9.10.
  • Xamarin.Mac по-прежнему поддерживает классический API, но больше не обновляется.Xamarin.Mac still supports the Classic API, but it is no longer updated. Так как она устарела, разработчикам следует переместить свои приложения на единый API.Since it is deprecated, developers should move their applications to the Unified API.

Обновление классического приложения на основе APIUpdating Classic API-based Apps

Выполните соответствующие инструкции для вашей платформы.Follow the relevant instructions for your platform:

Советы по обновлению кода в Unified APITips for Updating Code to the Unified API

Независимо от того, какие приложения вы переносите, ознакомьтесь с эти советы для успешного обновления на единый API.Regardless of what applications you are migrating, check out these tips to help you successfully update to the Unified API.

Библиотека разбиенияLibrary Split

С этого момента наши API-интерфейсы будут отображаться двумя способами:From this point on, our APIs will be surfaced in two ways:

  • Классический API: Ограничивается 32 бита (только) и представлены в monotouch.dll и XamMac.dll сборок.Classic API: Limited to 32-bits (only) and exposed in the monotouch.dll and XamMac.dll assemblies.
  • Unified API: Поддержка 32- и 64 разрядной разработки с помощью одного API, доступные в Xamarin.iOS.dll и Xamarin.Mac.dll сборок.Unified API: Support both 32 and 64 bit development with a single API available in the Xamarin.iOS.dll and Xamarin.Mac.dll assemblies.

Это означает, что для корпоративных разработчиков (не предназначенных App Store), вы можете продолжать использовать существующие классические API, как мы будет поддерживать обслуживание их навсегда, или можно обновить до новых интерфейсов API.This means that for Enterprise developers (not targetting the App Store), you can continue using the existing Classic APIs, as we will keep maintaining them forever, or you can upgrade to the new APIs.

Изменения пространства именNamespace Changes

Чтобы уменьшить трения совместное использование кода между продуктов Mac и iOS, мы изменяем пространства имен для API-интерфейсов в продуктах.To reduce the friction to share code between our Mac and iOS products, we are changing the namespaces for the APIs in the products.

Мы пропускают префикс «MonoTouch» из «MonoMac» и операций ввода-вывода продукта из нашего продукта Mac для типов данных.We are dropping the prefix "MonoTouch" from our iOS product and "MonoMac" from our Mac product on the data types.

Это упрощает совместное использование кода на платформах Mac и iOS, не прибегая к условной компиляции, а также сократить шума в верхней части файлов исходного кода.This makes it simpler to share code between the Mac and iOS platforms without resorting to conditional compilation and will reduce the noise at the top of your source code files.

  • Классический API: Использование пространств имен MonoTouch. или MonoMac. префикс.Classic API: Namespaces use MonoTouch. or MonoMac. prefix.
  • Unified API: Отсутствует префикс пространства именUnified API: No namespace prefix

Значения по умолчанию среды выполненияRuntime Defaults

На единый API по умолчанию использует SGen сборщика мусора и новый подсчет ссылок система отслеживания владения объектом.The Unified API by default uses the SGen garbage collector and the New Reference Counting system for tracking object ownership. Эта же функция был перенесен на Xamarin.Mac.This same feature has been ported to Xamarin.Mac.

Это решает ряд проблем, которые разработчики сталкиваются со старой системы и упростить управление памятью.This solves a number of problems that developers faced with the old system and also ease memory management.

Обратите внимание, что можно включить новый Refcount даже для Classic API, но по умолчанию является консервативным и не требуется вносить изменения.Note that it is possible to enable New Refcount even for the Classic API, but the default is conservative and does not require users to make any changes. С помощью единого интерфейса API, мы воспользовались возможностью изменения значение по умолчанию и предоставить разработчикам все усовершенствования в то же время они рефакторинг и повторно тестировать их код.With the Unified API, we took the opportunity of changing the default and give developers all the improvements at the same time that they refactor and re-test their code.

Изменения APIAPI Changes

На единый API удаляет устаревшие методы и несколько экземпляров там, где произошли опечаток в именах API, когда они были привязаны к исходной MonoTouch MonoMac пространства имен и в классическом API.The Unified API removes deprecated methods and there are a few instances where there were typos in the API names when they were bound to the original MonoTouch and MonoMac namespaces in the Classic APIs. Эти экземпляры были исправлены в новых интерфейсов API единой и нужно будет обновляться в компонент, iOS и Mac-приложений.These instances have been corrected in the new Unified APIs and will need to be updated in your component, iOS and Mac applications. Ниже приведен список самых распространенных рисков, которыми вы можете столкнуться:Here is a list of the most common ones you might run into:

Имя метода классический APIClassic API Method Name Имени унифицированный API-методUnified API Method Name
UINavigationController.PushViewControllerAnimated() UINavigationController.PushViewController()
UINavigationController.PopViewControllerAnimated() UINavigationController.PopViewController()
CGContext.SetRGBFillColor() CGContext.SetFillColor()
NetworkReachability.SetCallback() NetworkReachability.SetNotification()
CGContext.SetShadowWithColor CGContext.SetShadow
UIView.StringSize UIKit.UIStringDrawing.StringSize

Полный список изменений при переключении из классической модели на единый API, см. в разделе наших Classic (monotouch.dll) vs отличия API единой (Xamarin.iOS.dll) документации.For a full list of changes when switching from the Classic to the Unified API, please see our Classic (monotouch.dll) vs Unified (Xamarin.iOS.dll) API differences documentation.

Обновление до единойUpdating to Unified

Несколько старого/разбить/устаревшего API-интерфейса в классической недоступны в единой API.Several old/broken/deprecated API in classic are not available in the Unified API. Его можно легко исправить CS0616 обновляете предупреждения перед запуском вашего (автоматически или вручную), поскольку вы [Obsolete] атрибут сообщения (часть предупреждения) помогут вам в правом API.It can be easier to fix the CS0616 warnings before starting your (manual or automated) upgrade since you'll have the [Obsolete] attribute message (part of the warning) to guide you to the right API.

Обратите внимание, что мы публикуем diff -или классическом unified API изменения, которые могут использоваться до или после обновления проекта.Note that we are publishing a diff of the classic vs unified API changes that can be used either before or after your project updates. По-прежнему исправления старые вызовы в классическом будет часто можно сэкономить много времени (меньше поиска документации).Still fixing the obsoletes calls in Classic will often be a time saver (less documentation lookups).

Следуйте указаниям, приведенным к обновление имеющихся приложений iOS, или приложений Mac на единый API.Follow these instructions to update existing iOS apps, or Mac apps to the Unified API. Просмотрите оставшейся части этой страницы, и эти советы Дополнительные сведения о переносе кода.Review the remainder of this page, and these tips for additional information on migrating your code.

NuGetNuGet

Пакеты NuGet, которые ранее поддерживались Xamarin.iOS через классический API публикации своих сборок с помощью Monotouch10 моникер платформы.NuGet packages that previously supported Xamarin.iOS via the Classic API published their assemblies using the Monotouch10 platform moniker.

На единый API вводит новый идентификатор платформы для совместимых пакетов — Xamarin.iOS10.The Unified API introduces a new platform identifier for compatible packages - Xamarin.iOS10. Существующие пакеты NuGet потребуется обновить для добавления поддержки для этой платформы, создавая в единый API.Existing NuGet packages will need to be updated to add support for this platform, by building against the Unified API.

Важно!

При наличии ошибки в форме «ошибка 3 нельзя включать в том же проекте Xamarin.iOS «monotouch.dll» и «Xamarin.iOS.dll» — «Xamarin.iOS.dll» указывается явным образом, хотя «monotouch.dll» ссылается "xxx, версия = 0.0.000, Culture = neutral, PublicKeyToken = null'» после преобразования приложения Unified API-интерфейсам, это обычно из-за наличия компонента или пакета NuGet в проекте, который не был обновлен на единый API.If you have an error in the form "Error 3 Cannot include both 'monotouch.dll' and 'Xamarin.iOS.dll' in the same Xamarin.iOS project - 'Xamarin.iOS.dll' is referenced explicitly, while 'monotouch.dll' is referenced by 'xxx, Version=0.0.000, Culture=neutral, PublicKeyToken=null'" after converting your application to the Unified APIs, it is typically due to having either a component or NuGet Package in the project that has not been updated to the Unified API. Необходимо удалить существующий компонент/NuGet, обновление до версии, которая поддерживает унифицированными API и выполните чистую сборку.You'll need to remove the existing component/NuGet, update to a version that supports the Unified APIs and do a clean build.

Пути к 64-разряднаяThe Road to 64 Bits

Общие сведения о поддержке 32- и 64 разрядных приложений, так и сведения о платформах см. в разделе 32 и 64-разрядных платформы.For background on supporting 32 and 64 bit applications and information about frameworks see the 32 and 64 bit Platform Considerations.

Новые типы данныхNew Data Types

В основе разницу Mac и iOS API-интерфейсы используют конкретной архитектуры типы данных, которые всегда являются 32-разрядной на 32-разрядных платформах и 64-разрядной на 64-разрядных платформах.At the core of the difference, both Mac and iOS APIs use an architecture-specific data types that are always 32 bit on 32 bit platforms and 64 bit on 64 bit platforms.

Например, сопоставляет Objective-C NSInteger тип данных для int32_t на 32-разрядных системах, позволяющая int64_t на 64-разрядных системах.For example, Objective-C maps the NSInteger data type to int32_t on 32 bit systems and to int64_t on 64 bit systems.

В соответствии с это поведение, на наш Unified API вместо прежнего использования int (в .NET определяется как всегда должны быть System.Int32) в новый тип данных: System.nint.To match this behavior, on our Unified API, we are replacing the previous uses of int (which in .NET is defined as always being System.Int32) to a new data type: System.nint. Можно считать из «n» значение «native», поэтому собственного целочисленный тип платформы.You can think of the "n" as meaning "native", so the native integer type of the platform.

Мы представляем nint, nuint и nfloat также предоставляет типы данных на основе их при необходимости.We are introducing nint, nuint and nfloat as well providing data types built on top of them where necessary.

Дополнительные сведения об этих изменениях типов данных, см. в разделе собственные типы документа.To learn more about these data type changes, see the Native Types document.

Как определить архитектуру приложений iOSHow to detect the architecture of iOS apps

Могут возникнуть ситуации, где приложения необходимо знать, если он под управлением 32-разрядная или 64-разрядной системы iOS.There might be situations where your application needs to know if it is running on a 32 bit or a 64 bit iOS system. Чтобы проверить архитектуру можно использовать следующий код:The following code can be used to check the architecture:

if (IntPtr.Size == 4) {
    Console.WriteLine ("32-bit App");
} else if (IntPtr.Size == 8) {
    Console.WriteLine ("64-bit App");
}

Массивы и System.Collections.GenericArrays and System.Collections.Generic

Так как C# индексаторы ожидать, что тип int, необходимо явно привести тип nint значения int для доступа к элементам в коллекции или массиве.Because C# indexers expect a type of int, you'll have to explicitly cast nint values to int to access the elements in a collection or array. Пример:For example:

public List<string> Names = new List<string>();
...

public string GetName(nint index) {
    return Names[(int)index];
}

Это ожидаемое поведение, так как на приведение из int для nint является потерей данных на 64-разрядная версия, неявное преобразование не выполняется.This is expected behavior, because the cast from int to nint is lossy on 64 bit, an implicit conversion is not done.

Преобразование типа DateTime в NSDateConverting DateTime to NSDate

При использовании Unified API-интерфейсы, выполняется неявное преобразование DateTime для NSDate значения больше не выполняется.When using the Unified APIs, the implicit conversion of DateTime to NSDate values is no longer performed. Эти значения необходимо будет явно преобразовываться из одного типа в другой.These values will need to be explicitly converted from one type to another. Чтобы автоматизировать этот процесс можно использовать следующие методы расширения:The following extension methods can be used to automate this process:

public static DateTime NSDateToDateTime(this NSDate date)
{
    // NSDate has a wider range than DateTime, so clip
    // the converted date to DateTime.Min|MaxValue.
    double secs = date.SecondsSinceReferenceDate;
    if (secs < -63113904000)
        return DateTime.MinValue;
    if (secs > 252423993599)
        return DateTime.MaxValue;
    return (DateTime) date;
}

public static NSDate DateTimeToNSDate(this DateTime date)
{
    if (date.Kind == DateTimeKind.Unspecified)
        date = DateTime.SpecifyKind (date, /* DateTimeKind.Local or DateTimeKind.Utc, this depends on each app */)
    return (NSDate) date;
}

Устаревшие интерфейсы API и опечаткиDeprecated APIs and Typos

Классический API Xamarin.iOS внутри (monotouch.dll) [Obsolete] атрибут использовался двумя разными способами:Inside Xamarin.iOS classic API (monotouch.dll) the [Obsolete] attribute was used in two different ways:

  • Устаревшие API для iOS: Это когда Apple подсказок для остановки теста с помощью API, так как он является заменяют новой.Deprecated iOS API: This is when Apple hints to you to stop using an API because it's being superseded by a newer one. Классический API по-прежнему нормально и часто требуется (Если вы поддерживаете более старой версии iOS).The Classic API is still fine and often required (if you support the older version of iOS). Такие API (и [Obsolete] атрибут), включаются в новые сборки Xamarin.iOS.Such API (and the [Obsolete] attribute) are included into the new Xamarin.iOS assemblies.
  • Неправильный API некоторые API-Интерфейс содержит опечаток по их именам.Incorrect API Some API had typos on their names.

Для исходной сборки (monotouch.dll и XamMac.dll) сохранена старого кода, для совместимости, но они будут удалены из сборок Unified API (Xamarin.iOS.dll и Xamarin.Mac)For the original assemblies (monotouch.dll and XamMac.dll) we kept the old code available for compatibility but they have been removed from the Unified API assemblies (Xamarin.iOS.dll and Xamarin.Mac)

NSObject subclasses .ctor(IntPtr)NSObject subclasses .ctor(IntPtr)

Каждый NSObject подкласс имеет конструктор, принимающий IntPtr.Every NSObject subclass has a constructor that accepts an IntPtr. Это как можно создать новый управляемый экземпляр из собственный дескриптор ObjC.This is how we can instantiate a new managed instance from a native ObjC handle.

В классической модели это было public конструктор.In classic this was a public constructor. Однако оказалось достаточно неправильно использовать эту функцию в пользовательском коде, например, создание нескольких управляемых экземпляров для одного экземпляра ObjC или , создание экземпляра управляемого будет недоставать ожидаемое состояние управляемых (для подклассов).However it was easy to misuse this feature in user code, e.g. creating several managed instances for a single ObjC instance or creating a managed instance that would lack the expected managed state (for subclasses).

Чтобы избежать таких проблем IntPtr конструкторы являются теперь protected в единой API, используемый только для подклассов.To avoid those kind of problems the IntPtr constructors are now protected in unified API, to be used only for subclassing. Это гарантирует, что исправьте/safe API используется для создания управляемого экземпляра из дескрипторов, т. е.This will ensure the correct/safe API is used to create managed instance from handles, i.e.

var label = Runtime.GetNSObject<UILabel> (handle);

Этот API возвращает существующего управляемого экземпляра (если он уже существует) или создаст новый (при необходимости).This API will return an existing managed instance (if it already exists) or will create a new one (when required). Он уже находится в классической и унифицированный API.It is already available in both classic and unified API.

Обратите внимание, что .ctor(NSObjectFlag) теперь protected , но это редко используется вне подклассов.Note that the .ctor(NSObjectFlag) is now also protected but this one was rarely used outside of subclassing.

Заменить действие NSActionNSAction Replaced with Action

С помощью API-интерфейсы единой NSAction был удален в пользу standard .NET Action.With the Unified APIs, NSAction has been removed in favor of the standard .NET Action. Это является значительным улучшением, поскольку Action является типом .NET, тогда как NSAction была предназначена для Xamarin.iOS.This is a big improvement because Action is a common .NET type, whereas NSAction was specific to Xamarin.iOS. В обоих случаях то же, но они были отличающимися и несовместимых типов и привела к больший объем кода, нужно быть записаны для достижения такого же результата.They both do exactly the same thing, but they were distinct and incompatible types and resulted in more code having to be written to achieve the same result.

Например, если существующее приложение Xamarin включен следующий код:For example, if your existing Xamarin application included the following code:

UITapGestureRecognizer singleTap = new UITapGestureRecognizer (new NSAction (delegate() {
    ShowDropDownAnimated (tblDataView);
}));

Теперь его можно заменить на простое лямбда-выражения:It can now be replaced with a simple lambda:

UITapGestureRecognizer singleTap = new UITapGestureRecognizer (() => ShowDropDownAnimated(tblDataView));

Ранее это было бы ошибка компилятора поскольку Action не могут быть назначены NSAction, но поскольку UITapGestureRecognizer теперь принимает Action вместо NSAction допустимо в Unified API.Previously that would be a compiler error because an Action can't be assigned to NSAction, but since UITapGestureRecognizer now takes an Action instead of an NSAction it is valid in the Unified APIs.

Пользовательские делегаты, заменить действиеCustom delegates replaced with Action

В единой несколько простых (например, один параметр) .net-делегатам, были заменены Action<T>.In unified some simple (e.g. one parameter) .net delegates were replaced with Action<T>. Например,E.g.

public delegate void NSNotificationHandler (NSNotification notification);

Теперь можно использовать как Action<NSNotification>.can now be used as an Action<NSNotification>. Этот код promote повторно использовать и сокращают дублирование кода внутри Xamarin.iOS и собственных приложений.This promote code reuse and reduce code duplication inside both Xamarin.iOS and your own applications.

Задача заменены задачи < Boolean, NSError >>Task replaced with Task<Boolean,NSError>>

В классической возникли некоторые асинхронные интерфейсы API возвращение Task<bool>.In classic there were some async APIs returning Task<bool>. Однако некоторые из них где следует использовать, когда NSError был частью сигнатуры, т. е. bool уже true и требовалось перехватить исключение, чтобы получить NSError.However some of them where are to use when an NSError was part of the signature, i.e. the bool was already true and you had to catch an exception to get the NSError.

Так как некоторые ошибки являются очень часто, и возвращаемое значение невозможно было использовать этот шаблон был изменен в единой для возврата Task<Tuple<Boolean,NSError>>.Since some errors are very common and the return value was not useful this pattern was changed in unified to return a Task<Tuple<Boolean,NSError>>. Это позволяет проверить успешность и любая ошибка, могло бы произойти во время асинхронного вызова.This allows you to check both the success and any error that could have happened during the async call.

Строка NSString vsNSString vs string

В некоторых случаях была изменена из нескольких констант string для NSString, например UITableViewCellIn a few cases some constants had to be changed from string to NSString, e.g. UITableViewCell

Классическая модельClassic

public virtual string ReuseIdentifier { get; }

Единая системаUnified

public virtual NSString ReuseIdentifier { get; }

В целом мы предпочитаем .NET System.String типа.In general we prefer the .NET System.String type. Тем не менее, несмотря на рекомендации Apple собственного API сравнение константы указателей (но не саму строку), и это работают, только когда мы предоставляем констант как NSString.However, despite Apple guidelines, some native API are comparing constant pointers (not the string itself) and this can only work when we expose the constants as NSString.

Протоколы Objective-CObjective-C Protocols

Исходное MonoTouch не имеет полную поддержку для протоколов ObjC и некоторые, не является оптимальным, API были добавлены для поддержки наиболее распространенным сценарием.The original MonoTouch did not have full support for ObjC protocols and some, non-optimal, API were added to support the most common scenario. Это ограничение больше не существует, но для обеспечения обратной совместимости, несколько интерфейсов API, хранятся вокруг внутри monotouch.dll и XamMac.dll.This limitation does not exists anymore but, for backward compatibility, several APIs are kept around inside monotouch.dll and XamMac.dll.

Эти ограничения были удалены и очищены в Unified API-интерфейсы.These limitations have been removed and cleaned up on the Unified APIs. Большинство изменений будет выглядеть следующим образом:Most changes will look like this:

Классическая модельClassic

public virtual AVAssetResourceLoaderDelegate Delegate { get; }

Единая системаUnified

public virtual IAVAssetResourceLoaderDelegate Delegate { get; }

I Префикса означает, что единой предоставлять интерфейс, а не конкретный тип, для протокола ObjC.The I prefix means unified expose an interface, instead of a specific type, for the ObjC protocol. Это упрощает случаев, где вы не хотите подкласс определенного типа, который предоставлен Xamarin.iOS.This will ease cases where you do not want to subclass the specific type that Xamarin.iOS provided.

Его также можно использовать некоторые API, чтобы быть более точными и проста в использовании, например:It also allowed some API to be more precise and easy to use, e.g.:

Классическая модельClassic

public virtual void SelectionDidChange (NSObject uiTextInput);

Единая системаUnified

public virtual void SelectionDidChange (IUITextInput uiTextInput);

Такие API стали проще для нас, не обращаясь к документации и автозавершение кода в интегрированной среде разработки предоставит вам удобнее предложения на основе протокола и интерфейса.Such API are now easier to us, without referring to documentation, and your IDE code completion will provide you with more useful suggestions based on the protocol/interface.

Протокол NSCodingNSCoding Protocol

Наши исходную привязку .ctor(NSCoder) для каждого типа - включены, даже если он не поддерживает NSCoding протокола.Our original binding included an .ctor(NSCoder) for every type - even if it did not support the NSCoding protocol. Один Encode(NSCoder) метод присутствовал в NSObject кодируемый объект.A single Encode(NSCoder) method was present in the NSObject to encode the object. Но этот метод будет работать только в том случае, если экземпляр согласование протокола NSCoding.But this method would only work if the instance conformed to NSCoding protocol.

На единый API мы устранили это.On the Unified API we have fixed this. Новые сборки будут иметь только .ctor(NSCoder) Если тип соответствует NSCoding.The new assemblies will only have the .ctor(NSCoder) if the type conforms to NSCoding. Теперь есть такие типы Encode(NSCoder) метод, который соответствует INSCoding интерфейс.Also such types now have an Encode(NSCoder) method which conforms to the INSCoding interface.

Отсутствие серьезных последствий: В большинстве случаев это изменение не влияет на приложения как старые, удалены, конструкторы не может быть использована.Low Impact: In most cases this change won’t affect applications as the old, removed, constructors could not be used.

Дополнительные советыFurther Tips

Дополнительные изменения, которые следует учитывать, перечислены в советы по обновлению приложений на единый API.Additional changes to be aware of are listed in the tips for updating apps to the Unified API.

Пример кодаSample Code

Начиная с 31 июля, корпорация Майкрософт опубликовала порты примеров операций ввода-вывода к новому интерфейсу API на magic-types ветви в monotouch-samples.As of July 31st, we have published ports of the iOS samples to this new API on the magic-types branch at monotouch-samples.

Для Mac, выполняется проверка примеров в обоих примеры mac репозитория (отображение новых интерфейсов API в Mavericks или Yosemite), а также примеры 32 или 64-разрядную в ветви magic типы примеры mac.For Mac, we are checking samples in both the mac-samples repo (showing new APIs in Mavericks/Yosemite) as well as 32/64 bit samples in the magic-types branch mac-samples.