Xamarin.Android bağlama projesi geçişi

.NET'te, ayrı bir proje türü olarak Android bağlama projesi kavramı yoktur. Xamarin.Android bağlama projelerinde çalışan MSBuild öğe gruplarından veya derleme eylemlerinden herhangi biri, Android için .NET uygulaması veya kitaplığı aracılığıyla desteklenir.

Xamarin.Android bağlama kitaplığını Android için .NET sınıf kitaplığına geçirmek için:

1. Visual Studio'da, Xamarin.Android bağlama projenizle aynı ada sahip yeni bir Android Java Kitaplığı Bağlama projesi oluşturun:

   

   Proje dosyasını açtığınızda .NET SDK stilinde bir projeniz olduğunu onaylar:

   <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
       <TargetFramework>net8.0-android</TargetFramework>
       <SupportedOSPlatformVersion>21</SupportedOSPlatformVersion>
       <Nullable>enable</Nullable>
       <ImplicitUsings>enable</ImplicitUsings>
     </PropertyGroup>
   </Project>
   

   Uyarı

   Android bağlama kitaplığının proje dosyası, Android sınıf kitaplığının proje dosyasıyla aynıdır.

2. Projeye Java Arşivi (JAR) veya Android Arşivi (AAR) ekleyin ve derleme eyleminin AndroidLibrary olarak ayarlandığından emin olun.

3. Xamarin.Android bağlama kitaplığınızdan tüm dönüştürmeleri veya eklemeleri kopyalayın.

Desteklenmeyen eski seçenekler

Aşağıdaki eski seçenekler artık desteklenmiyor. Desteklenen alternatifler birkaç yıldır kullanılabilir ve en sorunsuz geçiş seçeneği, geçerli projelerinizi .NET'e geçirmeden önce bu seçeneklerle güncelleştirmek ve test etmektir.

AndroidClassParser

jar2xml özelliği için $(AndroidClassParser) artık geçerli bir seçenek değildir. class-parse artık varsayılan ve yalnızca desteklenen seçenektir.

class-parse , içinde jar2xmlbulunmayan birçok yeni modern özelliğin avantajlarından yararlanır, örneğin:

• Sınıf yöntemleri için otomatik parametre adları (Java kodunuz ile javac -parametersderlenmişse).
• Kotlin desteği.
• Statik/varsayılan arabirim üyesi (DIM) desteği.
• Java Boş bırakılabilir başvuru türü (NRT) ek açıklamaları desteği.

AndroidCodegenTarget

XamarinAndroid özelliği için $(AndroidCodegenTarget) artık geçerli bir seçenek değildir. XAJavaInterop1 artık varsayılan ve yalnızca desteklenen seçenektir.

Dosyalarınızdaki Additions içerisinde oluşturulan bağlama kodu ile etkileşim kuran el ile bağlı kodunuz varsa, XAJavaInterop1 ile uyumlu olacak şekilde güncellenmesi gerekebilir.

Varsayılan dosya ekleme

Aşağıdaki dosya yapısı göz önünde bulundurulduğunda:

Transforms/
    Metadata.xml
foo.jar

Transforms\*.xmldosyalar otomatik olarak bir @(TransformFile) öğe olarak eklenir ve.jar/.aardosyalar otomatik olarak öğe @(AndroidLibrary) olarak eklenir. Bu, foo.jar içinde bulunan Java türleri için, Transforms\Metadata.xml'den gelen meta veri düzeltmelerini kullanarak C# türlerini bağlar.

Varsayılan Android ile ilgili dosya globbing davranışı AutoImport.props içinde tanımlanır. Bu davranış, $(EnableDefaultAndroidItems) özelliği false olarak ayarlanarak Android öğeleri için devre dışı bırakılabilir veya tüm varsayılan öğe ekleme davranışı $(EnableDefaultItems) özelliği false olarak ayarlanarak devre dışı bırakılabilir.

Varsayılan joker karakterlerle istemeyen .jar veya .aar dosyalar dahil edilebilir. Örneğin, aşağıdaki C# derleyici hataları bir AndroidStudio\gradle\wrapper\gradle-wrapper.jar dosyanın istemeden bağlı olmasına neden olur:

Org.Gradle.Cli.AbstractCommandLineConverter.cs(11,89): error CS0535: 'Download' does not implement interface member 'IDownload.Download(URI, File)'
Org.Gradle.Wrapper.Download.cs(10,60): error CS0535: 'AbstractCommandLineConverter' does not implement interface member 'ICommandLineConverter.Convert(ParsedCommandLine, Object)'

Bu sorunu çözmek için proje dosyanızdaki belirli dosyayı kaldırabilirsiniz:

<ItemGroup>
  <AndroidLibrary Remove="AndroidStudio\gradle\wrapper\gradle-wrapper.jar" />
</ItemGroup>

Alternatif olarak, bir klasördeki tüm dosyaları dışlayabilirsiniz:

<AndroidLibrary Remove="AndroidStudio\**\*" />

Yeni öğe grubu adları

<AndroidLibrary> artık tüm .jar dosyalar ve .aar dosyalar için kullanılması önerilen öğe grubudur. Xamarin.Android'de, aynı sonucu elde etmek için öğe meta verilerini kullanabilen aşağıdaki öğe grupları kullanılmıştır:

Eski Öğe Grubu	Yeni Öğe Grubu	Öğe Meta Verileri	Eski Proje Türü
AndroidAarLibrary	AndroidLibrary	Bind="false"	Uygulama
AndroidJavaLibrary	AndroidLibrary	Bind="false"	Uygulama veya sınıf kitaplığı
EmbeddedJar	AndroidLibrary	Yok	Projeyi bağlama
EmbeddedReferenceJar	AndroidLibrary	Bind="false"	Projeyi bağlama
InputJar	AndroidLibrary	Pack="false"	Projeyi bağlama
LibraryProjectZip	AndroidLibrary	Yok	Projeyi bağlama

.aar veya .jar dosyasını, C# bağlaması eklemeyi düşünmediğinizde göz önünde bulundurun. Bu, C# dilinden çağırmanız gerekmeyen Java veya Kotlin bağımlılıklarınız olduğu durumlarda yaygındır. Bu durumda, Bind meta verilerini false olacak şekilde ayarlayabilirsiniz. Varsayılan olarak, dosya varsayılan joker karakterler tarafından alınır. Öznitelik Update, Bind meta verilerini ayarlamak için de kullanılabilir.

<ItemGroup>
  <AndroidLibrary Update="foo.jar" Bind="false">
</ItemGroup>

Bir Android sınıf kitaplığı projesinde, bu işlem sonucunda elde edilen NuGet paketi dizisinde .jar dosyasını olduğu gibi yeniden dağıtır. Bir Android uygulama projesinde, bu .jar dosya, sonuçtaki .apk veya .aab dosyasında yer alır. Bu Java kitaplığı için C# bağlaması da dahil değildir.

Katıştırılmış JAR/AAR dosyaları

Xamarin.Android'de Java .jar veya .aar genellikle bağlamaya .dll Katıştırılmış Kaynak olarak eklenmişti. Ancak bu, her .dll'nin Java kodunu taramak için açılıp taranması gerektiğinden yavaş derlemelere yol açtı. Bulunursa, kullanılması için diske çıkarılması gerekir.

.NET'te artık Java kodu .dll içine gömülmez. Uygulama derleme işlemi, başvurulan .jar ile aynı dizinde bulduğu herhangi bir .aar veya .dll dosyalarını otomatik olarak içerir.

Bir proje <PackageReference> veya <ProjectReference> aracılığıyla bir bağlamaya başvuruyorsa, her şey çalışır ve başka ek hususlar gerekmiyor. Ancak, bir proje <Reference> aracılığıyla bir bağlamaya başvuruyorsa, .jar/.aar.dll öğesinin yanında bulunması gerekir. Yani, aşağıdaki referans için:

<Reference Include="MyBinding.dll" />

Aşağıdaki örnekteki gibi bir dizin çalışmaz:

lib/
    MyBinding.dll

Bunun yerine, dizinin yerel kodu da içermesi gerekir:

lib/
    MyBinding.dll
    mybinding.jar

Geçişle ilgili dikkat edilmesi gerekenler

Java karşılıklarıyla daha iyi eşleşen bağlamalar üretmeye yardımcı olmak için varsayılan olarak ayarlanmış birkaç yeni özellik vardır. Ancak, var olan bir bağlama projesini geçiriyorsanız, bu özellikler mevcut bağlamalarınızla uyumlu API uyumlu olmayan bağlamalar oluşturabilir. Uyumluluğu korumak için bu yeni özellikleri devre dışı bırakmak veya değiştirmek isteyebilirsiniz.

Arabirim sabitleri

Geleneksel olarak, C# Java'da yaygın bir desen olan bir interfaceiçinde sabitlerin bildirilmesine izin vermemiştir:

public interface Foo {
     public static int BAR = 1;
}

Bu desen daha önce sabitleri içeren bir alternatif class oluşturularak destekleniyordu:

public abstract class Foo : Java.Lang.Object
{
   public static int Bar = 1;
}

C# 8 ile bu sabitler `interface` üzerine yerleştirilmiştir:

public interface IFoo
{
    public static int Bar = 1;
}

Ancak bu, mevcut kodun bağımlı olabileceği alternatif sınıfın artık oluşturulmayabileceği anlamına gelir.

$(AndroidBoundInterfacesContainConstants) Özelliğini proje dosyanızda olarak false ayarlamak eski davranışa geri döner.

İç içe arabirim türleri

Geleneksel olarak, C# dilinde iç içe türlerin interface içinde bildirilmesine izin verilmezken, Java'da bu mümkündür.

public interface Foo {
     public class Bar { }
}

Bu düzen, iç içe türü arabirimden ve iç içe tür adından oluşturulmuş bir adla en üst düzey türe taşıyarak desteklendi:

public interface IFoo { }

public class IFooBar : Java.Lang.Object { }

C# 8 ile iç içe türler interface içine yerleştirilebilir.

public interface IFoo
{
    public class Bar : Java.Lang.Object { }
}

Ancak bu, mevcut kodun bağımlı olabileceği en üst düzey sınıfın artık oluşturulmadığını gösterir.

$(AndroidBoundInterfacesContainTypes) Özelliğini proje dosyanızda olarak false ayarlamak eski davranışa geri döner.

Örneğin, var olan iç içe türleri üst düzey bir türe taşımayı sağlamak, ancak gelecek iç içe türlerin iç içe kalmasına izin vermek için karma bir yaklaşım kullanmak istiyorsanız, bunu interface düzeyinde, metadata'yi kullanarak unnest özniteliğini ayarlayarak belirtebilirsiniz. true olarak ayarlanması, iç içe yerleştirilmiş türlerin "çözülmesi" (eski davranış) ile sonuçlanır.

<attr path="/api/package[@name='my.package']/interface[@name='Foo']" name="unnest">true</attr>

olarak false ayarlanması, iç içe türlerin interface (.NET davranışı) iç içe kalmasına neden olur:

<attr path="/api/package[@name='my.package']/interface[@name='Foo']" name="unnest">false</attr>

Bu yaklaşımı kullanarak $(AndroidBoundInterfacesContainTypes) özelliğini true olarak bırakabilir ve şu anda elinizde bulunan iç içe türleri olan her unnest için true özelliğini interface olarak ayarlayabilirsiniz. Bunlar her zaman en üst düzey türler olarak kalacaktır, daha sonra tanıtılan yeni iç içe türler iç içe olacaktır.

Statik ve varsayılan arabirim üyeleri (DIM)

Geleneksel olarak, C# arabirimlerin static üyeler ve default yöntemler içermesine izin vermemiştir.

public interface Foo {
  public static void Bar () { ... }
  public default void Baz () { ... }
}

Arabirimlerdeki statik üyeler eşdüzey classbir öğeye taşınarak desteklenmiştir:

public interface IFoo { }

public class Foo
{
    public static void Bar () { ... }
}

default arabirim yöntemleri gerekli olmadığından ve bunları destekleyecek bir C# yapısı olmadığından geleneksel olarak bağlı değildir.

C# 8 ile, Java arabirimini yansıtan arabirimlerde static ve default üyeleri destekleniyor.

public interface IFoo
{
    public static void Bar () { ... }
    public default void Baz () { ... }
}

Ancak bu, class üyelerini içeren alternatif eşdüzey static artık oluşturulmayacağı anlamına gelir.

$AndroidBoundInterfacesContainStaticAndDefaultInterfaceMethods Özelliğini proje dosyanızda olarak false ayarlamak eski davranışa geri döner.

Null değer alabilen referans türleri

Xamarin.Android 11.0'da null atanabilir referans türleri (NRT) desteği eklendi. NRT desteği standart .NET mekanizması kullanılarak etkinleştirilebilir:

<PropertyGroup>
  <Nullable>enable</Nullable>
</PropertyGroup>

.NET için varsayılan değer olduğundan disable, aynı durum Xamarin.Android projeleri için de geçerlidir.

Resource.designer.cs

Xamarin.Android'de Java bağlama projeleri dosya Resource.designer.cs oluşturmayı desteklemedi. Bağlama projeleri yalnızca .NET'teki sınıf kitaplıkları olduğundan, bu dosya oluşturulur. Bu, mevcut projeleri geçiş yaparken bozucu bir değişiklik olabilir.

Bu değişiklikten kaynaklanan bir hata örneği, bağlamanızın kök ad alanında adlı Resource bir sınıf oluşturmasıdır:

error CS0101: The namespace 'MyBinding' already contains a definition for 'Resource'

Veya AndroidX söz konusu olduğunda, adında - gibi androidx.window/window-extensions.csproj proje dosyaları vardır. Bu, kök ad alanında window-extensions ve Resource.designer.cs içinde geçersiz C# ile sonuçlanmaktadır.

error CS0116: A namespace cannot directly contain members such as fields, methods or statements
error CS1514: { expected
error CS1022: Type or namespace definition, or end-of-file expected

Projede oluşturmayı devre dışı bırakmak için, Resource.designer.cs özelliğini proje dosyanızda $(AndroidGenerateResourceDesigner) olarak ayarlayın: false

<PropertyGroup>
  <AndroidGenerateResourceDesigner>false</AndroidGenerateResourceDesigner>
</PropertyGroup>