diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index e5c8dad02..45f200e01 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -1,5 +1,9 @@ { "redirections": [ + { + "source_path": "docs/cross-platform/get-started/introduction-to-mobile-development.md", + "redirect_url": "/xamarin/get-started/what-is-xamarin" + }, { "source_path": "docs/cross-platform/getting-started/index.md", "redirect_url": "/xamarin/xamarin-forms/get-started" diff --git a/docs/cross-platform/TOC.yml b/docs/cross-platform/TOC.yml index 5c88bb022..b4a64a49e 100644 --- a/docs/cross-platform/TOC.yml +++ b/docs/cross-platform/TOC.yml @@ -9,8 +9,6 @@ - name: Requirements displayName: System requirements href: get-started/requirements.md - - name: What is Xamarin? - href: get-started/introduction-to-mobile-development.md - name: Mobile software development lifecycle href: get-started/introduction-to-mobile-sdlc.md - name: Walkthrough building a cross-platform app diff --git a/docs/cross-platform/get-started/introduction-to-mobile-development-images/android.png b/docs/cross-platform/get-started/introduction-to-mobile-development-images/android.png deleted file mode 100644 index 2c31c3063..000000000 Binary files a/docs/cross-platform/get-started/introduction-to-mobile-development-images/android.png and /dev/null differ diff --git a/docs/cross-platform/get-started/introduction-to-mobile-development-images/ios.png b/docs/cross-platform/get-started/introduction-to-mobile-development-images/ios.png deleted file mode 100644 index 788657503..000000000 Binary files a/docs/cross-platform/get-started/introduction-to-mobile-development-images/ios.png and /dev/null differ diff --git a/docs/cross-platform/get-started/introduction-to-mobile-development.md b/docs/cross-platform/get-started/introduction-to-mobile-development.md deleted file mode 100644 index 8575d3531..000000000 --- a/docs/cross-platform/get-started/introduction-to-mobile-development.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: "What is Xamarin?" -description: "This document provides an introduction to mobile development, discussing Xamarin, how it works, and the applications it outputs." -ms.prod: xamarin -ms.assetid: 33C83E13-F3E5-17B4-6512-207F3D3C5AB6 -author: conceptdev -ms.author: crdun -ms.date: 07/16/2019 ---- - -# What is Xamarin? - -Building mobile apps can be as easy as opening up the IDE, writing and testing an app, and submitting to an App Store -– all done in an afternoon. Or it can be an extremely involved process that -involves rigorous up-front design, usability testing, QA testing on thousands of -devices, a full beta lifecycle, and then deployment a number of different -ways. - -This document introduces the Xamarin platform. To learn more about the *process* of building mobile applications from design through to testing, see [Introduction to the Mobile Software Development Lifecycle](~/cross-platform/get-started/introduction-to-mobile-sdlc.md). - -See [system requirements](~/cross-platform/get-started/requirements.md#macos-requirements) -to confirm your system. - -## Introduction to Xamarin - -When considering how to build Android and iOS applications, many people think -that the native languages, Objective-C, Swift, Java, and Kotlin, are the only -choice. - -Xamarin allows you develop in C#, with a class library and runtime that works across -all many platforms, including iOS, Android, and Windows, while still compiling native -(non-interpreted) applications that are performant enough even for demanding games. - -Xamarin combines all of the abilities of the native -platforms and adds a number of powerful features of its own, including: - -1. **Complete Binding for the underlying SDKs** – Xamarin contains bindings for nearly the entire underlying platform SDKs in both iOS and Android. Additionally, these bindings are strongly-typed, which means that they’re easy to navigate and use, and provide robust compile-time type checking and during development. This leads to fewer runtime errors and higher-quality apps. -1. **Objective-C, Java, C, and C++ Interop** – Xamarin provides facilities for directly invoking Objective-C, Java, C, and C++ libraries, giving you the power to use a wide array of 3rd party code that has already been created. This lets you take advantage of existing iOS and Android libraries written in Objective-C, Java, or C/C++. Additionally, Xamarin offers binding projects that allow you to easily bind native Objective-C and Java libraries using a declarative syntax. -1. **Modern Language Constructs** – Xamarin applications are written in C#, a modern language that includes significant improvements over Objective-C and Java such as *Dynamic Language Features, *Functional Constructs* such as *Lambdas, *LINQ, *Parallel Programming* features, sophisticated *Generics, and more. -1. **Amazing Base Class Library (BCL)** – Xamarin applications use the .NET BCL, a large collection of classes that have comprehensive and streamlined features such as powerful XML, Database, Serialization, IO, String, and Networking support, and more. Existing C# code can be compiled for use in an app, which provides access to thousands of libraries that allow you do things that aren’t covered in the BCL. -1. **Modern Integrated Development Environment (IDE)** – Xamarin uses Visual Studio for Mac on macOS and Visual Studio on Windows. These are both modern IDEs that include features such as code auto completion, a sophisticated Project and Solution management system, a comprehensive project template library, integrated source control, and many others. -1. **Mobile Cross Platform Support** – Xamarin offers sophisticated cross-platform support for the three major mobile platforms of iOS, Android, and Windows. Applications can be written to share up to 90% of their code, and our Xamarin.Mobile library offers a unified API to access common resources across all three platforms. This can significantly reduce both development costs and time to market for mobile developers that target the three most popular mobile platforms. - -Because of Xamarin’s powerful and comprehensive feature set, it fills a -void for application developers that want to use a modern language and platform -to develop cross-platform mobile applications. - -> [!NOTE] -> This Get Started series focuses on getting started building iOS and Android applications. Microsoft offers information about [Universal Windows Platform (UWP) development](https://docs.microsoft.com/windows/uwp/develop/) for tablets and desktops. To learn more about cross-platform development with Xamarin (including UWP apps for Windows), read the [Building Cross-Platform Applications guide](~/cross-platform/app-fundamentals/building-cross-platform-applications/index.md). - -## How does Xamarin work? - -Xamarin offers two commercial products: Xamarin.iOS and Xamarin.Android. They’re both built on -top of *Mono*, an open-source version of the .NET Framework based on the -published .NET ECMA standards. Mono has been around almost as long as the .NET -framework itself, and runs on nearly every imaginable platform including Linux, -Unix, FreeBSD, and macOS. - -On iOS, Xamarin’s *Ahead-of-Time* ( *AOT*) Compiler compiles -Xamarin.iOS applications directly to native ARM assembly code. On Android, -Xamarin’s compiler compiles down to *Intermediate Language* -( *IL*), which is then *Just-in-Time* ( *JIT*) compiled to -native assembly when the application launches. - -In both cases, Xamarin applications utilize a runtime that automatically -handles things such as memory allocation, garbage collection, underlying -platform interop, etc. - -### Xamarin.iOS.dll and Mono.Android.dll - -Xamarin applications are built against a subset of the .NET BCL known as the -Xamarin Mobile Profile. This profile has been created specifically for mobile -applications and packaged in the Xamarin.iOS.dll and Mono.Android.dll (for iOS and -Android respectively). This is much like the way Silverlight (and Moonlight) -applications are built against the Silverlight/Moonlight .NET Profile. In fact, -the Xamarin Mobile profile is equivalent to the Silverlight 4.0 profile with a -bunch of BCL classes added back in. - -For a full list of available assemblies and classes, see the [Xamarin.iOS Assembly List](~/cross-platform/internals/available-assemblies.md?context=xamarin/ios) and the [Xamarin.Android Assembly List](~/cross-platform/internals/available-assemblies.md?context=xamarin/android) - -In addition to the BCL, these .dlls include wrappers for nearly the entire -iOS SDK and Android SDK that allows the underlying SDK APIs to be invoked -directly from C#. - -### Application output - -When Xamarin applications are compiled, the result is an Application Package, -either an .app file in iOS, or .apk file in Android. These files are -indistinguishable from application packages built with the platform's default -IDEs and are deployable in the exact same way. - -## Next steps - -Now you've learned a little about how Xamarin works, the next step is to start building an app using one of these guides: - -- [**Get started with Xamarin.Forms**](~/get-started/index.yml) -- [**Get started with Xamarin.iOS**](~/ios/get-started/hello-ios/index.md) -- [**Get started with Xamarin.Android**](~/android/get-started/hello-android/index.md) -- [**Get started with Xamarin.Mac**](~/mac/get-started/hello-mac.md) diff --git a/docs/get-started/TOC.yml b/docs/get-started/TOC.yml index dc039af90..7bef5f066 100644 --- a/docs/get-started/TOC.yml +++ b/docs/get-started/TOC.yml @@ -2,6 +2,8 @@ href: index.yml expanded: true items: + - name: What is Xamarin + href: what-is-xamarin.md - name: Requirements href: requirements.md - name: Installation diff --git a/docs/get-started/what-is-xamarin-forms-images/xamarin-forms-app-cropped.png b/docs/get-started/what-is-xamarin-forms-images/xamarin-forms-app-cropped.png new file mode 100644 index 000000000..1d3a8b0cb Binary files /dev/null and b/docs/get-started/what-is-xamarin-forms-images/xamarin-forms-app-cropped.png differ diff --git a/docs/get-started/what-is-xamarin-forms-images/xamarin-forms-app.png b/docs/get-started/what-is-xamarin-forms-images/xamarin-forms-app.png new file mode 100644 index 000000000..9e6fb204e Binary files /dev/null and b/docs/get-started/what-is-xamarin-forms-images/xamarin-forms-app.png differ diff --git a/docs/get-started/what-is-xamarin-forms-images/xamarin-forms-architecture.png b/docs/get-started/what-is-xamarin-forms-images/xamarin-forms-architecture.png new file mode 100644 index 000000000..8e78733fb Binary files /dev/null and b/docs/get-started/what-is-xamarin-forms-images/xamarin-forms-architecture.png differ diff --git a/docs/get-started/what-is-xamarin-forms.md b/docs/get-started/what-is-xamarin-forms.md new file mode 100644 index 000000000..ccbd949d1 --- /dev/null +++ b/docs/get-started/what-is-xamarin-forms.md @@ -0,0 +1,88 @@ +--- +title: "What is Xamarin.Forms?" +description: "This article introduces Xamarin.Forms and related libraries." +ms.prod: xamarin +ms.assetid: C1E24DB9-3099-4F79-BB88-10AABF7D4614 +author: profexorgeek +ms.author: jusjohns +ms.date: 09/18/2019 +--- + +# What is Xamarin.Forms? + +[![Screenshots of example Xamarin.Forms application in iOS and Android](what-is-xamarin-forms-images/xamarin-forms-app-cropped.png)](what-is-xamarin-forms-images/xamarin-forms-app.png#lightbox) + +Xamarin.Forms is an open-source UI framework. Xamarin.Forms allows developers to build Android, iOS, and Windows applications from a single shared codebase. + +Xamarin.Forms allows developers to create user interfaces in XAML with code-behind in C#. These interfaces are rendered as performant native controls on each platform. + +## Who Xamarin.Forms is for + +Xamarin.Forms is for developers with the following goals: + +- Share UI layout and design across platforms. +- Share code, test and business logic across platforms. +- Write cross-platform apps in C# with Visual Studio. + +## How Xamarin.Forms works + +![Xamarin.Forms architecture diagram](what-is-xamarin-forms-images/xamarin-forms-architecture.png) + +Xamarin.Forms provides a consistent API for creating UI elements across platforms. This API can be implemented in either XAML or C# and supports databinding for patterns such as Model-View-ViewModel (MVVM). + +At runtime, Xamarin.Forms utilizes platform renderers to convert the cross-platform UI elements into native controls on Android, iOS and UWP. The allows developers to get native look, feel and performance while realizing the benefits of code sharing across platforms. + +Xamarin.Forms applications typically consist of a shared .NET Standard library and individual platform projects. The shared library contains the XAML or C# views and any business logic such as services, models or other code. The platform projects contain any platform-specific logic or packages the application requires. + +Xamarin.Forms uses Xamarin to run .NET applications natively across platforms. For more information about Xamarin, see [What is Xamarin?](~/get-started/what-is-xamarin.md). + +## Additional tools + +Xamarin.Forms has a large ecosystem of NuGet packages that add diverse functionality to applications. This section describes a few commonly-used NuGet packages. + +### Xamarin.Essentials + +Xamarin.Essentials is a library that provides cross-platform APIs for native device features. Like Xamarin itself, Xamarin.Essentials is an abstraction that simplifies the process of accessing native utilities. Some examples of utilities provided by Xamarin.Essentials include: + +- Device info +- File system +- Accelerometer +- Phone dialer +- Text-to-speech +- Screen lock + +For more information, see [Xamarin.Essentials](~/essentials/index.md). + +### Shell + +Xamarin.Forms Shell reduces the complexity of mobile application development by providing the fundamental features that most applications require. Some examples of features provided by Shell include: + +- Common navigation experience +- URI-based navigation scheme +- Integrated search handler + +For more information, see [Xamarin.Forms Shell](~/xamarin-forms/app-fundamentals/shell/index.md) + +### Platform-specifics + +Xamarin.Forms provides a common API that renders native controls across platforms, but a specific platform may have functionality that doesn't exist on other platforms. For example, the Android platform has native functionality for Fast Scrolling in a `ListView` but iOS does not. Xamarin.Forms platform-specifics allow you to utilize functionality that is only available on a specific platform without creating custom renderers or effects. + +Xamarin.Forms includes pre-built solutions for a variety of platform-specific functionality. For more information, see: + +- [Xamarin.Forms platform-specifics](~/xamarin-forms/platform/platform-specifics/index.md) +- [Android platform-specifics](~/xamarin-forms/platform/android/index.md) +- [iOS platform-specifics](~/xamarin-forms/platform/ios/index.md) +- [Windows platform-specifics](~/xamarin-forms/platform/windows/index.md) + +### Material Visual + +Xamarin.Forms Material Visual is used to apply Material Design rules to Xamarin.Forms applications. Xamarin.Forms Material Visual utilizes the Visual property to selectively apply custom renderers to the UI, resulting in an application with a consistent look and feel across iOS and Android. + +For more information, see [Xamarin.Forms Material Visual](~/xamarin-forms/user-interface/visual/material-visual.md) + +## Related links + +- [Get started with Xamarin.Forms](~/xamarin-forms/index.yml) +- [Xamarin.Essentials](~/essentials/index.md) +- [Xamarin.Forms Shell](~/xamarin-forms/app-fundamentals/shell/index.md) +- [Xamarin.Forms Material Visual](~/xamarin-forms/user-interface/visual/material-visual.md) diff --git a/docs/get-started/what-is-xamarin-images/android-architecture-cropped.png b/docs/get-started/what-is-xamarin-images/android-architecture-cropped.png new file mode 100644 index 000000000..e89776d1f Binary files /dev/null and b/docs/get-started/what-is-xamarin-images/android-architecture-cropped.png differ diff --git a/docs/get-started/what-is-xamarin-images/android-architecture.png b/docs/get-started/what-is-xamarin-images/android-architecture.png new file mode 100644 index 000000000..525cc89e4 Binary files /dev/null and b/docs/get-started/what-is-xamarin-images/android-architecture.png differ diff --git a/docs/get-started/what-is-xamarin-images/ios-architecture-cropped.png b/docs/get-started/what-is-xamarin-images/ios-architecture-cropped.png new file mode 100644 index 000000000..9652f035a Binary files /dev/null and b/docs/get-started/what-is-xamarin-images/ios-architecture-cropped.png differ diff --git a/docs/get-started/what-is-xamarin-images/ios-architecture.png b/docs/get-started/what-is-xamarin-images/ios-architecture.png new file mode 100644 index 000000000..965e27aa5 Binary files /dev/null and b/docs/get-started/what-is-xamarin-images/ios-architecture.png differ diff --git a/docs/get-started/what-is-xamarin-images/xamarin-app-cropped.png b/docs/get-started/what-is-xamarin-images/xamarin-app-cropped.png new file mode 100644 index 000000000..6a58f3372 Binary files /dev/null and b/docs/get-started/what-is-xamarin-images/xamarin-app-cropped.png differ diff --git a/docs/get-started/what-is-xamarin-images/xamarin-app.png b/docs/get-started/what-is-xamarin-images/xamarin-app.png new file mode 100644 index 000000000..3385494f8 Binary files /dev/null and b/docs/get-started/what-is-xamarin-images/xamarin-app.png differ diff --git a/docs/get-started/what-is-xamarin-images/xamarin-architecture.png b/docs/get-started/what-is-xamarin-images/xamarin-architecture.png new file mode 100644 index 000000000..1acddf04a Binary files /dev/null and b/docs/get-started/what-is-xamarin-images/xamarin-architecture.png differ diff --git a/docs/get-started/what-is-xamarin.md b/docs/get-started/what-is-xamarin.md new file mode 100644 index 000000000..a0dbbaa47 --- /dev/null +++ b/docs/get-started/what-is-xamarin.md @@ -0,0 +1,100 @@ +--- +title: "What is Xamarin?" +description: "This article introduces Xamarin and related libraries." +ms.prod: xamarin +ms.assetid: 33C83E13-F3E5-17B4-6512-207F3D3C5AB6 +author: profexorgeek +ms.author: jusjohns +ms.date: 09/16/2019 +--- + +# What is Xamarin? + +[![Screenshots of example Xamarin application in iOS and Android](what-is-xamarin-images/xamarin-app-cropped.png)](what-is-xamarin-images/xamarin-app.png#lightbox) + +Xamarin is an open-source platform for building modern and performant applications for iOS, Android, and Windows with .NET. Xamarin is an abstraction layer that manages communication of shared code with underlying platform code. Xamarin runs in a managed environment that provides conveniences such as memory allocation and garbage collection. + +Xamarin enables developers to share an average of 90% of their application across platforms. This pattern allows developers to write all of their business logic in a single language (or reuse existing application code) but achieve native performance, look, and feel on each platform. + +Xamarin applications can be written on PC or Mac and compile into native application packages, such as an **.apk** file on Android, or an **.ipa** file on iOS. + +> [!NOTE] +> Compiling and deploying applications for iOS currently requires a MacOS machine. For more information about development requirements, see [system requirements](~/cross-platform/get-started/requirements.md#macos-requirements). + +## Who Xamarin is for + +Xamarin is for developers with the following goals: + +- Share code, test and business logic across platforms. +- Write cross-platform applications in C# with Visual Studio. + +## How Xamarin works + +![Diagram of Xamarin architecture](what-is-xamarin-images/xamarin-architecture.png) + +The diagram shows the overall architecture of a cross-platform Xamarin application. Xamarin allows you to create native UI on each platform and write business logic in C# that is shared across platforms. In most cases, 80% of application code is sharable using Xamarin. + +Xamarin is built on top of **Mono**, an open-source version of the .NET Framework based on the .NET ECMA standards. Mono has existed for almost as long as the .NET Framework itself, and runs on most platforms including Linux, Unix, FreeBSD, and macOS. The Mono execution environment automatically handles tasks such as memory allocation, garbage collection and interoperability with underlying platforms. + +For more information about platform-specific architecture, see [Xamarin.Android](#xamarinandroid) and [Xamarin.iOS](#xamarinios). + +### Added features + +Xamarin combines the abilities of native platforms and adds a number of features, including: + +1. **Complete binding for the underlying SDKs** – Xamarin contains bindings for nearly the entire underlying platform SDKs in both iOS and Android. Additionally, these bindings are strongly-typed, which means that they’re easy to navigate and use, and provide robust compile-time type checking and during development. Strongly-typed bindings lead to fewer runtime errors and higher-quality applications. +1. **Objective-C, Java, C, and C++ Interop** – Xamarin provides facilities for directly invoking Objective-C, Java, C, and C++ libraries, giving you the power to use a wide array of third party code. This functionality lets you use existing iOS and Android libraries written in Objective-C, Java, or C/C++. Additionally, Xamarin offers binding projects that allow you to bind native Objective-C and Java libraries using a declarative syntax. +1. **Modern language constructs** – Xamarin applications are written in C#, a modern language that includes significant improvements over Objective-C and Java such as dynamic language features, functional constructs such as lambdas, LINQ, parallel programming, generics, and more. +1. **Robust Base Class Library (BCL)** – Xamarin applications use the .NET BCL, a large collection of classes that have comprehensive and streamlined features such as powerful XML, Database, Serialization, IO, String, and Networking support, and more. Existing C# code can be compiled for use in an app, which provides access to thousands of libraries that add functionality beyond the BCL. +1. **Modern Integrated Development Environment (IDE)** – Xamarin uses Visual Studio, a modern IDE that includes features such as code auto completion, a sophisticated project and solution management system, a comprehensive project template library, integrated source control, and more. +1. **Mobile cross-platform support** – Xamarin offers sophisticated cross-platform support for the three major platforms of iOS, Android, and Windows. Applications can be written to share up to 90% of their code, and Xamarin.Essentials offers a unified API to access common resources across all three platforms. Shared code can significantly reduce both development costs and time to market for mobile developers. + +### Xamarin.Android + +[![Xamarin.Android architecture diagram](what-is-xamarin-images/android-architecture-cropped.png)](what-is-xamarin-images/android-architecture.png#lightbox) + +Xamarin.Android applications compile from C# into **Intermediate Language (IL)** which is then **Just-in-Time (JIT)** compiled to a native assembly when the application launches. Xamarin.Android applications run within the Mono execution environment, side by side with the Android Runtime (ART) virtual machine. Xamarin provides .NET bindings to the Android.* and Java.* namespaces. The Mono execution environment calls into these namespaces via **Managed Callable Wrappers (MCW)** and provides **Android Callable Wrappers (ACW)** to the ART, allowing both environments to invoke code in each other. + +For more information, see [Xamarin.Android architecture](~/android/internals/architecture.md). + +### Xamarin.iOS + +[![Xamarin.iOS architecture diagram](what-is-xamarin-images/ios-architecture-cropped.png)](what-is-xamarin-images/ios-architecture.png#lightbox) + +Xamarin.iOS applications are fully **Ahead-of-Time (AOT)** compiled from C# into native ARM assembly code. Xamarin uses **Selectors** to expose Objective-C to managed C# and **Registrars** to expose managed C# code to Objective-C. Selectors and Registrars collectively are called "bindings" and allow Objective-C and C# to communicate. + +For more information, see [Xamarin.iOS architecture](~/ios/internals/architecture.md). + +### Xamarin.Essentials + +Xamarin.Essentials is a library that provides cross-platform APIs for native device features. Like Xamarin itself, Xamarin.Essentials is an abstraction that simplifies the process of accessing native functionality. Some examples of functionality provided by Xamarin.Essentials include: + +- Device info +- File system +- Accelerometer +- Phone dialer +- Text-to-speech +- Screen lock + +For more information, see [Xamarin.Essentials](~/essentials/index.md). + +### Xamarin.Forms + +Xamarin.Forms is an open-source UI framework. Xamarin.Forms allows developers to build iOS, Android and Windows applications from a single shared codebase. Xamarin.Forms allows developers to create user interfaces in XAML with code-behind in C#. These user interfaces are rendered as performant native controls on each platform. Some examples of features provided by Xamarin.Forms include: + +- XAML user-interface language +- Databinding +- Gestures +- Effects +- Styling + +For more information, see [Xamarin.Forms](~/xamarin-forms/index.yml). + +## Get started + +The following guides will help you build your first app using Xamarin: + +- [Get started with Xamarin.Forms](~/xamarin-forms/index.yml) +- [Get started with Xamarin.Android](~/android/index.yml) +- [Get started with Xamarin.iOS](~/ios/index.yml) +- [Get started with Xamarin.Mac](~/mac/index.yml) diff --git a/docs/xamarin-forms/TOC.md b/docs/xamarin-forms/TOC.md index 86db5bcb1..edf739333 100644 --- a/docs/xamarin-forms/TOC.md +++ b/docs/xamarin-forms/TOC.md @@ -1,5 +1,6 @@ # [Xamarin.Forms](index.yml) ## [Get Started](~/get-started/index.yml) +### [What is Xamarin.Forms](~/get-started/what-is-xamarin-forms.md) ### [Requirements](~/get-started/requirements.md) ### [Installation](~/get-started/installation/index.md) ### [Build your first app](~/get-started/first-app/index.md)