The samples in this directory use the Xamarin.iOS toolchain and
Xamarin Studio project files to illustrate the basics of how to
work with iOS and the SDK.
License
See the repo's license file and any additional license information attached to each sample.
Samples Layout
Version Specific Samples
Starting with iOS 8, we started adding samples that showcase specific
features introduced in a release into a directory for the release. So
all the new iOS 8 feature samples live in the ios8 directory, the
iOS 9 features live in the ios9 directory and the iOS 10 feature lives
in the ios10 directory, and so on for iOS 11.
WatchKit
WatchKit samples are in the WatchKit directory, there are a couple of them:
WatchKit/WatchKitCatalog: contains a sample that shows all the UI elements available in WatchKit.
WatchKit/WatchTables: the sample app used in our tutorials to show how to build WatchKit apps.
Contributing
Before adding a sample to the repository, please run either install-hook.bat
or install-hook.sh depending on whether you're on Windows or a Posix system.
This will install a Git hook that runs the Xamarin code sample validator before
a commit, to ensure that all samples are good to go.
Samples Submission Guidelines
Galleries
We love samples! Application samples show off our platform and provide a great way for people to learn our stuff. And we even promote them as a first-class feature of the docs site. You can find our two sample galleries here:
The mobile-samples repository is for samples that are cross-platform.
The mac-ios-samples repository is for samples that are Mac/iOS only.
Sample Requirements
We welcome sample submissions. Please ping Nat or Miguel for repo commit access.
However, because the sample galleries are powered by the github sample repos, each sample needs to have the following things:
Screenshots - a folder called Screenshots that has at least one screen shot of the sample (preferably a screen shot for every page or every major functionality piece, people really key off these things). for the xplat samples, the folder should be split into platform folders, e.g. iOS, Android, Windows. see https://github.com/xamarin/mobile-samples/tree/master/Tasky/Screenshots for an example of this.
ID - A GUID for the sample. You can generate this in MD under Tools menu : Insert GUID. we need this to key between articles and their associated samples
IsFullApplication - Boolean flag (true or false): whether or not this is a full application such as the MWC App, Tasky, etc., or it's just a feature sample, such as, how to use 'x' feature. the basic test here is, if you would submit this to the app store because it's useful, then it's a full app, otherwise it's just a feature sample.
Brief - Short description or what your sample does. This allows us to display a nice and clean vignette on the sample page.
Level - Beginner, Intermediate, or Advanced: this is the intended audience level for the sample. only the getting started samples are Beginner, as they are intended for people who are just starting with the platform. most samples are Intermediate, and a few, that dive deep into difficult APIs, should be Advanced.
Minimum License Requirement - Starter, Indie, Business, or Enterprise: denotes the license that a user has to have in order to build/run the sample.
Tags: a list of relevant tags for the app. These are:
Data
User Interface
Games
Graphics (CoreDrawing, Animation, OpenGL...)
Media (Video, Sound, recording, photos)
Platform Features (Photo Library, Contacts, Calendars, etc.)
Device Features (NFC, Accelerometer, Compass, Magnemometer, Bluetooth, RFID)
Cloud (Web Services, Networking, etc.)
Backgrounding
Maps + Location
Binding + Interop (Projections)
Notifications
Touch
Getting Started
Async
Extension
iOS8
iOS9
iOS10
Watch
Keyboard
SceneKit
FSharp
SupportedPlatforms: this is only for cross plat samples. It's a comma-separated list, and the valid values are iOS, Android, and Windows.
Gallery: This tag must contain a value of true if you want the sample to show up in the samples gallery on the developer portal.
Buildable Sln and CSProj file - the project must build and have the appropriate project scaffolding (solution + proj).
We integrate tightly with Git to make sure we always provide working samples to our customers. This is achieved through a pre-commit hook that runs before your commit goes through, as well as a post-receive hook on GitHub's end that notifies our samples gallery server when changes go through.
To you, as a sample committer, this means that before you push to the repos, you should run the "install-hook.bat" or "install-hook.sh" (depending on whether you're on Windows or OS X/Linux, respectively). These will install the Git pre-commit hook. Now, whenever you try to make a Git commit, all samples in the repo will be validated. If any sample fails to validate, the commit is aborted; otherwise, your commit goes through and you can go ahead and push.
This strict approach is put in place to ensure that the samples we present to our customers are always in a good state, and to ensure that all samples integrate correctly with the sample gallery (README.md, Metadata.xml, etc). Note that the master branch of each sample repo is what we present to our customers for our stable releases, so they must always Just Work.
Should you wish to invoke validation of samples manually, simply run "validate.windows" or "validate.posix" (again, Windows vs OS X/Linux, respectively). These must be run from a Bash shell (i.e. a terminal on OS X/Linux or the Git Bash terminal on Windows).
If you have any questions, don't hesitate to ask on Xamarin Forums!
ae9d0fa625