Ćwiczenie — korzystanie z usługi REST za pomocą klienta HttpClient

  • 20 min

W ramach aplikacji używanej przez inżynierów podczas wizyt w witrynie klienta należy dodać funkcję umożliwiającą inżynierowi wyszukiwanie szczegółów składników elektrycznych. Te informacje będą przechowywane w bazie danych i dostępne za pośrednictwem usługi internetowej REST. Poproszono Cię również o podanie interfejsu umożliwiającego administratorowi tworzenie, usuwanie i modyfikowanie szczegółów części przechowywanych w bazie danych przy użyciu tej samej usługi internetowej REST.

W tym ćwiczeniu wdrożysz usługę internetową REST na platformie Azure, a następnie sprawdzisz, czy możesz uzyskać do niej dostęp przy użyciu przeglądarki internetowej. Następnie dodasz funkcje do istniejącej aplikacji, która używa usługi internetowej REST do pobierania, dodawania, usuwania i aktualizowania szczegółów składników elektrycznych.

Wykonasz to ćwiczenie przy użyciu piaskownicy platformy Azure.

Napiwek

Do kopiowania poleceń do schowka możesz używać przycisku Kopiuj. Aby wkleić, kliknij prawym przyciskiem myszy nowy wiersz w terminalu usługi Cloud Shell i wybierz polecenie Wklej lub użyj skrótu klawiaturowego Shift+Insert (⌘+V w systemie macOS).

Wdrażanie usługi internetowej REST części

  1. W oknie usługi Cloud Shell uruchom następujące polecenie, aby sklonować repozytorium zawierające kod dla tego ćwiczenia, w tym usługę internetową REST części:

    git clone https://github.com/microsoftdocs/mslearn-dotnetmaui-consume-rest-services

  2. Przejdź do folderu Consume-REST-services :

    cd mslearn-dotnetmaui-consume-rest-services/src

  3. Uruchom następujące polecenie, aby wdrożyć usługę internetową Part przy użyciu piaskownicy usługi Azure Cloud Shell. To polecenie udostępnia usługę za pośrednictwem unikatowego adresu URL. Zanotuj ten adres URL po wyświetleniu. Skonfigurujesz aplikację tak, aby łączyła się z usługą internetową przy użyciu tego adresu URL.

    bash initenvironment.sh

Badanie kodu usługi internetowej

Uwaga

Wykonasz resztę tego ćwiczenia na lokalnym komputerze deweloperów.

  1. Na komputerze otwórz okno wiersza polecenia i sklonuj repozytorium na potrzeby tego ćwiczenia. Kod znajduje się w repozytorium net-maui-learn-consume-rest-services .

    git clone https://github.com/microsoftdocs/mslearn-dotnetmaui-consume-rest-services

    Uwaga

    Najlepiej sklonować lub pobrać zawartość ćwiczenia do krótkiej ścieżki folderu, takiej jak C:\dev, aby uniknąć plików generowanych przez kompilację przekraczającą maksymalną długość ścieżki.

  2. Przejdź do folderu src\webservice\PartsServer w klonie repozytorium i otwórz rozwiązanie PartsServer.sln przy użyciu programu Visual Studio lub folderu w programie Visual Studio Code. To rozwiązanie zawiera kopię kodu dla usługi internetowej wdrożonej na platformie Azure w poprzedniej procedurze.

  3. W oknie Eksplorator rozwiązań rozwiń folder Modele. Ten folder zawiera dwa pliki:

    • Part.cs. Klasa Part reprezentuje część dostarczaną przez usługę internetową REST. Pola obejmują identyfikator części, nazwę części, typ części, datę dostępności (po podaniu części) i listę dostawców. Właściwość Href zwraca względny identyfikator URI części. Klient REST może użyć tego identyfikatora URI, aby odwołać się do tej konkretnej części w usłudze internetowej REST. Właściwość Dostawcy zwraca listę dostawców części jako ciąg.

    • PartsFactory.cs. Klasa PartsFactory inicjuje listę części dostarczanych przez usługę przy użyciu małego zestawu ustalonych wartości. W świecie rzeczywistym te dane zostaną pobrane z bazy danych.

  4. W oknie Eksplorator rozwiązań rozwiń folder Kontrolery. Ten folder zawiera następujące pliki:

    • PartsController.cs. Klasa PartsController implementuje internetowy interfejs API dla usługi. Obejmuje ona metody, które umożliwiają aplikacji klienckiej pobranie listy wszystkich części (Get), znalezienie szczegółów określonej części, biorąc pod uwagę identyfikator części (przeciążona wersja get), zaktualizowanie szczegółów części (Put), dodanie nowej części do listy (Post) i usunięcie części z listy (Usuń).

    • LoginController.cs. Klasa LoginController implementuje prostą formę uwierzytelniania dla usługi internetowej. Aplikacja musi wysłać żądanie HTTP GET do tego kontrolera, które zwraca token autoryzacji. Ten token autoryzacji służy do uwierzytelniania żądań wysyłanych do elementu PartsController.

    • BaseController.cs. Klasa BaseController zawiera logikę używaną do uwierzytelniania żądań. Klasa PartsController dziedziczy z tej klasy. Jeśli klient próbuje wywołać metody w klasie PartsController bez podania prawidłowego tokenu uwierzytelniania, metody zwracają odpowiedź HTTP 401 (nieautoryzowana).

Badanie kodu aplikacji klienckiej .NET MAUI

W tym module jest używany zestaw .NET 9.0 SDK. Upewnij się, że masz zainstalowany program .NET 9.0, uruchamiając następujące polecenie w preferowanym terminalu poleceń:

dotnet --list-sdks

Zostanie wyświetlone dane wyjściowe podobne do następującego przykładu:

8.0.100 [C:\Program Files\dotnet\sdk]
9.0.100 [C:\Program Files\dotnet\sdk]

Upewnij się, że na liście znajduje się wersja rozpoczynająca się od 9 . Jeśli na liście nie ma żadnej listy lub polecenie nie zostanie znalezione, zainstaluj najnowszy zestaw SDK platformy .NET 9.0.

  1. Zamknij rozwiązanie PartsServer i otwórz rozwiązanie PartsClient w folderze src\client\PartsClient w sklonowanym repozytorium. To rozwiązanie zawiera częściową implementację aplikacji klienckiej .NET MAUI korzystającej z usługi internetowej PartServer .

  2. W oknie Eksplorator rozwiązań rozwiń folder Dane. Ten folder zawiera kod dla dwóch klas:

    • PartsManager.cs. Klasa PartsManager udostępnia metody, których aplikacja kliencka używa do interakcji z usługą internetową REST. Ta klasa jest obecnie niekompletna; Podczas tego ćwiczenia dodasz niezbędny kod. Po zakończeniu metoda GetClient łączy się z usługą internetową REST. Metoda GetAll zwraca listę części z usługi internetowej REST. Metoda Add dodaje nową część do listy części zarządzanych przez usługę internetową REST. Metoda Update modyfikuje szczegóły części przechowywanej przez usługę internetową REST, a metoda Delete usuwa część.

    • Part.cs. Klasa Part modeluje część przechowywaną w bazie danych. Uwidacznia właściwości, których aplikacja może używać do uzyskiwania dostępu do pól PartID, PartName, PartAvailableDate, PartType i PartSuppliers . Klasa udostępnia również metodę narzędzia o nazwie SupplierString , za pomocą którego aplikacja może pobrać sformatowany ciąg zawierający nazwy dostawców.

  3. W oknie Eksplorator rozwiązań rozwiń folder Pages. Ten folder zawiera znaczniki i kod dla dwóch stron:

    • PartsPage.xaml. Ta strona używa układu CollectionView z elementem DataTemplate , aby wyświetlić szczegóły części dostępnych jako listę. Element DataTemplate używa powiązania danych, aby połączyć dane wyświetlane z częściami pobranymi z usługi internetowej. Możesz wybrać wiersz w obiekcie CollectionView , aby edytować część w dodajpartpage, lub wybrać przycisk Dodaj nową część, aby dodać nową część.

    • AddPartPage.xaml. Ta strona umożliwia użytkownikom wprowadzanie i zapisywanie szczegółów nowej części. Użytkownicy mogą określić nazwę części, typ części i początkowego dostawcę. Identyfikator części i dostępna data części są generowane automatycznie.

  4. W oknie Eksplorator rozwiązań rozwiń folder ViewModels. Ten folder zawiera dwie klasy: AddPartViewModel.cs i PartsViewModel.cs. Są to modele wyświetlania odpowiednich stron i zawierają właściwości i logikę, które strona musi wyświetlać i manipulować danymi.

Zaloguj się do usługi

Usługa REST wymaga uprzedniego zalogowania się w celu uzyskania tokenu autoryzacji. Nie ma uwierzytelniania użytkownika. Najpierw wywołasz określony punkt końcowy, aby uzyskać token autoryzacji, a następnie wyślesz token z powrotem do serwera na każdym kolejnym żądaniu w nagłówku HTTP.

  1. Otwórz plik PartsManager.cs w folderze Dane.

  2. Dodaj pola statyczne BaseAddress i Url zgodnie z definicją w poniższym fragmencie kodu do klasy PartsManager . Zastąp tekstowy adres URL IDZIE TUTAJ adresem URL zanotowaną wcześniej usługą internetową REST:

    public class PartsManager
{
    static readonly string BaseAddress = "URL GOES HERE";
    static readonly string Url = $"{BaseAddress}/api/";
    ...
}

  3. Dodaj następujące pole do klasy po polu Adres URL . To pole będzie przechowywać token autoryzacji zwrócony po zalogowaniu się użytkownika:

    private static string authorizationKey;

  4. Znajdź metodę GetClient . Ta metoda zgłasza obecnie wyjątek NotImplementedException . Zastąp istniejący kod w tej metodzie następującym kodem. Ten kod tworzy obiekt HttpClient , a następnie wysyła żądanie do punktu końcowego logowania usługi internetowej REST. Usługa powinna odpowiedzieć komunikatem zawierającym token autoryzacji. Deserializuj ten token i dodaj go jako domyślny nagłówek żądania autoryzacji dla kolejnych żądań wysyłanych przy użyciu obiektu HttpClient :

    private static async Task<HttpClient> GetClient()
{
    if (client != null)
        return client;

    client = new HttpClient();

    if (string.IsNullOrEmpty(authorizationKey))
    {                
        authorizationKey = await client.GetStringAsync($"{Url}login");
        authorizationKey = JsonSerializer.Deserialize<string>(authorizationKey);
    }

    client.DefaultRequestHeaders.Add("Authorization", authorizationKey);
    client.DefaultRequestHeaders.Add("Accept", "application/json");

    return client;
}

Wykonywanie operacji GET w celu pobrania informacji dotyczących części

  1. W pliku PartsManager.cs znajdź metodę GetAll. Jest to metoda asynchroniczna, która zwraca wyliczalną listę części. Ta metoda nie została jeszcze zaimplementowana.

  2. W tej metodzie usuń kod, który zgłasza wyjątek NotImplementedException .

  3. Sprawdź, czy urządzenie ma łączność z Internetem Connectivity przy użyciu klasy . Jeśli internet nie jest obecny, zwróć pusty List<Part>element .

    if (Connectivity.Current.NetworkAccess != NetworkAccess.Internet)
    return new List<Part>();

  4. Wywołaj metodę GetClient, aby pobrać obiekt HttpClient do pracy. Pamiętaj, że element GetClient jest asynchroniczny, dlatego użyj operatora await , aby przechwycić obiekt zwrócony przez tę metodę.

  5. Wywołaj metodę GetStringAsync obiektu HttpClient i podaj podstawowy adres URL, aby pobrać tablicę części z usługi internetowej REST. Dane są zwracane asynchronicznie jako ciąg JSON.

  6. Deserializuj ciąg JSON zwrócony przez tę metodę do listy obiektów części przy użyciu metody JsonSerializer.Deserialize . Zwróć tę listę do wywołującego.

    Ukończona metoda powinna wyglądać następująco:

    public static async Task<IEnumerable<Part>> GetAll()
{
    if (Connectivity.Current.NetworkAccess != NetworkAccess.Internet)
        return new List<Part>();

    var client = await GetClient();
    string result = await client.GetStringAsync($"{Url}parts");

    return JsonSerializer.Deserialize<List<Part>>(result, new JsonSerializerOptions
        {
            PropertyNameCaseInsensitive = true,
        });                     
}

  7. Skompiluj i uruchom aplikację. Po uruchomieniu aplikacji zostanie wyświetlona strona Lista części i powinna zostać wyświetlona lista części pobranych przez metodę GetAll . Na poniższej ilustracji przedstawiono aplikację działającą w systemie Android:

    Zrzut ekranu przedstawiający aplikację Klienta części uruchomioną w systemie Android z listą części.

  8. Po zakończeniu przeglądania danych zamknij aplikację i wróć do programu Visual Studio lub Visual Studio Code.

Wykonywanie operacji POST w celu dodania nowej części do bazy danych

  1. W klasie PartsManager znajdź metodę Add. Ta metoda zawiera parametry nazwy części, dostawcy i typu części. Metoda jest asynchroniczna. Celem metody jest wstawienie nowej części do bazy danych i zwrócenie obiektu Part reprezentującego nowo utworzony element.

  2. Usuń istniejący kod w metodzie .

  3. Sprawdź, czy urządzenie ma łączność z Internetem Connectivity przy użyciu klasy . Jeśli internet nie jest obecny, zwróć pusty Partelement .

    if (Connectivity.Current.NetworkAccess != NetworkAccess.Internet)
    return new Part();

  4. Utwórz nowy obiekt part . Wypełnij pola danymi przekazanymi:

    • Ustaw pole PartID na pusty ciąg. Ten identyfikator zostanie wygenerowany przez usługę internetową REST.
    • Utwórz nową listę do przechowywania nazwy dostawcy.
    • Ustaw pole PartAvailableDate na DateTime.Now.
    • Pobierz klienta HTTP z metody GetClient .
    var part = new Part()
{
    PartName = partName,
    Suppliers = new List<string>(new[] { supplier }),
    PartID = string.Empty,
    PartType = partType,
    PartAvailableDate = DateTime.Now.Date
};

  5. Wywołaj metodę GetClient, aby pobrać obiekt HttpClient do pracy.

  6. Utwórz HttpRequestMessage obiekt. Ten obiekt służy do modelowania żądania wysyłanego do usługi internetowej. Zainicjuj go za pomocą parametrów wskazujących czasownik HTTP do użycia i adres URL usługi internetowej do komunikowania się z.

    var msg = new HttpRequestMessage(HttpMethod.Post, $"{Url}parts");

  7. Aby utworzyć informacje o składniku Part, musisz wysłać ładunek do usługi internetowej. Ten ładunek zostanie serializowany do formatu JSON. Ładunek JSON zostanie dodany do HttpRequestMessage.Content właściwości i zostanie zserializowany za pomocą JsonContent.Create metody .

    msg.Content = JsonContent.Create<Part>(part);

  8. Teraz wyślij komunikat do usługi internetowej za HttpClient.SendAsync pomocą funkcji . Ta funkcja zwróci HttpResponseMessage obiekt, który zawiera informacje o operacji na serwerze. Takie jak kody odpowiedzi HTTP i informacje przekazywane z powrotem z serwera.

    var response = await client.SendAsync(msg);
response.EnsureSuccessStatusCode();

    Zwróć uwagę, że powyższe używa response.EnsureSuccessStatusCode metody . Spowoduje to zwrócenie błędu, jeśli zostanie zwrócony inny kod stanu HTTP 2xx.

  9. Jeśli usługa internetowa zwraca informacje, takie jak obiekt serializowany w formacie JSON, możesz go odczytać z pliku HttpResponseMessage. Następnie można deserializować kod JSON przy użyciu polecenia JsonSerializer.Deserialize.

    var returnedJson = await response.Content.ReadAsStringAsync();

var insertedPart = JsonSerializer.Deserialize<Part>(returnedJson, new JsonSerializerOptions
        {
            PropertyNameCaseInsensitive = true,
        });

  10. Na koniec zwróć nową wstawioną część.

    return insertedPart;

  11. Skompiluj i uruchom aplikację. Wybierz przycisk Dodaj nową część i wprowadź nazwę, typ i dostawcę, aby utworzyć nową część. Wybierz pozycję Zapisz. Metoda Add w klasie PartsManager zostanie wywołana, co spowoduje utworzenie nowej części w usłudze internetowej. Jeśli operacja zakończy się pomyślnie, strona listy części pojawi się ponownie z nową częścią w dolnej części listy.

    Zrzut ekranu przedstawiający aplikację działającą po dodaniu nowej części. Nowa część znajduje się w dolnej części listy.

  12. Po zakończeniu przeglądania danych zamknij aplikację i wróć do programu Visual Studio lub Visual Studio Code.

Wykonaj operację PUT, aby zaktualizować szczegóły części bazy danych

  1. W klasie PartsManager znajdź metodę Update. Jest to metoda asynchroniczna, która przyjmuje obiekt Part jako parametr. Metoda nie ma jawnej wartości zwracanej. Jednak zwracany typ to Zadanie , aby wyjątki były prawidłowo zwracane do elementu wywołującego. Zaimplementujmy funkcję PUT .

  2. Usuń istniejący kod.

  3. Tak jak poprzednio, sprawdź, czy jest dostępne połączenie internetowe.

    if (Connectivity.Current.NetworkAccess != NetworkAccess.Internet)
    return;

  4. Utwórz nowy HttpRequestMessageelement , tym razem określając operację PUT i adres URL aktualizacji części.

    HttpRequestMessage msg = new(HttpMethod.Put, $"{Url}parts/{part.PartID}");

  5. Content Ustaw właściwość HttpRequestMessage przy użyciu JsonContent.Create funkcji i parametru części, który został przekazany do funkcji.

    msg.Content = JsonContent.Create<Part>(part);

  6. Pobierz klienta HTTP z metody GetClient .

    var client = await GetClient();

  7. Wyślij żądanie za pomocą polecenia HttpClient , a następnie upewnij się, że przebiegł pomyślnie.

    var response = await client.SendAsync(msg);
response.EnsureSuccessStatusCode();

  8. Skompiluj i uruchom aplikację. Wybierz jedną z części z listy. Zostanie wyświetlona strona Dodajpart , tym razem z wypełnionymi już właściwościami. Zaktualizuj wszystko, co chcesz.

  9. Wybierz pozycję Zapisz. Spowoduje to wywołanie metody Update w klasie PartsManager w celu wysłania zmian do usługi internetowej. W przypadku pomyślnego wyświetlenia strony listy części zostaną odzwierciedlone zmiany.

    Zrzut ekranu przedstawiający aplikację uruchomioną z pierwszym elementem na liście zaktualizowanym.

    Uwaga

    Część dodana w poprzednim zadaniu nie będzie wyświetlana na stronie Lista części. Dane używane przez aplikację są resetowane do listy wstępnie zdefiniowanych części przy każdym uruchomieniu aplikacji. Jest to zapewnienie spójności na potrzeby testowania aplikacji.

Wykonaj operację DELETE, aby usunąć szczegóły części z bazy danych

  1. W klasie PartsManager znajdź metodę Delete. Jest to metoda asynchroniczna, która przyjmuje ciąg partId i zwraca zadanie.

  2. Usuń istniejący kod.

  3. Sprawdź połączenie internetowe.

    if (Connectivity.Current.NetworkAccess != NetworkAccess.Internet)
    return;

  4. Utwórz nowy HttpRequestMessage obiekt. Tylko teraz określ czasownik HTTP DELETE i adres URL, aby usunąć część.

    HttpRequestMessage msg = new(HttpMethod.Delete, $"{Url}parts/{partID}");

  5. Pobierz klienta HTTP z metody GetClient .

    var client = await GetClient();

  6. Wyślij żądanie do usługi internetowej. Sprawdź powodzenie po jego powrocie.

    var response = await client.SendAsync(msg);
response.EnsureSuccessStatusCode();

  7. Skompiluj i uruchom aplikację. Wybierz część z listy, a następnie wybierz pozycję Usuń na stronie Dodawanie części . W przypadku powodzenia strona Lista części zostanie ponownie wyświetlona, a usunięta część nie będzie już widoczna.