Aplikacje mobilne · Pierwszy projekt

Pierwszy projekt .NET MAUI: struktura i podstawy XAML

Czas utworzyć pierwszą prawdziwą aplikację MAUI. Zobaczysz, z jakich plików składa się świeży projekt, czym jest XAML i jak łączy się z kodem C#, dokładnie tak samo jak w WPF, tylko z innymi nazwami klas (ContentPage zamiast Window).

około 45 minut
.NET MAUI · XAML · code-behind
INF.04.6.2

Po tej lekcji: utworzyć projekt .NET MAUI App, rozpoznać role plików projektu, napisać stronę w XAML i obsłużyć kliknięcie przycisku w C#.

Przycisk, który wita po imieniu

Najpierw zbudujesz małą aplikację: wpisujesz imię, klikasz i dostajesz odpowiedź. Dzięki temu nazwy XAML i C# od razu będą miały sens.

Najpierw uruchomisz mały ekran. Potem połączysz go z kodem i sprawdzisz konkretne wyniki. Dodatki wykonuj dopiero, gdy wersja podstawowa działa. Quiz i oceniane zadania pozostają w biurku po zalogowaniu.

Laboratorium · ćwiczenie w przeglądarce, do którego odsyłają rozgrzewki na końcu lekcji

4 · Sprawdź w działaniu

Pierwsza strona MAUI, bez instalowania czegokolwiek

Wpisz imię w polu i kliknij przycisk. W zakładce .xaml.cs zmień komunikat (np. na „Miło Cię poznać”). Spróbuj też zmienić nazwę metody w jednym z plików, a zobaczysz błąd, który zobaczyłbyś w Visual Studio.

Najpierw przewidź, potem sprawdź: Wpisz w podglądzie różne imiona i uruchom przycisk. Potem zmień tekst przycisku w XAML. Odróżnij tekst widoczny na ekranie od nazwy metody Clicked.

Nazwa w Clicked="…" musi być identyczna z nazwą metody w C#. Brak x:Name oznacza, że kontrolki nie zobaczysz w kodzie. Model pomaga zobaczyć mechanizm; właściwą aplikację uruchomisz z plików poniżej.

1. Przygotuj miejsce pracy

W Visual Studio wybierz Utwórz nowy projekt → .NET MAUI App, nie MAUI Blazor Hybrid. Nazwij projekt PierwszaAplikacjaMaui, żeby namespace pasował do przykładów. Każdy temat możesz robić w osobnym katalogu, nawet gdy nazwa projektu się powtarza.
Wybierz .NET10 i najpierw uruchom niezmieniony szablon na Windows Machine. Gdy masz działające środowiskoAndroid, później wybierz własne urządzenie lub emulator.
Zatrzymaj debugowanie przed dodawaniem klas i zmianą sposobu startu. Zachowaj App.xaml, Resources i pliki platform z szablonu.

Co dodajesz, a co podmieniasz?

Stronę dodaj przez Projekt → Dodaj → Nowy element → .NET MAUI ContentPage (XAML). Powstaje para .xaml i .xaml.cs. Dla ContentView wybierz szablon ContentView; dla modeli i serwisów zwykłą klasę. Jeśli plik już istnieje, podmień wskazaną zawartość — nie twórz drugiej klasy o tej samej nazwie.

Plik	Rola w ćwiczeniu
MainPage.xaml	Wygląd strony lub kontrolki
MainPage.xaml.cs	Logika i obsługa danych

Zanim uruchomisz: trzy połączenia

x:Class="PierwszaAplikacjaMaui.NazwaStrony" w XAML musi zgadzać się z namespace PierwszaAplikacjaMaui i nazwą klasy C#. InitializeComponent() tworzy kontrolki opisane w XAML.

x:Name="PoleImie" daje kodowi C# dostęp przez PoleImie.Text. Z kolei Clicked="Zapisz_Clicked" wskazuje metodę o tej nazwie w pliku .xaml.cs. Sam napis przycisku w Text niczego nie podpina.

Gdy dodajesz XAML z obsługą zdarzeń, od razu uzupełnij też odpowiadający C#. Uruchamiaj dopiero po skończeniu oznaczonej pary plików; brakujący handler nie jest błędem środowiska.

2. Uruchom sam wygląd — jeszcze bez logiki

W świeżym projekcie zastąp MainPage.xaml poniższym ekranem. W MainPage.xaml.cs zachowaj konstruktor z InitializeComponent(); usuń szablonowy licznik i OnCounterClicked, bo nie ma ich już w XAML. Na tym etapie App i AppShell pozostają z szablonu. To pełny, tymczasowy XAML — później świadomie go podmienisz, nie dokleisz do drugiego ContentPage.

MainPage.xaml — etap tymczasowyxaml

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="PierwszaAplikacjaMaui.MainPage">
    <VerticalStackLayout Padding="24" Spacing="14">
        <Label Text="Jak masz na imię?" FontSize="24" />
        <Entry Placeholder="Wpisz imię" />
        <Button Text="Jeszcze bez obsługi kliknięcia" />
    </VerticalStackLayout>
</ContentPage>

Pierwsza próba Uruchom. Zobaczysz kontrolki, ale przyciski bez Clicked jeszcze nic nie robią. Sprawdź rozmiar i kolejność elementów. Zatrzymaj aplikację przed następnym etapem.

Zacznijmy od znajomego pomysłu

Wygląd osobno, działanie osobno, jak w WPF

Podział na XAML (wygląd) i plik **.xaml.cs** (logika) działa tak samo jak w WPF. Jedna osoba w zespole może zajmować się wyglądem, a druga logiką, bez wchodzenia sobie w drogę.

Zmieniają się nazwy: zamiast Window jest **ContentPage**, zamiast TextBox jest **Entry, a kliknięcie przycisku to zdarzenie Clicked** (nie Click).

1 · Zacznij od projektu

Utwórz projekt .NET MAUI App

Szablon „.NET MAUI App” pojawia się tylko wtedy, gdy zaznaczone jest obciążenie .NET Multi-platform App UI development. Zaznaczaj kroki w trakcie.

Visual Studio → Nowy projekt i wyszukaj .NET MAUI App.
Nadaj nazwę, np. PierwszaAplikacjaMaui, i kliknij Utwórz.
Obok zielonego przycisku Start wybierz urządzenie. Na początek najprościej Windows Machine (zwykłe okno, bez emulatora).
Naciśnij Start. Zobaczysz gotowy szablon z licznikiem kliknięć.
Później, gdy chcesz sprawdzić zachowanie mobilne, wybierz emulator Androida.

2 · Co jest w środku

Pliki i foldery świeżego projektu

Plik lub folder	Rola
`MauiProgram.cs`	Punkt startowy: konfiguracja i uruchomienie aplikacji (odpowiednik `Program.cs`).
`App.xaml` / `App.xaml.cs`	Zasoby globalne (style całej aplikacji) i logika startowa: która strona ma być pierwsza.
`AppShell.xaml` / `AppShell.xaml.cs`	Nawigacja: „mapa aplikacji” mówiąca, jakie strony istnieją i jak się między nimi poruszać (Shell).
`MainPage.xaml` / `MainPage.xaml.cs`	Interfejs i logika głównej strony. To Twój odpowiednik `MainWindow` z WPF.
`Resources/Fonts`, `Images`, `Styles`, `Raw`	Czcionki, grafiki i ikony, style XAML oraz pliki dołączane w oryginalnej postaci (np. JSON).
`Platforms/`	Kod specyficzny dla Androida, iOS, Windows i MacCatalyst. Na start prawie nigdy tu nic nie zmieniasz.

AppShell działa jak spis treści aplikacji. W tej lekcji jest tylko jedna strona, więc jest minimalny. Pełną nawigacją zajmiemy się osobno.

3 · Jeśli znasz HTML

Co jest czym

HTML i CSS	XAML (.NET MAUI)
HTML opisuje strukturę strony	XAML opisuje strukturę aplikacji
CSS nadaje styl	Styl i układ są w kontrolkach albo w plikach `Styles`
`<button>Kliknij</button>`	`<Button Text="Kliknij" />`
`<input type="text">`	`<Entry />`
`<div>`	`<VerticalStackLayout>`

Ten sam XAML działa na Androidzie, iOS i Windows. Czasem wymaga drobnych dostosowań do platformy, o czym będzie osobna lekcja.

7 · Zapamiętaj różnice

Te same pojęcia, inne nazwy

WPF	.NET MAUI
`Window`	`ContentPage`
`TextBox`	`Entry`
`Click`	`Clicked`
`Content` na przycisku	`Text` na przycisku
`HorizontalAlignment`	`HorizontalOptions`
`StackPanel`	`VerticalStackLayout` / `HorizontalStackLayout`

W MAUI zarówno napis na przycisku, jak i w etykiecie to `Text`. Nie ma kłopotu z `Content` kontra `Text`.

3. Wskaż stronę startową ćwiczenia

Po dodaniu docelowych stron podmień App.xaml.cs na poniższy. App.xaml zostaje z szablonu. Od tej chwili startuje MainPage, a nie wcześniejszy tymczasowy MainPage z AppShell. Uzupełnij jej pliki w kolejnych etapach, zanim ponownie uruchomisz projekt.

App.xaml.cscsharp

namespace PierwszaAplikacjaMaui;

public partial class App : Application
{
    public App() => InitializeComponent();
    protected override Window CreateWindow(IActivationState? activationState)
        => new Window(new NavigationPage(new MainPage()));
}

CreateWindow Tworzy okno aplikacji. NavigationPage jest kontenerem zwykłych stron i daje przycisk powrotu; nie łączymy go z Shell.
new MainPage() Tworzy instancję docelowej strony. Aby testować drugi niezależny przykład, zatrzymaj program, zmień tylko ten typ i uruchom ponownie.

4. Połącz wygląd z działaniem

Teraz zbuduj docelowy przykład. Pełne pliki poniżej zastępują swoje wcześniejsze wersje. Przeczytaj opis nad kodem i objaśnienia pod nim; potem sprawdź przepływ danych, nie tylko brak czerwonych podkreśleń.

Gdy przykład ma kilka plików zależnych od siebie, najpierw dodaj wszystkie wskazane typy, a potem uruchom całość. Ustaw breakpoint w obsłudze głównego przycisku i prześledź jedną próbę.

Budowa krok po kroku

MainPage.xaml

Zamień tymczasowy ekran na poniższy. Teraz Entry ma nazwę PoleTekstowe, Button wskazuje OnButtonClicked, a EtykietaWynik odbierze odpowiedź.

ContentPage to główny kontener strony, wewnątrz jest layout, a w nim kontrolki.

MainPage.xamlxaml

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="PierwszaAplikacjaMaui.MainPage">

    <!-- VerticalStackLayout układa elementy jeden pod drugim -->
    <VerticalStackLayout Padding="30" Spacing="20">

        <Label Text="Witaj w .NET MAUI!"
               FontSize="26"
               HorizontalOptions="Center" />

        <Entry x:Name="PoleTekstowe"
               Placeholder="Wpisz swoje imię"
               FontSize="18" />

        <Button Text="Kliknij mnie"
                Clicked="OnButtonClicked" />

        <Label x:Name="EtykietaWynik"
               FontSize="22"
               TextColor="DarkBlue"
               HorizontalOptions="Center" />

    </VerticalStackLayout>
</ContentPage>

x:Class="PierwszaAplikacjaMaui.MainPage" Łączy plik XAML z klasą w C#. Przy kopiowaniu kodu z innego projektu musisz dopasować tę nazwę.
VerticalStackLayout Padding="30" Spacing="20" Pionowy układ z marginesem wewnętrznym i odstępem między elementami.
Entry x:Name="PoleTekstowe" Pole tekstowe (odpowiednik TextBox). Placeholder to szary podpowiadający tekst.
Button Clicked="OnButtonClicked" Podpięcie metody do zdarzenia kliknięcia.
HorizontalOptions="Center" Wyśrodkowanie w poziomie (odpowiednik HorizontalAlignment z WPF).

Budowa krok po kroku

MainPage.xaml.cs

Podmień całą klasę MainPage, zachowując namespace. Kliknięcie odczytuje Text z Entry, buduje napis i wpisuje go do innej kontrolki. To trzy osobne czynności.

Konstruktor wywołuje InitializeComponent(), a metoda OnButtonClicked odczytuje pole i pokazuje powitanie.

MainPage.xaml.cscsharp

namespace PierwszaAplikacjaMaui;

// „partial class” oznacza, że klasa jest podzielona na dwie części:
// 1. część w pliku XAML (MainPage.xaml),
// 2. część w pliku C# (MainPage.xaml.cs).
// Obie razem tworzą jedną klasę MainPage.
public partial class MainPage : ContentPage
{
    public MainPage()
    {
        // InitializeComponent() odczytuje XAML, tworzy wszystkie
        // kontrolki (Label, Button, Entry) i łączy je z tą klasą.
        InitializeComponent();
    }

    // Metoda obsługująca kliknięcie przycisku.
    private void OnButtonClicked(object sender, EventArgs e)
    {
        string imie = PoleTekstowe.Text;
        EtykietaWynik.Text = $"Witaj, {imie}!";
    }
}

partial class MainPage : ContentPage Klasa jest podzielona na dwie części: XAML i C#. Razem tworzą jedną klasę.
InitializeComponent() Czyta XAML, tworzy kontrolki i łączy je z klasą. Bez niego strona byłaby pusta.
PoleTekstowe.Text Tekst wpisany przez użytkownika. W MAUI zarówno Label, Button, jak i Entry używają właściwości Text.
$"Witaj, {imie}!" Napis z wstawioną wartością zmiennej.

5. Odbiór: czy naprawdę działa?

Wykonaj próby w swojej aplikacji, nie tylko w modelu na stronie. Zaznaczaj dopiero po sprawdzeniu wyniku. Funkcje urządzenia wymagają testu na właściwej platformie.

Wpisz Ola i kliknij przycisk. Etykieta wyniku powinna zawierać imię Ola.
Zmień tylko napis przycisku. Działanie ma pozostać takie samo, bo Clicked nadal wskazuje tę samą metodę.
W Visual Studio postaw breakpoint w OnButtonClicked. Po kliknięciu sprawdź wartość PoleTekstowe.Text.

8 · Czego unikać

Cztery błędy z pierwszego projektu

Niezgodny `x:Class`

Tak nie

x:Class="StaraNazwa.MainPage"   // po skopiowaniu z innego projektu

Aplikacja się nie kompiluje, bo klasa nie istnieje pod tą nazwą.

Tak

x:Class="PierwszaAplikacjaMaui.MainPage"

Nazwa w XAML musi zgadzać się z przestrzenią nazw i klasą w C#.

Brak `x:Name`

Tak nie

<Entry Placeholder="Imię" />

// w C#:
string imie = PoleTekstowe.Text;

Błąd CS0103: nazwa nie istnieje w bieżącym kontekście.

Tak

<Entry x:Name="PoleTekstowe" Placeholder="Imię" />

Bez x:Name kontrolka nie ma nazwy w kodzie.

`Click` zamiast `Clicked`

Tak nie

<Button Text="OK" Click="OnButtonClicked" />

Błąd XAML: w MAUI przycisk nie ma zdarzenia Click.

Tak

<Button Text="OK" Clicked="OnButtonClicked" />

Zdarzenie przycisku w MAUI nazywa się Clicked.

Niewybrane urządzenie docelowe

Tak nie

Pasek narzędzi: brak wybranego urządzenia

Aplikacja się nie uruchomi.

Tak

Wybierz „Windows Machine” albo emulator przed naciśnięciem Start

Visual Studio musi wiedzieć, gdzie uruchomić aplikację.

Ćwiczenie z pomocą · samodzielna praca

6. Mała zmiana, którą zrobisz samodzielnie

Dopisz do powitania nazwę swojej klasy.

Oczekiwany rezultat

Dopisz do powitania nazwę swojej klasy.
Dotychczasowe działanie ma pozostać poprawne.

Potrzebujesz pomocy? Rozwiązuj krok po kroku.

Krok 1 — pokaż podpowiedź

Znajdź interpolowany napis zaczynający się od $ i fragment {imie}.

Krok 2 — pokaż podpowiedź

Dodaj nazwę klasy jako zwykły tekst wewnątrz tego samego napisu.

Krok 3 — pokaż podpowiedź

Nie zmieniaj nazwy PoleTekstowe, jeśli nie zmieniasz też x:Name w XAML.

Otwórz tylko tyle podpowiedzi, ile potrzebujesz. Po każdym kroku wróć do zadania i sprawdź wynik.

9 · Sprawdź się

WPF czy MAUI?

Cztery krótkie sytuacje.

Podsumowanie

Co warto zapamiętać

Szablon „.NET MAUI App” wymaga obciążenia MAUI. Na start wybierz urządzenie „Windows Machine”.
Projekt: MauiProgram.cs (start), App.xaml (style), AppShell (nawigacja), MainPage (strona), Resources, Platforms.
XAML opisuje wygląd, .xaml.cs logikę. x:Class i x:Name łączą je ze sobą.
ContentPage zastępuje Window, Entry zastępuje TextBox, Clicked zastępuje Click.
Nazwa metody w Clicked="..." musi być identyczna z nazwą w C#.

Dalej na swoim koncie

Rozgrzewki, quiz i zadania są w biurku ucznia.

Teoria jest otwarta dla wszystkich. Żeby rozwiązywać zadania, zapisywać szkice i widzieć swój postęp, zaloguj się.

Zaloguj się →

Źródła i dalsza nauka