UI5 Fiori 6 dakika okuma

Freestyle SAPUI5 + Node.js Projesini Local IIS'te Çalıştırma Rehberi

iisnode ile Node.js backend'i Windows IIS'te ayağa kaldırırken çıkan yanıltıcı hatalar (node.exe bulunamıyor sanılan gerçek kök neden dahil) ve çözümleri

05 Eylül 2026 142 görüntülenme
Paylaş:
Freestyle SAPUI5 + Node.js Projesini Local IIS'te Çalıştırma Rehberi
Merhaba Değerli Okuyucularım,

.NET projelerinde IIS + ASP.NET Core Module akışına alışkınsanız, Node.js için iisnode kullanmak sizi birkaç yanıltıcı hatayla karşılaştırır. Bir Freestyle SAPUI5 + Express projesini kurarken çıkan sorunlar ve gerçek çözümleri.

Mimari Farkı
.NET Core'da IIS, arka planda çalışan Kestrel sunucusuna reverse proxy yapar — tanıdık bir akış. Node.js'te iisnode bambaşka çalışır: IIS'in worker process'i (w3wp.exe) node.exe'yi doğrudan bir alt süreç olarak başlatır ve named pipe üzerinden konuşur. Aşağıdaki sorunların çoğunun kök nedeni bu fark.

Proje Yapısı
Tipik bir Freestyle SAPUI5 + Node projesinde kökte index.html yoktur, bu yüzden proje kökü tek bir IIS site'ına verilemez. Frontend ve backend ayrı site olarak tanımlanmalı, her iki Application Pool'da da .NET CLR version = No Managed Code seçilmeli.

BileşenPhysical PathÖrnek Port
Frontend (webapp)...\webapp5012
Backend (Node/Express)...\backend3000

Ön koşul olarak URL Rewrite Module ve iisnode kurulu olmalı.

Frontend Sorunları

403.14 — Forbidden

Site'ın Physical Path'i proje köküne ayarlanmıştı; index.html orada değil webapp/ içinde. Çözüm: Physical Path'i webapp/'e çevirmek.

.properties dosyaları 404 dönüyor

Ekranda çeviri metinleri yerine ham i18n anahtarları görünüyorsa, IIS'in bilinmeyen dosya uzantılarını (.properties) varsayılan olarak reddetmesi sorumludur. fiori run geliştirme sunucusu bu kısıtlamayı uygulamadığı için sorun daha önce fark edilmemiş olur.

Backend (iisnode) Sorunları

Rewrite kuralı mantığı: Path bazlı ayrım yapmaya çalışmak yerine tüm istekleri server.js'e yönlendirip yönlendirmeyi tamamen Express'in routing'ine bırakmak — sadece /api/* gibi dar bir kural, /health türü diğer route'ları 404'e düşürür.

Not:

500.1000 / 500.1002 hataları, aslında "node.exe bulunamıyor" değildi. Tam yol tanımlamak, tırnaklamak veya 8.3 kısa yol kullanmak tek başına çözmüyordu. Kesin teşhis: backend/iisnode/ log klasörü otomatik oluşmuyorsa, node.exe hiç başlatılamıyor demektir. Application Pool Identity'nin bu klasörü kendi başına oluşturma izni olmayabilir — klasör yoksa log açılamaz, bu da node sürecinin tümden ölmesine yol açar. 

Çözüm: backend/iisnode/ klasörünü elle, önceden oluşturmak.

Port uyumluluğu

iisnode, port bilgisini named pipe üzerinden process.env.PORT ile iletir. Sabit port kullanan kod (app.listen(3000)) iisnode altında çalışmaz:

const PORT = process.env.PORT || 3000;
app.listen(PORT, ...);

.env dosyasında PORT=3000 gibi bir satır sorun oluşturmaz — dotenv, process.env'de zaten tanımlı bir değişkenin üzerine varsayılan olarak yazmaz.

Sırasıyla Şu İşlemleri Yapalım

UI5/Fiori projenizi C:\inetpub\wwwroot dosya yolu altında isterseniz bir klasör oluşturup içine kopyalayabilir, isterseniz doğrudan inetpub klasörüne kopyalayabilirsiniz.

URL Rewrite Module Kurulumu: https://www.iis.net/downloads/microsoft/url-rewrite sitesinden uygun dil paketinize göre dosyayı indirip kurunuz.

URL Rewrite Module Kurulumu
IIS Node Kurulumu: https://github.com/tjanczuk/iisnode/releases adresinden güncel kurulum paketini indirip kurunuz.
IIS Node Kurulumu
webapp klasörü altında web.config dosyasını oluşturup alt kısımdaki kodları uyguluyoruz.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <system.webServer>
        <staticContent>
            <mimeMap fileExtension=".properties" mimeType="text/plain" />
            <!-- yaml/json gibi diger olasi eksik MIME type'lar icin onceden ekleniyor, ileride sorun cikarmasin -->
            <mimeMap fileExtension=".yaml" mimeType="text/yaml" />
            <mimeMap fileExtension=".webmanifest" mimeType="application/manifest+json" />
        </staticContent>
    </system.webServer>
</configuration>

Backend klasörü altında web.config dosyasını oluşturup alt kısımdaki kodları uyguluyoruz.

Benim bilgisayarımda Node.js C:\Program Files\nodejs yolunda kurulu. Bu yoldaki node.exe çalıştırılabilir dosyasını nodeProcessCommandLine parametresine tanımlıyoruz. Fakat yolda boşluk (Program Files) bulunduğu için &quot; ile tırnaklamayı unutmayalım, aksi halde iisnode yolu doğru parse edemez:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add name="iisnode" path="server.js" verb="*" modules="iisnode" responseBufferLimit="0" />
        </handlers>
        <rewrite>
            <rules>
                <rule name="node_modules erisimini engelle" stopProcessing="true">
                    <match url="^node_modules\/.*" />
                    <action type="CustomResponse" statusCode="403" statusReason="Forbidden" statusDescription="Erisim engellendi" />
                </rule>
                <rule name="db klasoru erisimini engelle" stopProcessing="true">
                    <match url="^db\/.*" />
                    <action type="CustomResponse" statusCode="403" statusReason="Forbidden" statusDescription="Erisim engellendi" />
                </rule>
                <rule name="iisnode klasoru erisimini engelle" stopProcessing="true">
                    <match url="^iisnode\/.*" />
                    <action type="CustomResponse" statusCode="403" statusReason="Forbidden" statusDescription="Erisim engellendi" />
                </rule>
                <rule name="Tum istekleri Node'a yonlendir" stopProcessing="true">
                    <match url="^(?!node_modules|db|iisnode).*" />
                    <action type="Rewrite" url="server.js" />
                </rule>
            </rules>
        </rewrite>
        <!--
        iisnode ayarlari. nodeProcessCommandLine, node.exe'nin tam yoluna ayarlandi cunku IIS
        worker process (w3wp.exe) Application Pool Identity altinda calisiyor - bu kullanicinin
        PATH ortam degiskeninde Node.js kurulu dizini yer almiyor, "node" komutu bulunamiyordu
        (0x00000057 / ERROR_INVALID_PARAMETER hatasinin sebebiydi).
        Yol icinde bosluk oldugu icin (Program Files) &quot; ile ic tirnak icine alindi - aksi
        halde komut satiri "Program" ve "Files\nodejs\node.exe" olarak iki ayri parametreye
        bolunup gecersiz parametre hatasi verirdi.
        -->
        <iisnode
            nodeProcessCommandLine="&quot;C:\Program Files\nodejs\node.exe&quot;"
            loggingEnabled="true"
            logDirectory="iisnode"
            devErrorsEnabled="false"
            watchedFiles="*.js;iisnode.yml"
            />
        </system.webServer>
    </configuration>

.properties mime türü eklendi mi?

IIS varsayılan olarak yalnızca kendi tanıdığı (statik olarak IIS/web.config'e kayıtlı) dosya uzantılarını sunar; .properties bu listede olmadığı için IIS o dosyayı hiç okumadan direkt 404 döndürür — dosya diskte fiziksel olarak var olsa bile.

SAPUI5'in i18n çeviri dosyaları (i18n.properties, i18n_tr.properties vb.) bu uzantıyı kullanır. mimeMap satırı IIS'e "bu uzantıyı da tanı, text/plain içerik tipiyle servis et" der.


Backend - Fronted Application Pool "No Managed Code" mu?

IIS üzerinde frontend ve backend için ayrı site oluşturuyoruz. Dikkat edilmesi gereken nokta, ikisinin physical path'inin farklı olmasıdır: frontend için proje içindeki webapp klasörü, backend için proje içindeki backend klasörü referans gösterilir.

SayımX projemde frontend için 5012, backend için 3000 portlarını kullandım.

Not: SayımX projesi üzerinde çalışmam sürdüğü için sayimx ve sayimx_backend IIS site'larını şu an durdurdum; sizde bunlar aktif olarak çalışır durumda kalacak.

Ayrıca VS Code veya başka bir editörden npm run dev / npm start ile projeyi ayrıca çalıştırırsanız ve bu komutlar IIS'teki site ile aynı portu kullanıyorsa port çakışması hatası alırsınız. Bunun önüne geçmek için iki seçenekten birini uygulayın:

  • IIS'teki ilgili site'ı geçici olarak durdurun, veya
  • Projenizdeki portları geçici süreliğine değiştirin.


Sonrasında Uygulama Havuzları (Application Pools) kısmından gerekli düzenlemeleri yaptım. Her iki site için de ilgili Application Pool'u seçip .NET CLR Sürümü ayarını "Yönetilen Kod Yok" (No Managed Code) olarak değiştirdim.

  • backend klasöründe iisnode adında boş bir klasör oluşturunuz.
  • CMD'yi yönetici modda çalıştırıp şu komutu yazalım.  iisreset


Tüm Makalelere Dön
Muhammed AKTEPE