Dela via

Nyheter i .NET MAUI för .NET 9

  • Artikel

Fokus för .NET Multi-platform App UI (.NET MAUI) i .NET 9 är att förbättra produktkvaliteten. Detta omfattar utökad testtäckning, genomförandetester från början till slut och felkorrigering. Mer information om produktkvalitetsförbättringar i .NET MAUI 9 finns i följande versionsinformation:

Viktig

På grund av att du arbetar med externa beroenden, till exempel Xcode- eller Android SDK-verktyg, skiljer sig .NET MAUI-supportprincipen från .NET- och .NET Core-supportprincipen. För mer information, se .NET MAUI-supportpolicy.

Kompatibilitet med Xcode 16, som innehåller SDK-stöd för iOS 18, iPadOS 18, tvOS 18 och macOS 15, krävs när du skapar med .NET MAUI 9. Xcode 16 kräver en Mac som kör macOS 14.5 eller senare.

I .NET 9 levereras .NET MAUI som en .NET-arbetsbelastning och flera NuGet-paket. Fördelen med den här metoden är att du enkelt kan fästa dina projekt på specifika versioner, samtidigt som du enkelt kan förhandsgranska outgivna eller experimentella versioner. När du skapar ett nytt .NET MAUI-projekt läggs nödvändiga NuGet-paket automatiskt till i projektet.

Lägsta distributionsmål

.NET MAUI 9 kräver minst distributionsmål för iOS 12.2 och Mac Catalyst 15.0 (macOS 12.0). De lägsta distributionsmålen för Android och Windows är desamma. Mer information finns i plattformar som stöds för .NET MAUI-appar.

Nya kontroller

.NET MAUI 9 innehåller två nya kontroller.

HybridWebView

HybridWebView möjliggör värd för godtyckligt HTML-/JS/CSS-innehåll i en webbvy och möjliggör kommunikation mellan koden i webbvyn (JavaScript) och koden som är värd för webbvyn (C#/.NET). Om du till exempel har en befintlig React JS-app kan du vara värd för den i en plattformsoberoende .NET MAUI-inbyggd app och skapa serverdelen av appen med C# och .NET.

Om du vill skapa en .NET MAUI-app med HybridWebView behöver du:

  • Webbinnehållet i appen, som består av statisk HTML, JavaScript, CSS, bilder och andra filer.
  • En HybridWebView kontroll som en del av appens användargränssnitt. Detta kan uppnås genom att referera till det i appens XAML.
  • Kod i webbinnehållet och i C#/.NET som använder HybridWebView API:er för att skicka meddelanden mellan de två komponenterna.

Hela appen, inklusive webbinnehållet, paketeras och körs lokalt på en enhet och kan publiceras till tillämpliga appbutiker. Webbinnehållet finns i en intern webbvykontroll och körs i appens kontext. Alla delar av appen kan komma åt externa webbtjänster, men det krävs inte.

Mer information finns i HybridWebView.

Rubriklist för Windows

Med TitleBar-kontrollen kan du lägga till en anpassad titelrad i din app på Windows.

översikt över .NET MAUI-rubrikfältet.

En TitleBar kan anges som värdet för egenskapen Window.TitleBar på alla TitleBar:

<Window.TitleBar>
    <TitleBar x:Name="TeamsTitleBar"
              Title="Hello World"
              Icon="appicon.png"
              HeightRequest="46">
        <TitleBar.Content>
            <SearchBar Placeholder="Search"
                       PlaceholderColor="White"
                       MaximumWidthRequest="300"
                       HorizontalOptions="Fill"
                       VerticalOptions="Center" />
        </TitleBar.Content>
    </TitleBar>
</Window.TitleBar>

Ett exempel på dess användning i C# är:

Window window = new Window
{
    TitleBar = new TitleBar
    {
        Icon = "titlebar_icon.png"
        Title = "My App",
        Subtitle = "Demo"
        Content = new SearchBar { ... }      
    }
};

En TitleBar är mycket anpassningsbar genom dess egenskaper Content, LeadingContentoch TrailingContent:

<TitleBar Title="My App"
          BackgroundColor="#512BD4"
          HeightRequest="48">
    <TitleBar.Content>
        <SearchBar Placeholder="Search"
                   MaximumWidthRequest="300"
                   HorizontalOptions="Fill"
                   VerticalOptions="Center" />
    </TitleBar.Content>
    <TitleBar.TrailingContent>
        <ImageButton HeightRequest="36"
                     WidthRequest="36"
                     BorderWidth="0"
                     Background="Transparent">
            <ImageButton.Source>
                <FontImageSource Size="16"
                                 Glyph="&#xE713;"
                                 FontFamily="SegoeMDL2"/>
            </ImageButton.Source>
        </ImageButton>
    </TitleBar.TrailingContent>
</TitleBar>

Följande skärmbild visar det resulterande utseendet:

skärmbild av .NET MAUI Titlebar.

Not

Mac Catalyst-stöd för TitleBar-kontrollen kommer att läggas till i en framtida version.

Mer information finns i TitleBar.

Kontrollförbättringar

.NET MAUI 9 innehåller kontrollförbättringar.

BackButtonBehavior OneWay-bindningsläge

Bindningsläget för IsVisible och IsEnabled på en BackButtonBehavior i en Shell-app är nu BindingMode.OneWay i stället för BindingMode.OneTime. På så sätt kan du enklare styra beteendet för bakåtknappen vid körning, med databindningar:

<ContentPage ...>    
    <Shell.BackButtonBehavior>
        <BackButtonBehavior Command="{Binding BackCommand}"
                            IsVisible="{Binding IsBackButtonVisible}"
                            IconOverride="back.png" />   
    </Shell.BackButtonBehavior>
    ...
</ContentPage>

BlazorWebView

Standardbeteendet för att vara värd för innehåll i en BlazorWebView har ändrats till 0.0.0.1. Den interna 0.0.0.0 adress som används som värd för innehåll fungerar inte längre och resulterar i att BlazorWebView inte läser in innehåll och återgivning som en tom rektangel.

Om du vill välja att använda 0.0.0.0-adressen lägger du till följande kod i metoden CreateMauiApp i MauiProgram.cs:

// Set this switch to use the LEGACY behavior of always using 0.0.0.0 to host BlazorWebView
AppContext.SetSwitch("BlazorWebView.AppHostAddressAlways0000", true);

Som standard utlöses BlazorWebView nu och glömmer bort asynkront bortskaffande av den underliggande WebViewManager. Detta minskar risken för att deponeringsstopp förekommer på Android.

Varning

Det här standardbeteendet innebär att bortskaffande kan returneras innan alla objekt tas bort, vilket kan orsaka beteendeförändringar i din app. Objekten som tas bort är delvis Blazors egna interna typer, men även appdefinierade typer som begränsade tjänster som används i BlazorWebView delen av appen.

Om du vill inaktivera det här beteendet bör du konfigurera appen för att blockera vid borttagning via en AppContext-växel i CreateMauiApp-metoden i din MauiProgram-klass.

AppContext.SetSwitch("BlazorWebView.AndroidFireAndForgetAsync", false);

Om din app är konfigurerad att blockera vid bortskaffande via den här växeln utför BlazorWebView asynkron synkroniseringshantering, vilket innebär att den blockerar tråden tills asynkroniseringen har slutförts. Detta kan dock orsaka dödlägen om borttagningen behöver köra kod på samma tråd (eftersom tråden blockeras i väntan).

Knappar på iOS

Button kontroller på iOS respekterar nu avstånd, utfyllnad, kantlinjebredd och marginaler mer exakt än i tidigare versioner. En stor bild i en Button ändras nu till den maximala storleken, med hänsyn till avstånd, utfyllnad, kantlinjebredd och marginaler. Men om en Button innehåller text och en bild kanske det inte går att anpassa allt innehåll inuti knappen, och därför bör du ändra storleken på bilden manuellt för att uppnå önskad layout.

CollectionView och CarouselView

.NET MAUI 9 innehåller två valfria nya hanterare på iOS och Mac Catalyst som ger prestanda- och stabilitetsförbättringar för CollectionView och CarouselView. Dessa hanterare baseras på UICollectionView API:er.

Om du vill välja att använda dessa hanterare lägger du till följande kod i klassen MauiProgram:

#if IOS || MACCATALYST
builder.ConfigureMauiHandlers(handlers =>
{
    handlers.AddHandler<Microsoft.Maui.Controls.CollectionView, Microsoft.Maui.Controls.Handlers.Items2.CollectionViewHandler2>();
    handlers.AddHandler<Microsoft.Maui.Controls.CarouselView, Microsoft.Maui.Controls.Handlers.Items2.CarouselViewHandler2>();
});
#endif

Innehållssida

I .NET MAUI 9 stöds även egenskapen HideSoftInputOnTapped på Mac Catalyst samt Android och iOS.

Stöd för mjuk tangentbordsinmatning

.NET MAUI 9 lägger till nytt stöd för mjuk tangentbordsinmatning för Password, Dateoch Time. Dessa kan aktiveras på Editor- och Entry kontroller:

<Entry Keyboard="Date" />

Textjustering

TextAlignment-uppräkningen lägger till en Justify medlem som kan användas för att justera text i textkontroller. Du kan till exempel justera text vågrätt i en Label med HorizontalTextAlignment.Justify:

<Label Text="Lorem ipsum dolor sit amet, consectetur adipiscing elit. In facilisis nulla eu felis fringilla vulputate."
       HorizontalTextAlignment="Justify"/>

TimePicker

TimePicker får en TimeSelected händelse som utlöses när den valda tiden ändras. Det TimeChangedEventArgs objekt som medföljer händelsen TimeSelected har NewTime och OldTime egenskaper som anger den nya respektive gamla tiden.

WebView

WebView lägger till en ProcessTerminated händelse som aktiveras när en WebView process slutar oväntat. Det WebViewProcessTerminatedEventArgs objekt som medföljer den här händelsen definierar plattformsspecifika egenskaper som anger varför processen misslyckades.

Kompilerade bindningar i kod

Bindningar som skrivs i kod använder vanligtvis strängsökväg som löses vid körning med reflektion, och belastningen för att göra detta varierar från plattform till plattform. .NET MAUI 9 introducerar ytterligare en SetBinding tilläggsmetod som definierar bindningar med hjälp av ett Func argument i stället för en strängsökväg:

// in .NET 8
MyLabel.SetBinding(Label.TextProperty, "Text");

// in .NET 9
MyLabel.SetBinding(Label.TextProperty, static (Entry entry) => entry.Text);

Den här kompilerade bindningsmetoden ger följande fördelar:

  • Förbättrade databindningsprestanda genom att matcha bindningsuttryck vid kompilering i stället för körtid.
  • En bättre felsökningsupplevelse för utvecklare eftersom ogiltiga bindningar rapporteras som byggfel.
  • Intellisense vid redigering.

Alla metoder kan inte användas för att definiera en kompilerad bindning. Uttrycket måste vara ett enkelt egenskapsåtkomstuttryck. I följande exempel visas giltiga och ogiltiga bindningsuttryck:

// Valid: Property access
static (PersonViewModel vm) => vm.Name;
static (PersonViewModel vm) => vm.Address?.Street;

// Valid: Array and indexer access
static (PersonViewModel vm) => vm.PhoneNumbers[0];
static (PersonViewModel vm) => vm.Config["Font"];

// Valid: Casts
static (Label label) => (label.BindingContext as PersonViewModel).Name;
static (Label label) => ((PersonViewModel)label.BindingContext).Name;

// Invalid: Method calls
static (PersonViewModel vm) => vm.GetAddress();
static (PersonViewModel vm) => vm.Address?.ToString();

// Invalid: Complex expressions
static (PersonViewModel vm) => vm.Address?.Street + " " + vm.Address?.City;
static (PersonViewModel vm) => $"Name: {vm.Name}";

Varning

Ett CS0272-kompilatorfel inträffar om den angivna åtkomsten för en egenskap eller indexerare inte är tillgänglig. Om detta inträffar ökar du tillgängligheten för accessorn.

Dessutom lägger .NET MAUI 9 till en BindingBase.Create-metod som anger bindningen direkt på objektet med en Funcoch returnerar bindningsobjektinstansen:

// in .NET 8
myEntry.SetBinding(Entry.TextProperty, new MultiBinding
{
    Bindings = new Collection<BindingBase>
    {
        new Binding(nameof(Entry.FontFamily), source: RelativeBindingSource.Self),
        new Binding(nameof(Entry.FontSize), source: RelativeBindingSource.Self),
        new Binding(nameof(Entry.FontAttributes), source: RelativeBindingSource.Self),
    },
    Converter = new StringConcatenationConverter()
});

// in .NET 9
myEntry.SetBinding(Entry.TextProperty, new MultiBinding
{
    Bindings = new Collection<BindingBase>
    {
        Binding.Create(static (Entry entry) => entry.FontFamily, source: RelativeBindingSource.Self),
        Binding.Create(static (Entry entry) => entry.FontSize, source: RelativeBindingSource.Self),
        Binding.Create(static (Entry entry) => entry.FontAttributes, source: RelativeBindingSource.Self),
    },
    Converter = new StringConcatenationConverter()
});

Viktig

Kompilerade bindningar krävs i stället för strängbaserade bindningar i NativeAOT-appar och i appar med fullständig trimning aktiverad.

Mer information om kompilerade bindningar i kod finns i Kompilerade bindningar i kod.

Kompilerade bindningar i XAML

I .NET MAUI 8 inaktiveras kompilerade bindningar för alla XAML-bindningsuttryck som definierar egenskapen Source och som inte stöds för flera bindningar. Dessa begränsningar har tagits bort i .NET MAUI 9. Information om hur du kompilerar XAML-bindningsuttryck som definierar egenskapen Source finns i Kompilera bindningar som definierar egenskapen Source.

Som standard skapar .NET MAUI 9 byggvarningar för bindningar som inte använder kompilerade bindningar. Mer information om varningar för XAML-kompilerade bindningar finns i XAML-kompilerade bindningsvarningar.

Beroendeinjektion

I en Shell-app behöver du inte längre registrera dina sidor med containern för beroendeinmatning om du inte vill påverka sidans livslängd i förhållande till containern med metoderna AddSingleton, AddTransienteller AddScoped. För mer information om dessa metoder, se Beroendelivslängd.

Koppla från hanteraren

När du implementerar en anpassad kontroll med hjälp av hanterare måste varje plattformshanterares implementering inkludera DisconnectHandler()-metoden för att utföra rensningsåtgärder för den inbyggda vyn, såsom att avprenumerera från händelser. Före .NET MAUI 9 anropas dock inte DisconnectHandler()-implementeringen avsiktligt av .NET MAUI. I stället måste du anropa den själv när du väljer att rensa en kontroll, till exempel när du navigerar bakåt i en app.

I .NET MAUI 9 kopplar hanterare automatiskt från sina kontroller när det är möjligt, till exempel när man navigerar bakåt i en app. I vissa scenarier kanske du inte vill ha det här beteendet. Därför lägger .NET MAUI 9 till en bifogad egenskap HandlerProperties.DisconnectPolicy för att styra när hanterarna kopplas från sina kontroller. Den här egenskapen kräver ett HandlerDisconnectPolicy argument där uppräkningen definierar följande värden:

  • Automatic, vilket anger att hanterare kopplas från automatiskt. Det här är standardvärdet för den HandlerProperties.DisconnectPolicy tillhörande egenskapen.
  • Manual, som anger att hanterare måste kopplas från manuellt genom att anropa DisconnectHandler() implementeringen.

I följande exempel visas hur du anger egenskapen HandlerProperties.DisconnectPolicy bifogad:

<controls:Video x:Name="video"
                HandlerProperties.DisconnectPolicy="Manual"
                Source="video.mp4"
                AutoPlay="False" />

Motsvarande C#-kod är:

Video video = new Video
{
    Source = "video.mp4",
    AutoPlay = false
};
HandlerProperties.SetDisconnectPolicy(video, HandlerDisconnectPolicy.Manual);

Dessutom finns det en DisconnectHandlers tilläggsmetod som kopplar bort hanterare från en viss IView:

video.DisconnectHandlers();

När du kopplar ifrån sprids metoden DisconnectHandlers nedåt i kontrollträdet tills den har slutförts eller anländer till en kontroll som har angett en manuell policy.

Stöd för flera fönster

.NET MAUI 9 lägger till möjligheten att ta med ett specifikt fönster framtill på Mac Catalyst och Windows med metoden Application.Current.ActivateWindow:

Application.Current?.ActivateWindow(windowToActivate);

Inbyggd AOT-distribution

I .NET MAUI 9 kan du välja intern AOT-distribution på iOS och Mac Catalyst. Intern AOT-distribution genererar en .NET MAUI-app som har sammanställts i förväg (AOT) till intern kod. Detta ger följande fördelar:

  • Minskad storlek på apppaket, vanligtvis upp till 2,5 x mindre.
  • Snabbare starttid, vanligtvis upp till 2 gånger snabbare.
  • Snabbare byggtid.

Mer information finns i intern AOT-distribution på iOS och Mac Catalyst.

Inbyggd inbäddning

.NET MAUI 9 innehåller fullständiga API:er för interna inbäddningsscenarier, som tidigare måste läggas till manuellt i projektet:

var mauiApp = MauiProgram.CreateMauiApp();

#if ANDROID
var mauiContext = new MauiContext(mauiApp.Services, window);
#else
var mauiContext = new MauiContext(mauiApp.Services);
#endif

var mauiView = new MyMauiContent();
var nativeView = mauiView.ToPlatform(mauiContext);

Du kan också använda metoden ToPlatformEmbedded och skicka in Window för plattformen där appen körs:

var mauiApp = MauiProgram.CreateMauiApp();
var mauiView = new MyMauiContent();
var nativeView = mauiView.ToPlatformEmbedded(mauiApp, window);

I båda exemplen är nativeView en plattformsspecifik version av mauiView.

Om du vill starta en inbyggd inbäddad app i .NET MAUI 9 anropar du UseMauiEmbeddedApp-tilläggsmetoden för ditt MauiAppBuilder-objekt:

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();

        builder
            .UseMauiEmbeddedApp<App>();

        return builder.Build();
    }
}

Mer information finns i intern inbäddning.

Projektmallar

Projektmallen .NET MAUI App innehåller möjligheten att skapa en fullt fungerande todo-app med hjälp av kontroller från Syncfusion Toolkit för .NET MAUI för att visualisera data och spara dem i en lokal databas baserat på SQLite. Skapa den här att göra-appen genom att skapa ett nytt projekt i Visual Studio med hjälp av projektmallen .NET MAUI App och markera kryssrutan Inkludera exempelinnehåll i fönstret Ytterligare information:

Skärmbild av hur du lägger till SyncFusion-exempelsidor i ditt .NET MAUI-appprojekt.

Todolistappen kan också skapas med .NET CLI med --sample-content- eller -sc-alternativet.

dotnet new maui --sample-content -n MyProject

.NET MAUI 9 lägger också till en .NET MAUI Blazor Hybrid- och Web App- projektmall i Visual Studio som skapar en lösning med en .NET MAUI Blazor Hybrid-app med en Blazor-webbapp som delar gemensam kod i ett Razor-klassbiblioteksprojekt.

Mallen kan också användas från .NET CLI:

dotnet new maui-blazor-web -n MyProject

Resursordlistor

I .NET MAUI 9 är en fristående XAML-ResourceDictionary (som inte backas upp av en kod bakom fil) standard att ha sin XAML kompilerad. Om du vill avregistrera dig från det här beteendet anger du <?xaml-comp compile="false" ?> efter XML-huvudet.

Trimning

Fullständig trimning stöds nu genom att ange egenskapen $(TrimMode) MSBuild till full. Mer information finns i Trimma en .NET MAUI-app.

Beskära inkompatibiliteter

Följande .NET MAUI-funktioner är inte kompatibla med fullständig trimning och tas bort av trimmern:

Justera funktionsväxlar

.NET MAUI har trimmerdirektiv, så kallade funktionsväxlar, som gör det möjligt att bevara koden för funktioner som inte är trimningssäkra. Dessa trimmer-direktiv kan användas när $(TrimMode) build-egenskapen är inställd på full, samt för Native AOT:

MSBuild-egenskap Beskrivning
MauiEnableVisualAssemblyScanning När det är inställt på truegenomsöker .NET MAUI sammansättningar efter typer som implementerar IVisual och efter [assembly:Visual(...)] attribut, och registrerar dessa typer. Som standard är den här byggegenskapen inställd på false när fullständig trimning är aktiverad.
MauiShellSearchResultsRendererDisplayMemberNameSupported När värdet är inställt på falseignoreras värdet för SearchHandler.DisplayMemberName. I stället bör du ange en ItemTemplate för att definiera utseendet hos SearchHandler-resultat. Som standard är den här byggegenskapen inställd på false när fullständig trimning eller intern AOT är aktiverad.
MauiQueryPropertyAttributeSupport När värdet är inställt på falseanvänds inte [QueryProperty(...)] attribut för att ange egenskapsvärden när du navigerar. I stället bör du implementera IQueryAttributable-gränssnittet för att acceptera frågeparametrar. Som standard är den här byggegenskapen inställd på false när fullständig trimning eller intern AOT är aktiverad.
MauiImplicitCastOperatorsUsageViaReflectionSupport När värdet är inställt på falseletar .NET MAUI inte efter implicita konverteringsoperatorer när värden konverteras från en typ till en annan. Detta kan påverka bindningar mellan egenskaper med olika typer och ange ett egenskapsvärde för ett bindbart objekt med ett värde av en annan typ. I stället bör du definiera en TypeConverter för din typ och koppla den till typen med hjälp av attributet TypeConverterAttribute. Som standard är den här byggegenskapen inställd på false när fullständig trimning eller intern AOT är aktiverad.
_MauiBindingInterceptorsSupport När det är inställt på falsekommer .NET MAUI inte att fånga upp några anrop till SetBinding metoder och försöker inte kompilera dem. Som standard är den här byggegenskapen inställd på true.
MauiEnableXamlCBindingWithSourceCompilation När det är inställt på truekompilerar .NET MAUI alla bindningar, inklusive de där egenskapen Source används. Om du aktiverar den här funktionen kontrollerar du att alla bindningar har rätt x:DataType så att de kompileras eller rensar datatypen med x:Data={x:Null}} om bindningen inte ska kompileras. Som standard är den här byggegenskapen inställd på true när fullständig trimning eller intern AOT är aktiverad.
MauiHybridWebViewSupported När den är inställd på falseblir HybridWebView-kontrollen inte tillgänglig. Som standard är den här byggegenskapen inställd på false när fullständig trimning eller intern AOT är aktiverad.

Dessa MSBuild-egenskaper har också motsvarande AppContext växlar:

  • MSBuild-egenskapen MauiEnableVisualAssemblyScanning har en motsvarande AppContext omkopplare med namnet Microsoft.Maui.RuntimeFeature.IsIVisualAssemblyScanningEnabled.
  • Egenskapen MauiShellSearchResultsRendererDisplayMemberNameSupported i MSBuild har en motsvarande AppContext-omkopplare med namnet Microsoft.Maui.RuntimeFeature.IsShellSearchResultsRendererDisplayMemberNameSupported.
  • Egenskapen MauiQueryPropertyAttributeSupport MSBuild har en motsvarande AppContext växel med namnet Microsoft.Maui.RuntimeFeature.IsQueryPropertyAttributeSupported.
  • Egenskapen MauiImplicitCastOperatorsUsageViaReflectionSupport MSBuild har en motsvarande AppContext växel med namnet Microsoft.Maui.RuntimeFeature.IsImplicitCastOperatorsUsageViaReflectionSupported.
  • Egenskapen _MauiBindingInterceptorsSupport MSBuild har en motsvarande AppContext växel med namnet Microsoft.Maui.RuntimeFeature.AreBindingInterceptorsSupported.
  • Egenskapen MauiEnableXamlCBindingWithSourceCompilation MSBuild har en motsvarande AppContext växel med namnet Microsoft.Maui.RuntimeFeature.MauiEnableXamlCBindingWithSourceCompilationEnabled.
  • Egenskapen MauiHybridWebViewSupported MSBuild har en motsvarande AppContext växel med namnet Microsoft.Maui.RuntimeFeature.IsHybridWebViewSupported.

Det enklaste sättet att använda en funktionsväxel är att placera motsvarande MSBuild-egenskap i appens projektfil (*.csproj), vilket gör att den relaterade koden trimmas från .NET MAUI-sammansättningarna.

Distribution av Windows-appar

När du felsöker och distribuerar ett nytt .NET MAUI-projekt till Windows är standardbeteendet i .NET MAUI 9 att distribuera en uppackad app. Mer information finns i Distribuera och felsöka .NET MAUI-appen i Windows.

XAML-kompilatorfelkoder

I .NET MAUI 9 har XAML-kompilatorfelkoderna ändrat sitt prefix från XFC till XC. Se till att du uppdaterar $(WarningsAsErrors), $(WarningsNotAsErrors)och $(NoWarn) byggnadsegenskaper i appens projektfiler, om de används, för att referera till det nya prefixet.

XAML markup-utvidgningar

Alla klasser som implementerar IMarkupExtension, IMarkupExtension<T>, IValueProvideroch IExtendedTypeConverter måste kommenteras med antingen RequireServiceAttribute eller AcceptEmptyServiceProviderAttribute. Detta krävs på grund av en XAML-kompilatoroptimering som introducerades i .NET MAUI 9 som möjliggör generering av effektivare kod, vilket hjälper till att minska appens storlek och förbättra körningsprestanda.

Information om hur du kommenterar tillägg med dessa attribut finns i Tjänsteleverantörer.

Xcode-synkronisering

.NET MAUI 9 innehåller Xcode-synkronisering (xcsync), som är ett verktyg som gör att du kan använda Xcode för att hantera Apple-specifika filer med .NET-projekt, inklusive tillgångskataloger, plist-filer, storyboards och xib-filer. Verktyget har två huvudkommandon för att generera ett tillfälligt Xcode-projekt från ett .NET-projekt och för att synkronisera ändringar från Xcode-filerna tillbaka till ditt .NET-projekt.

Du använder dotnet build med kommandona xcsync-generate eller xcsync-sync för att generera eller synkronisera dessa filer och skicka in en projektfil och ytterligare argument:

dotnet build /t:xcsync-generate
    /p:xcSyncProjectFile=<PROJECT>
    /p:xcSyncXcodeFolder=<TARGET_XCODE_DIRECTORY>
    /p:xcSyncTargetFrameworkMoniker=<FRAMEWORK>
    /p:xcSyncVerbosity=<LEVEL>

För mer information, se Xcode-synkronisering.

Inaktuella API:er

.NET MAUI 9 avvecklar vissa API:er, som kommer att tas bort helt i en framtida version.

Ram

Kontrollen Frame markeras som föråldrad i .NET MAUI 9 och tas bort helt i en framtida version. Den Border-kontrollen ska användas istället för det.

När du ersätter en Frame med en Borderbör Frame.BorderColor egenskapsvärdet bli Border.Stroke egenskapsvärde och Frame.CornerRadius egenskapsvärdet ska bli en del av Border.StrokeShape egenskapsvärdet. Dessutom kan det vara väsentligt att duplicera Margin värdet som Padding värde.

I följande exempel visas motsvarande Frame- och Border-element i XAML:

<Frame BorderColor="DarkGray"
       CornerRadius="5"
       Margin="20"
       HeightRequest="360"
       HorizontalOptions="Center"
       VerticalOptions="Center" />

<Border Stroke="DarkGray"
        StrokeShape="RoundRectangle 5"
        Margin="20"
        Padding="20"
        HeightRequest="360"
        HorizontalOptions="Center"
        VerticalOptions="Center" />

Mer information finns i Border.

Huvudsida

I stället för att definiera den första sidan i din app med egenskapen MainPage på ett Application objekt bör du ange egenskapen Page på en Window till appens första sida. Det här är vad som händer internt i .NET MAUI när du anger egenskapen MainPage, så det finns ingen beteendeförändring som introduceras av egenskapen MainPage markeras som föråldrad.

I följande exempel visas hur du anger egenskapen Page på en Windowvia åsidosättningen CreateWindow:

public partial class App : Application
{
    public App()
    {
        InitializeComponent();
    }

    protected override Window CreateWindow(IActivationState? activationState)
    {
        return new Window(new AppShell());
    }
}

Kod som använder egenskapen Application.Current.MainPage ska nu komma åt egenskapen Application.Current.Windows[0].Page för appar med ett enda fönster. För appar med flera fönster använder du samlingen Application.Current.Windows för att identifiera rätt fönster och sedan komma åt egenskapen Page. Dessutom har varje element en Window egenskap, som är tillgänglig när elementet är en del av det aktuella fönstret, från vilket egenskapen Page kan nås (Window.Page). Plattformskod kan hämta appens IWindow-objekt med Microsoft.Maui.Platform.GetWindow-tilläggsmetoden.

Även om egenskapen MainPage behålls i .NET MAUI 9 tas den bort helt i en framtida version.

Kompatibilitetslayouter

Kompatibilitetslayoutklasserna i Microsoft.Maui.Controls.Compatibility namnområdet har föråldrats.

Äldre samtalsmätningar

Följande VisualElement mätmetoder har föråldrats:

Det här är äldre måttmetoder som inte fungerar korrekt med .NET MAUI-layoutförväntningar.

Som ersättning har metoden VisualElement.Measure(Double, Double) introducerats. Den här metoden returnerar den minsta storlek som ett element behöver för att kunna visas på en enhet. Marginaler undantas från mätningen, men returneras med storleken. Det här är den föredragna metoden att anropa när du mäter en vy.

Dessutom är SizeRequest struct föråldrad. I stället ska Size användas.

Uppgradera från .NET 8 till .NET 9

Om du vill uppgradera dina .NET MAUI-projekt från .NET 8 till .NET 9 installerar du först .NET 9 och .NET MAUI-arbetsbelastningen med Visual Studio 17.12+eller med Visual Studio Code och .NET MAUI-tillägget och .NET MAUI-arbetsbelastningarnaeller med fristående installationsprogrammet och kommandot dotnet workload install maui.

Uppdatera projektfil

Om du vill uppdatera .NET MAUI-appen från .NET 8 till .NET 9 öppnar du appens projektfil (.csproj) och ändrar Target Framework Monikers (TFMs) från 8 till 9. Om du använder en TFM, till exempel net8.0-ios15.2 se till att matcha plattformsversionen eller ta bort den helt. I följande exempel visas TFM:erna för ett .NET 8-projekt:

<TargetFrameworks>net8.0-android;net8.0-ios;net8.0-maccatalyst;net8.0-tizen</TargetFrameworks>
<TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net8.0-windows10.0.19041.0</TargetFrameworks>

I följande exempel visas TFM:erna för ett .NET 9-projekt:

<TargetFrameworks>net9.0-android;net9.0-ios;net9.0-maccatalyst;net9.0-tizen</TargetFrameworks>
<TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net9.0-windows10.0.19041.0</TargetFrameworks>

Om appens projektfil refererar till en .NET 8-version av Microsoft.Maui.Controls NuGet-paketet, antingen direkt eller via egenskapen $(MauiVersion) build, uppdaterar du den till en .NET 9-version. Ta sedan bort paketreferensen för Microsoft.Maui.Controls.Compatibility NuGet-paketet, förutsatt att appen inte använder några typer från det här paketet. Uppdatera dessutom paketreferensen för Microsoft.Extensions.Logging.Debug NuGet-paketet till den senaste .NET 9-versionen.

Om din app riktar in sig på iOS eller Mac Catalyst uppdaterar du $(SupportedOSPlatformVersion) build-egenskaperna för dessa plattformar till 15.0:

<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">15.0</SupportedOSPlatformVersion>
<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">15.0</SupportedOSPlatformVersion>

När du felsöker och distribuerar ett nytt .NET MAUI-projekt till Windows är standardbeteendet i .NET 9 att distribuera en uppackad app. För att anta detta beteende, se Konvertera en paketerad .NET MAUI Windows-app till opaketerad.

Innan du skapar din uppgraderade app för första gången tar du bort mapparna bin och obj. Eventuella byggfel och varningar vägleder dig mot nästa steg.

Uppdatera XAML-kompilatorfelkoder

XAML-kompilatorfelkoder har ändrat sitt prefix från XFC till XC, så uppdatera $(WarningsAsErrors), $(WarningsNotAsErrors)och $(NoWarn) byggnadsegenskaper i appens projektfil, om de används, för att referera till det nya prefixet.

Åtgärda nya XAML-kompilatorvarningar för kompilerade bindningar

Kompileringsvarningar skapas för bindningar som inte använder kompilerade bindningar, och dessa måste åtgärdas. Mer information finns i XAML-kompilerade bindningsvarningar.

Uppdatera XAML-markeringstillägg

XAML-markeringstillägg måste kommenteras med antingen RequireServiceAttribute eller AcceptEmptyServiceProviderAttribute. Detta krävs på grund av en XAML-kompilatoroptimering som möjliggör generering av effektivare kod, vilket hjälper till att minska appens storlek och förbättra körningsprestanda. Mer information finns i Tjänsteleverantörer.

Adressera inaktuella API:er

.NET MAUI 9 föråldrar vissa API:er, som kommer att tas bort helt i en framtida version. Åtgärda därför eventuella build-varningar om inaktuella API:er. Mer information finns i Inaktuella API:er.

Anta kompilerade bindningar som anger egenskapen Source

Du kan välja att kompilera bindningar som anger egenskapen Source för att dra nytta av bättre körningsprestanda. Mer information finns i Kompilera bindningar som definierar egenskapen Source.

Anta kompilerade bindningar i C#

Du kan välja att kompilera bindningsuttryck som deklareras i kod för att dra nytta av bättre körningsprestanda. Mer information finns i Kompilerade bindningar i kod.

Inför fullständig trimning

Du kan använda fullständig trimning för att minska appens totala storlek genom att ange egenskapen $(TrimMode) MSBuild till full. Mer information finns i Trimma en .NET MAUI-app.

Implementera NativeAOT-distribution på plattformar som stöds

Du kan välja intern AOT-distribution på iOS och Mac Catalyst. Intern AOT-distribution genererar en .NET MAUI-app som har sammanställts i förväg (AOT) till intern kod. Mer information finns i intern AOT-distribution på iOS och Mac Catalyst.

.NET för Android

.NET för Android i .NET 9, som lägger till stöd för API 35, innehåller arbete för att minska byggtiden och för att förbättra trimbarheten för appar för att minska storleken och förbättra prestandan. Mer information om .NET för Android i .NET 9 finns i följande versionsanteckningar:

Resurspaket

.NET för Android i .NET 9 introducerar möjligheten att placera tillgångar i ett separat paket, som kallas ett tillgångspaket. På så sätt kan du ladda upp spel och appar som normalt är större än den grundläggande paketstorlek som tillåts av Google Play. Genom att placera dessa tillgångar i ett separat paket får du möjlighet att ladda upp ett paket som är upp till 2 GB i storlek, snarare än den grundläggande paketstorleken på 200 Mb.

Viktig

Tillgångspaket kan bara innehålla tillgångar. När det gäller .NET för Android innebär det objekt som har AndroidAsset build-åtgärden.

.NET MAUI-appar definierar tillgångar via MauiAsset byggåtgärd. Ett tillgångspaket kan anges via attributet AssetPack:

<MauiAsset
    Include="Resources\Raw\**"
    LogicalName="%(RecursiveDir)%(Filename)%(Extension)"
    AssetPack="myassetpack" />

Obs

Ytterligare metadata ignoreras av andra plattformar.

Om du har specifika objekt som du vill placera i ett tillgångspaket kan du använda attributet Update för att definiera AssetPack metadata:

<MauiAsset Update="Resources\Raw\MyLargeAsset.txt" AssetPack="myassetpack" />

Tillgångspaket kan ha olika leveransalternativ som styr när dina tillgångar ska installeras på enheten:

  • Tidsmoduler installeras samtidigt som appen. Den här pakettypen kan vara upp till 1 GB stor, men du kan bara ha en av dem. Den här leveranstypen anges med InstallTime metadata.
  • Snabbföljningspaket installeras någon gång strax efter att appen har installerats klart. Appen kommer att kunna starta medan den här typen av paket installeras, så du bör kontrollera att installationen har slutförts innan du försöker använda tillgångarna. Den här typen av tillgångspaket kan vara upp till 512 MB stort. Den här leveranstypen anges med FastFollow metadata.
  • Paket på begäran laddas aldrig ned till enheten om inte appen specifikt begär det. Den totala storleken på alla dina tillgångspaket får inte överstiga 2 Gb och du kan ha upp till 50 separata tillgångspaket. Den här leveranstypen anges med OnDemand metadata.

I .NET MAUI-appar kan leveranstypen anges med attributet DeliveryType på en MauiAsset:

<MauiAsset Update="Resources\Raw\myvideo.mp4" AssetPack="myassetpack" DeliveryType="FastFollow" />

Mer information om Android-tillgångspaket finns i Android-tillgångspaket.

Stöd för Android 15

.NET för Android i .NET 9 lägger till .NET-bindningar för Android 15 (API 35). Om du vill skapa för dessa API:er uppdaterar du projektets målramverk till net9.0-android:

<TargetFramework>net9.0-android</TargetFramework>

Not

Du kan också ange net9.0-android35 som ett målramverk, men nummer 35 kommer förmodligen att ändras i framtida .NET-versioner för att matcha nyare Android OS-versioner.

64-bitarsarkitekturer som standard

.NET för Android i .NET 9 skapar inte längre följande körningsidentifierare (RID) som standard:

  • android-arm
  • android-x86

Detta bör förbättra byggtiden och minska storleken på Android-.apk filer. Observera att Google Play stöder delning av apppaket per arkitektur.

Om du behöver skapa för dessa arkitekturer kan du lägga till dem i projektfilen (.csproj):

<RuntimeIdentifiers>android-arm;android-arm64;android-x86;android-x64</RuntimeIdentifiers>

Eller i ett projekt med flera mål:

<RuntimeIdentifiers Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">android-arm;android-arm64;android-x86;android-x64</RuntimeIdentifiers>

Android Marshal-metoder

Förbättringar av Android Marshal-metoder i .NET 9 har gjort att funktionen fungerar mer tillförlitligt i program men är ännu inte standard. Aktivering av den här funktionen har resulterat i en ~10% prestandaförbättring i en testapp.

Android Marshal-metoder kan aktiveras i projektfilen (.csproj) via egenskapen $(AndroidEnableMarshalMethods):

<PropertyGroup>
    <AndroidEnableMarshalMethods>true</AndroidEnableMarshalMethods>
</PropertyGroup>

Mer information om funktionen finns i -funktionsdokumentationen eller implementering på GitHub.

Trimning av förbättringar

I .NET 9 är Android API-sammansättningarna (Mono.Android.dll, Java.Interop.dll) nu helt trimkompatibla. Om du vill välja fullständig trimning anger du egenskapen $(TrimMode) i projektfilen (.csproj):

<PropertyGroup>
    <TrimMode>Full</TrimMode>
</PropertyGroup>

Detta möjliggör även trimning av analysverktyg, så att varningar introduceras för eventuell problematisk C#-kod.

Mer information finns i Trimningskornighet.

.NET för iOS

.NET 9 på iOS, tvOS, Mac Catalyst och macOS använder Xcode 16.0 för följande plattformsversioner:

  • iOS: 18.0
  • tvOS: 18.0
  • Mac Catalyst: 18.0
  • macOS: 15.0

Mer information om .NET 9 på iOS, tvOS, Mac Catalyst och macOS finns i följande versionsinformation:

Bindningar

.NET för iOS 9 introducerar möjligheten till flermålsversioner av .NET för iOS-bindningar. Ett biblioteksprojekt kan till exempel behöva byggas för två olika iOS-versioner:

<TargetFrameworks>net9.0-ios17.0;net9.0-ios17.2</TargetFrameworks>

Detta skapar två bibliotek, ett med iOS 17.0-bindningar och ett med iOS 17.2-bindningar.

Viktig

Ett appprojekt bör alltid rikta in sig på den senaste iOS SDK:n.

Trimning av förbättringar

I .NET 9 är iOS- och Mac Catalyst-sammansättningarna (Microsoft.iOS.dll, Microsoft.MacCatalyst.dll osv.) nu helt trimkompatibla. Om du vill välja fullständig trimning anger du egenskapen $(TrimMode) i projektfilen (.csproj):

<PropertyGroup>
    <TrimMode>Full</TrimMode>
</PropertyGroup>

Detta möjliggör även trimning av analysverktyg, så att varningar introduceras för eventuell problematisk C#-kod.

Mer information finns i Trimningskornighet.

Inbyggd AOT för iOS & Mac Catalyst

I .NET för iOS 9 utnyttjar den interna AOT-kompilering (Ahead of Time) för iOS och Mac Catalyst fullständig trimning för att minska appens paketstorlek och startprestanda. NativeAOT bygger på fullständig trimning genom att även välja en ny körtid.

Viktig

Din app och dess beroenden måste vara helt trimmade för att kunna använda den här funktionen.

NativeAOT kräver att applikationer byggs utan trimmervarningar för att visa att applikationen kommer att fungera korrekt vid körning.

Se även