.NET nie działa z IIS

Problemy .NET z IIS zwykle dotyczą niezainstalowanego modułu ASP.NET Core Module (dla nowszych wersji .NET) lub niewłaściwie skonfigurowanej puli aplikacji w Menedżerze IIS.

Komunikat „.NET nie działa z IIS” oznacza, że aplikacja przygotowana w technologii .NET nie uruchamia się poprawnie w serwisie Internet Information Services albo działa inaczej niż podczas pracy lokalnej. Przyczyną może być brak właściwego środowiska uruchomieniowego, niezgodność wersji platformy, błędny plik konfiguracyjny, niewłaściwe uprawnienia konta puli aplikacji lub problem z przekazywaniem żądań do procesu aplikacji. Sam fakt, że projekt kompiluje się bez błędów w środowisku programistycznym, nie potwierdza jeszcze poprawnej konfiguracji IIS.

Czym jest problem „.NET nie działa z IIS”

IIS pełni rolę warstwy przyjmującej żądania HTTP i przekazującej je do aplikacji .NET. W przypadku starszych aplikacji opartych na .NET Framework część funkcji może być obsługiwana bezpośrednio przez zainstalowane składniki systemu Windows oraz rozszerzenia ASP.NET. Aplikacje tworzone dla współczesnego .NET, w tym aplikacje ASP.NET Core, wymagają natomiast odpowiedniego mechanizmu integracji z IIS. W praktyce oznacza to konieczność dopasowania hostingu do modelu publikowania konkretnego projektu.

W aplikacji ASP.NET Core żądanie często trafia przez IIS do procesu uruchamiającego aplikację. Jeżeli brakuje właściwego modułu integracyjnego, procesu nie można uruchomić albo konfiguracja wskazuje nieistniejący plik, pojawia się błąd serwera, kod 500, kod 502 lub komunikat o niedostępności usługi. Problem może wystąpić również wtedy, gdy wdrożono wyłącznie pliki projektu, pomijając wymagane zależności środowiska uruchomieniowego.

Znaczenie ma także sposób publikacji. Wdrożenie zależne od środowiska wymaga obecności odpowiedniej wersji .NET na komputerze, na którym działa IIS. Wdrożenie samodzielne zawiera większą część potrzebnych składników, ale nadal musi być zgodne z architekturą systemu, ustawieniami procesu oraz konfiguracją serwera. Dlatego diagnoza powinna obejmować zarówno samą aplikację, jak i warstwę IIS, a nie ograniczać się do ponownego uruchomienia witryny.

Kontekst techniczny i porównanie sposobów uruchamiania - .NET nie działa z IIS

W przypadku .NET Framework aplikacja może wymagać włączenia odpowiednich funkcji systemu Windows, rejestracji komponentów ASP.NET oraz poprawnego przypisania rozszerzeń plików do właściwych modułów. Jeżeli dana funkcja nie została zainstalowana, IIS może zwracać błąd jeszcze przed przekazaniem żądania do kodu aplikacji. Znaczenie ma również wersja frameworka przypisana do aplikacji oraz zgodność ustawień puli aplikacji z jej modelem działania.

ASP.NET Core działa według innego schematu. Plik web.config opisuje sposób przekazywania żądań, a moduł integracyjny IIS uruchamia aplikację lub przekazuje żądania do już działającego procesu. Brak tego modułu, nieprawidłowy wpis w konfiguracji albo publikacja do niewłaściwego katalogu może spowodować, że witryna nie odpowie mimo obecności wszystkich plików projektu. Warto rozróżnić błąd konfiguracji IIS od błędu samej aplikacji, ponieważ oba przypadki mogą wyglądać podobnie z poziomu przeglądarki.

Istotne jest też ustawienie puli aplikacji. Aplikacja oparta na .NET Framework może wymagać konkretnego trybu zarządzanego, natomiast aplikacja ASP.NET Core jest często uruchamiana z ustawieniem bez zarządzanego kodu po stronie IIS, ponieważ właściwy proces .NET działa osobno. Nie oznacza to, że każda aplikacja powinna mieć identyczne ustawienia. Należy uwzględnić typ projektu, wersję platformy, sposób publikacji i wymagania określone przez plik projektu.

Podobne objawy mogą powstać z zupełnie różnych przyczyn. Kod 500.19 zwykle kieruje uwagę na nieprawidłową konfigurację lub brak wymaganej funkcji IIS, kod 500.30 może wskazywać na nieuruchomienie aplikacji ASP.NET Core, a kod 502.5 często wiąże się z nieprawidłowym startem procesu. Sam numer błędu nie zawsze wystarcza do rozpoznania przyczyny, dlatego powinno się sprawdzić dzienniki systemowe, logi aplikacji oraz wpisy generowane przez IIS.

Typowe problemy, błędy i objawy - .NET nie działa z IIS

Jednym z częstszych problemów jest zainstalowanie niewłaściwej wersji środowiska uruchomieniowego. Projekt może być zbudowany dla określonej wersji .NET, podczas gdy na komputerze dostępna jest wyłącznie inna wersja lub tylko zestaw narzędzi programistycznych. W takiej sytuacji aplikacja może uruchamiać się na komputerze deweloperskim, ale zatrzymywać się po wdrożeniu. Pomocne jest porównanie informacji z pliku projektu, wyniku publikowania oraz listy środowisk dostępnych w systemie.

Problemy powoduje również brak lub uszkodzenie ASP.NET Core Module. Samo zainstalowanie IIS nie zapewnia wszystkich składników potrzebnych do hostowania aplikacji ASP.NET Core. Jeżeli moduł nie został dodany, jest niezgodny z architekturą albo nie został poprawnie zarejestrowany, żądania mogą kończyć się błędem przed uruchomieniem kodu aplikacji.

Nieprawidłowy plik web.config może zawierać błędną ścieżkę do pliku wykonywalnego, nieaktualną nazwę modułu, literówkę w atrybucie albo ustawienie niedopasowane do rodzaju publikacji. Warto sprawdzić, czy plik znajduje się w katalogu głównym wdrożenia i czy odwołuje się do faktycznie istniejących elementów. Ręczne kopiowanie konfiguracji z innej aplikacji często przenosi niepasujące ścieżki i ustawienia.

Kolejną grupę przyczyn stanowią uprawnienia. Tożsamość puli aplikacji musi mieć możliwość odczytu plików aplikacji, a w razie potrzeby także zapisu do katalogów używanych na pliki tymczasowe, logi lub przesyłane dane. Ograniczenia dostępu do certyfikatów, zmiennych środowiskowych albo zasobów systemowych mogą ujawniać się dopiero po rozpoczęciu obsługi konkretnego żądania.

Znaczenie mają także ustawienia systemu 32-bitowego i 64-bitowego, blokady zapory, zajęty port, nieprawidłowe powiązanie nazwy witryny oraz konflikt między kilkoma witrynami korzystającymi z tego samego adresu. W aplikacjach korzystających z połączenia z bazą danych należy dodatkowo zweryfikować łańcuch połączenia, dostępność usługi bazodanowej i sposób przechowywania sekretów. Jeżeli aplikacja działa po uruchomieniu ręcznym, ale nie przez IIS, szczególnej uwagi wymagają katalog roboczy, konto procesu i zmienne środowiskowe.

Przydatne jest włączenie logowania startu aplikacji oraz sprawdzenie Podglądu zdarzeń systemu Windows. Nie powinno się jednak pozostawiać szczegółowych komunikatów diagnostycznych dostępnych publicznie w działającej witrynie. Po ustaleniu przyczyny należy ograniczyć ekspozycję informacji o ścieżkach, konfiguracji i środowisku, a następnie ponownie uruchomić aplikację w kontrolowanych warunkach.

Kiedy trzeba zlecić diagnozę specjalistom - .NET nie działa z IIS

Zgłoszenie problemu do serwisu jest uzasadnione, gdy aplikacja przestała działać po aktualizacji systemu, zmianie wersji .NET, przeniesieniu witryny na inny komputer albo odtworzeniu danych z kopii. Wsparcie może być potrzebne także wtedy, gdy w przeglądarce pojawia się wyłącznie ogólny błąd, a brak jest dostępu do logów lub nie ma pewności, czy przyczyna leży po stronie IIS, aplikacji, uprawnień czy zależności zewnętrznych.

Przy zgłoszeniu warto przygotować adres witryny, moment wystąpienia problemu, ostatnio wykonane zmiany, dokładny komunikat błędu oraz informację, czy aplikacja działa lokalnie poza IIS. Pomocne są także fragmenty logów bez haseł, kluczy i innych danych poufnych. Dzięki temu można szybciej odtworzyć kolejność zdarzeń i sprawdzić, czy problem dotyczy uruchomienia procesu, obsługi żądania, dostępu do plików czy połączenia z inną usługą.

W Warszawie takie zgłoszenia przyjmuje Warszawskie Pogotowie Komputerowe 24/7, gdzie można przekazać sprzęt do sprawdzenia lub ustalić zakres prac związanych z konfiguracją systemu i oprogramowania. Przed rozpoczęciem naprawy powinno zostać ustalone, czy potrzebna jest korekta ustawień IIS, instalacja brakujących składników, odtworzenie praw dostępu, poprawienie publikacji, czy analiza samej aplikacji .NET.

Nie zaleca się przypadkowego usuwania plików konfiguracyjnych, wielokrotnego instalowania różnych wersji środowiska ani nadawania szerokich uprawnień wszystkim użytkownikom. Takie działania mogą utrudnić ustalenie pierwotnej przyczyny i zwiększyć ryzyko ujawnienia danych. Bezpieczniejszym podejściem jest wykonanie kopii konfiguracji, zebranie logów, sprawdzenie zgodności wersji i wprowadzanie zmian pojedynczo, z potwierdzeniem efektu po każdej korekcie.