Nie działa Entity Framework

Niedziałający Entity Framework wskazuje na brak zainstalowanego pakietu NuGet lub niezgodność wersji frameworka z docelowym środowiskiem .NET.

Nie działa Entity Framework – czym objawia się problem

Hasło „Nie działa Entity Framework” może oznaczać kilka różnych sytuacji związanych z projektem .NET, konfiguracją aplikacji albo sposobem komunikacji z bazą danych. W jednym przypadku aplikacja nie kompiluje się, ponieważ brakuje przestrzeni nazw lub pakietu NuGet. W innym kod uruchamia się poprawnie, lecz pojawia się wyjątek podczas tworzenia kontekstu danych, wykonywania zapytania albo zapisywania zmian. Zdarza się również, że projekt działa na komputerze deweloperskim, a po wdrożeniu przestaje łączyć się z bazą, ponieważ środowisko uruchomieniowe, pliki konfiguracyjne lub dostępne sterowniki nie odpowiadają ustawieniom użytym podczas programowania.

Entity Framework jest warstwą pośrednią między kodem aplikacji a relacyjną bazą danych. Pozwala opisywać tabele za pomocą klas, budować zapytania w języku C# i wykonywać operacje bez ręcznego zapisywania każdego polecenia SQL. Nie oznacza to jednak, że cała obsługa bazy zostaje ukryta. Nadal znaczenie mają typ użytej bazy, poprawność łańcucha połączenia, uprawnienia użytkownika, migracje, wersja biblioteki oraz zgodność projektu z konkretną wersją platformy .NET.

Przy diagnozowaniu problemu ważne jest ustalenie, na jakim etapie występuje błąd. Inaczej analizuje się komunikat pojawiający się podczas kompilacji, inaczej wyjątek przy uruchamianiu aplikacji, a jeszcze inaczej niepoprawny wynik zapytania. Samo ponowne zainstalowanie pakietu nie zawsze rozwiązuje przyczynę, a czasem może dodatkowo zmienić zależności projektu.

Entity Framework a wersje .NET, pakiety i model danych

Jednym z częstych źródeł kłopotów jest pomieszanie dwóch rodzin technologii: starszego Entity Framework przeznaczonego dla klasycznego .NET Framework oraz Entity Framework Core używanego w nowoczesnych aplikacjach .NET. Nazwy są podobne, ale pakiety, przestrzenie nazw, mechanizmy konfiguracji i sposób rejestrowania kontekstu mogą się różnić. Kod przygotowany dla jednej odmiany nie zawsze można bezpośrednio przenieść do drugiej. Przed rozpoczęciem naprawy należy sprawdzić plik projektu, docelową platformę, wersję SDK oraz biblioteki wymienione w sekcji zależności.

W projekcie opartym na Entity Framework Core zwykle potrzebny jest właściwy pakiet dostawcy dla wybranej bazy danych. Biblioteka ogólna nie wystarcza, jeżeli aplikacja ma korzystać z konkretnego silnika. Niezbędne mogą być także narzędzia do tworzenia migracji. Należy zweryfikować, czy wszystkie pakiety mają kompatybilne wersje oraz czy nie występują zależności wymagające innej wersji .NET. Warto przejrzeć plik projektu i historię zmian, ponieważ ręczne aktualizowanie jednej biblioteki przy pozostawieniu pozostałych w starszych wersjach może prowadzić do konfliktów.

Problemy mogą wynikać także z modelu danych. Jeżeli nazwa właściwości nie odpowiada nazwie kolumny, typ danych jest niezgodny albo relacja między encjami została opisana niejednoznacznie, zapytanie może zakończyć się wyjątkiem. Przydatne jest jawne określenie kluczy głównych, relacji, wymaganych pól i sposobu mapowania nazw. W przypadku zmian struktury bazy trzeba ustalić, czy zastosowano migracje, czy baza jest tworzona z gotowego skryptu, a także czy aktualny schemat rzeczywiście odpowiada wersji kodu.

Porównanie z bezpośrednim użyciem SQL pomaga zrozumieć zakres odpowiedzialności Entity Framework. Przy ręcznym wykonywaniu zapytań większa część konfiguracji pozostaje po stronie programisty. Przy mapowaniu obiektowo-relacyjnym wiele czynności wykonuje biblioteka, lecz wymaga ona prawidłowo zdefiniowanego modelu i kontekstu. Błąd zgłoszony przez Entity Framework może więc wskazywać zarówno na problem w kodzie, jak i na niedostępność samej bazy.

Błędy Entity Framework i typowe przyczyny

Jeżeli kompilator nie rozpoznaje typu DbContext, DbSet albo przestrzeni nazw związanej z Entity Framework, należy najpierw sprawdzić zależności projektu i zgodność instrukcji using z używaną biblioteką. Warto odróżnić brak pakietu od błędnej nazwy typu. Po zmianie wersji biblioteki część metod może mieć inne sygnatury, a przykłady znalezione w starszej dokumentacji mogą nie pasować do aktualnego projektu.

Komunikat o braku możliwości utworzenia DbContext często wiąże się z niepoprawną rejestracją usługi, brakiem konstruktora przyjmującego opcje albo niewłaściwym odczytem konfiguracji. W aplikacji korzystającej z wstrzykiwania zależności trzeba sprawdzić, czy kontekst został zarejestrowany i czy przekazywany jest właściwy łańcuch połączenia. W narzędziach służących do migracji może być potrzebny sposób wskazania projektu startowego oraz projektu zawierającego kontekst.

Wyjątki typu connection refused, timeout lub login failed zwykle wskazują na problem z dostępem do bazy, a nie na uszkodzenie samego Entity Framework. Należy sprawdzić adres serwera zapisany w konfiguracji, nazwę bazy, sposób uwierzytelniania, dostępność portu, reguły zapory oraz uprawnienia konta. Jeżeli aplikacja działa w innym środowisku niż to, w którym tworzono projekt, trzeba porównać zmienne środowiskowe i pliki konfiguracyjne. Nie powinno się zakładać, że ten sam zapis połączenia zadziała na każdym komputerze.

Błąd podczas migracji może wynikać z rozbieżności między aktualnym modelem a historią migracji. Pomocne bywa sprawdzenie listy migracji, statusu bazy oraz zmian wykonanych ręcznie. Usuwanie tabel lub plików migracji bez kopii zapasowej może doprowadzić do utraty danych albo utrudnić odtworzenie poprzedniego schematu. Przed taką operacją należy zachować kopię projektu i bazy oraz ustalić, czy dane mogą zostać ponownie utworzone.

Niepoprawne działanie zapytań może mieć źródło w opóźnionym wykonaniu. Część zapytań jest budowana dopiero w chwili enumerowania wyników, na przykład po wywołaniu ToList, First, Single lub podobnej metody. Błąd może zatem pojawić się nie przy deklaracji zapytania, lecz dopiero przy jego wykonaniu. Warto również sprawdzić, czy połączenie nie jest zamykane zbyt wcześnie, czy kontekst nie jest używany równocześnie przez wiele operacji oraz czy zapytanie nie odwołuje się do danych, których nie można przetłumaczyć na SQL.

Sprawdzanie „Nie działa Entity Framework” krok po kroku

Najbezpieczniej rozpocząć od zapisania pełnego komunikatu błędu wraz z wewnętrznym wyjątkiem. Krótki tekst wyświetlany użytkownikowi często nie pokazuje przyczyny. Należy zanotować, czy błąd występuje podczas budowania projektu, uruchamiania aplikacji, wykonywania migracji, odczytu danych czy zapisu zmian. Pomocne są także informacje o używanej wersji .NET, rodzaju bazy, systemie operacyjnym oraz o tym, czy problem pojawił się po aktualizacji biblioteki lub zmianie konfiguracji.

Następnie można wykonać kontrolę zależności. W pliku projektu powinny znajdować się właściwe pakiety, bez przypadkowego połączenia bibliotek przeznaczonych dla różnych generacji technologii. Warto wyczyścić artefakty kompilacji, przywrócić zależności i zbudować projekt ponownie. Takie działanie pomaga wykluczyć uszkodzone pliki tymczasowe, ale nie zastępuje analizy wersji. Jeżeli po przebudowaniu problem pozostaje, należy porównać wersję SDK używaną w terminalu z wersją ustawioną dla projektu.

Kolejny etap to kontrola konfiguracji połączenia. Łańcuch połączenia powinien być odczytywany z właściwego źródła, a jego wartość nie powinna być przypadkowo nadpisywana przez konfigurację środowiska testowego lub produkcyjnego. Nie należy umieszczać danych uwierzytelniających w publicznym repozytorium. Przydatne jest wykonanie niezależnego testu dostępu do bazy oraz sprawdzenie, czy konto posiada wymagane uprawnienia do odczytu, zapisu i zmian schematu.

Jeżeli problem dotyczy migracji, trzeba porównać trzy elementy: model zapisany w kodzie, listę migracji oraz rzeczywistą strukturę bazy. Różnice między nimi mogą wyjaśnić brak kolumny, nieistniejącą tabelę lub konflikt klucza. W środowisku z ważnymi danymi każdą zmianę schematu powinno się najpierw przetestować na kopii. Warto też ustalić, czy aplikacja ma automatycznie wykonywać migracje przy starcie, czy proces ten jest kontrolowany osobno.

Duże znaczenie ma ograniczenie zakresu testu. Niewielki przykład z jednym kontekstem, prostą encją i pojedynczym odczytem pozwala ustalić, czy błąd dotyczy podstawowej konfiguracji, czy większej części aplikacji. Gdy prosty przypadek działa, dalszej analizy wymagają konkretne relacje, zapytania, konwersje typów lub logika zapisu.

Kiedy zgłosić się z problemem Entity Framework do serwisu

Zgłoszenie do serwisu może być zasadne, gdy aplikacja przestała działać po aktualizacji systemu, środowiska programistycznego albo sterownika bazy, a sam komunikat nie wskazuje jednoznacznej przyczyny. Warto przekazać pełny opis objawów, moment pojawienia się problemu, wersję platformy .NET, nazwę używanej biblioteki, fragment logu oraz informację, czy błąd występuje lokalnie, czy tylko na wybranym stanowisku. Tak przygotowane dane skracają rozpoznanie i ograniczają ryzyko przypadkowych zmian w projekcie.

Wsparcie może być przydatne także wtedy, gdy problem dotyczy komputera, na którym przygotowywany jest projekt: uszkodzonego środowiska programistycznego, brakujących składników, niepoprawnych zmiennych systemowych, problemów z dostępem do lokalnej bazy lub konfliktu między zainstalowanymi wersjami narzędzi. Przed rozpoczęciem prac należy zabezpieczyć kod źródłowy, pliki konfiguracyjne i kopię danych. Hasła oraz klucze dostępowe powinny zostać usunięte z przekazywanych logów.

W Warszawie pomoc przy problemach ze sprzętem i środowiskiem pracy świadczy Warszawskie Pogotowie Komputerowe 24/7. Przy zgłoszeniu warto jasno wskazać, czy oczekiwane jest jedynie ustalenie przyczyny, czy również uporządkowanie konfiguracji i przygotowanie środowiska do dalszej pracy. Jeżeli problem powtarza się po każdym uruchomieniu, pojawia się na kilku projektach albo towarzyszą mu inne nieprawidłowości systemowe, szersze sprawdzenie komputera może ułatwić rozdzielenie błędu programistycznego od problemu lokalnej konfiguracji.

Nie należy ignorować ostrzeżeń o utracie danych, błędach zapisu ani niezgodności schematu z modelem. Entity Framework może poprawnie wykonywać kod, a mimo to prowadzić do niezamierzonych zmian w bazie, jeżeli mapowanie lub migracje zostały przygotowane błędnie. Najpierw powinno się zachować kopię zapasową, zebrać logi i ustalić zakres problemu, a dopiero potem modyfikować pakiety, konfigurację lub strukturę danych.