IIS’te MIME Type Ekleme ve Yönetimi

Yazar:komut.io ekibi
0 Yorum

Bir müşterinin web sitesinde “bu dosya tipi desteklenmiyor” hatası alması ve bunun nedenini bulmak için saatlerce uğraşmak… IIS yönetiyorsanız bu durumu muhtemelen yaşadınız. Sorunun cevabı çoğu zaman basit: eksik MIME type tanımı. Ama bu basit sorunun çözümü, eğer doğru bilmiyorsanız, sizi birkaç saatlik debug seansına sürükleyebilir.

Bu yazıda IIS’te MIME type yönetimini her açıdan ele alacağız. IIS Manager arayüzünden komut satırına, PowerShell’den web.config dosyasına kadar her yöntemi gerçek senaryolarla açıklayacağız.

MIME Type Nedir ve Neden Önemlidir?

MIME (Multipurpose Internet Mail Extensions) type, bir dosyanın içeriğinin ne olduğunu tarayıcıya ve diğer istemcilere bildiren bir tanımlayıcıdır. text/html, application/json, image/svg+xml gibi değerler MIME type örnekleridir.

IIS, varsayılan olarak bilinen dosya uzantılarını sunabilir. Ancak .woff2, .webmanifest, .br gibi nispeten yeni uzantılar veya özel uygulama dosyaları söz konusu olduğunda IIS bunları tanımaz ve istemciye 404 hatası döndürür. Hatta bazı durumlarda dosya fiziksel olarak sunucuda var olmasına rağmen bu hatayı alırsınız. Bu da debug sürecini oldukça kafa karıştırıcı hale getirir.

IIS’in bu davranışı aslında güvenlik odaklıdır. Tanımlanmamış bir dosya tipini varsayılan olarak reddetmek, sunucuda hassas dosyaların yanlışlıkla açığa çıkmasını engeller. Ama bu güvenlik mekanizması, meşru dosyalar için de devreye girdiğinde sorun yaratır.

IIS’in Varsayılan MIME Type Listesi

IIS kurulduğunda oldukça geniş bir MIME type listesiyle gelir. HTML, CSS, JavaScript, yaygın resim formatları, PDF gibi tipler zaten tanımlıdır. Ama modern web geliştirmenin ihtiyaçları bu listeyi aşmaktadır.

Mevcut MIME type listesini kontrol etmek için PowerShell kullanabilirsiniz:

Import-Module WebAdministration
Get-WebConfiguration system.webServer/staticContent/* | 
    Select-Object fileExtension, mimeType | 
    Sort-Object fileExtension

Bu komut size sunucu genelinde tanımlı tüm MIME type’ları listeler. Belirli bir site için kontrol etmek istiyorsanız:

Get-WebConfiguration system.webServer/staticContent/* -PSPath "IIS:SitesSiteAdiniz" | 
    Select-Object fileExtension, mimeType

Uzantı bazlı hızlı arama yapmak için:

Get-WebConfiguration system.webServer/staticContent/* | 
    Where-Object { $_.fileExtension -eq ".woff2" }

Eğer bu sorgu sonuç dönmüyorsa, o uzantı tanımlı değil demektir.

IIS Manager ile MIME Type Ekleme

Grafik arayüz üzerinden MIME type eklemek en basit yöntemdir. Özellikle tek seferlik değişiklikler için tercih edilebilir.

Sunucu genelinde MIME type eklemek için:

  • IIS Manager’ı açın
  • Sol panelde sunucu adına tıklayın (site değil, sunucu kökü)
  • Orta panelde “MIME Types” ikonuna çift tıklayın
  • Sağ panelde “Add…” linkine tıklayın
  • File name extension alanına uzantıyı girin (örn: .woff2)
  • MIME type alanına karşılık gelen değeri girin (örn: font/woff2)
  • OK ile kaydedin

Belirli bir site için MIME type eklemek istiyorsanız sunucu adı yerine ilgili siteyi seçerek aynı adımları izleyin. Site seviyesindeki tanımlar sunucu genelini ezmez, sadece o site için geçerli olur.

PowerShell ile MIME Type Yönetimi

Üretime birden fazla sunucu yönetiyorsanız, IIS Manager ile tek tek uğraşmak zaman kaybıdır. PowerShell ile bu işlemleri otomatize etmek hem hızlı hem de tekrarlanabilir bir yöntem sunar.

Yeni MIME type eklemek:

Add-WebConfigurationProperty -PSPath "MACHINE/WEBROOT/APPHOST" `
    -Filter "system.webServer/staticContent" `
    -Name "." `
    -Value @{fileExtension='.woff2'; mimeType='font/woff2'}

Bu komut sunucu genelinde (MACHINE/WEBROOT/APPHOST) MIME type ekler. Belirli bir site için eklemek istiyorsanız:

Add-WebConfigurationProperty -PSPath "IIS:SitesSiteAdiniz" `
    -Filter "system.webServer/staticContent" `
    -Name "." `
    -Value @{fileExtension='.webmanifest'; mimeType='application/manifest+json'}

Var olan bir MIME type’ı güncellemek:

Bazen IIS’in varsayılan listesinde yanlış veya eski bir MIME type tanımı olabilir. Örneğin eski IIS sürümlerinde .js için text/javascript yerine application/x-javascript tanımlı olabilir. Güncellemek için:

Set-WebConfigurationProperty -PSPath "MACHINE/WEBROOT/APPHOST" `
    -Filter "system.webServer/staticContent/mimeMap[@fileExtension='.js']" `
    -Name "mimeType" `
    -Value "text/javascript"

MIME type silmek:

Remove-WebConfigurationProperty -PSPath "MACHINE/WEBROOT/APPHOST" `
    -Filter "system.webServer/staticContent" `
    -Name "." `
    -AtElement @{fileExtension='.uzanti'}

Toplu MIME type ekleme:

Birden fazla MIME type ekleyecekseniz bu işlemi bir fonksiyon haline getirin:

function Add-MimeType {
    param(
        [string]$Extension,
        [string]$MimeType,
        [string]$SitePath = "MACHINE/WEBROOT/APPHOST"
    )
    
    $existing = Get-WebConfigurationProperty `
        -PSPath $SitePath `
        -Filter "system.webServer/staticContent/mimeMap[@fileExtension='$Extension']" `
        -Name "mimeType" -ErrorAction SilentlyContinue
    
    if ($existing) {
        Write-Host "$Extension zaten tanımlı: $existing" -ForegroundColor Yellow
    } else {
        Add-WebConfigurationProperty -PSPath $SitePath `
            -Filter "system.webServer/staticContent" `
            -Name "." `
            -Value @{fileExtension=$Extension; mimeType=$MimeType}
        Write-Host "$Extension eklendi: $MimeType" -ForegroundColor Green
    }
}

# Kullanımı
$mimeTypes = @(
    @{Extension='.woff'; MimeType='font/woff'},
    @{Extension='.woff2'; MimeType='font/woff2'},
    @{Extension='.webmanifest'; MimeType='application/manifest+json'},
    @{Extension='.br'; MimeType='application/x-brotli'},
    @{Extension='.gz'; MimeType='application/x-gzip'},
    @{Extension='.avif'; MimeType='image/avif'},
    @{Extension='.webp'; MimeType='image/webp'}
)

foreach ($mime in $mimeTypes) {
    Add-MimeType -Extension $mime.Extension -MimeType $mime.MimeType
}

Bu script, önce uzantının tanımlı olup olmadığını kontrol eder. Eğer tanımlıysa uyarı verir, değilse ekler. Böylece “already exists” hatasıyla karşılaşmazsınız.

web.config ile MIME Type Yönetimi

Uygulama seviyesinde MIME type yönetimi için en taşınabilir ve versiyon kontrol dostu yöntem web.config dosyasını kullanmaktır. Özellikle uygulamanızı CI/CD pipeline’ı ile deploy ediyorsanız bu yöntem altın değerinde.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <staticContent>
      <!-- Modern font formatları -->
      <mimeMap fileExtension=".woff" mimeType="font/woff" />
      <mimeMap fileExtension=".woff2" mimeType="font/woff2" />
      
      <!-- PWA için gerekli -->
      <mimeMap fileExtension=".webmanifest" mimeType="application/manifest+json" />
      
      <!-- Modern resim formatları -->
      <mimeMap fileExtension=".avif" mimeType="image/avif" />
      <mimeMap fileExtension=".webp" mimeType="image/webp" />
      
      <!-- Sıkıştırılmış dosyalar -->
      <mimeMap fileExtension=".br" mimeType="application/x-brotli" />
    </staticContent>
  </system.webServer>
</configuration>

Ancak dikkat edilmesi gereken bir nokta var: Eğer bir uzantı sunucu genelinde zaten tanımlıysa ve siz site seviyesinde aynı uzantıyı farklı bir MIME type ile tanımlamak istiyorsanız, önce mevcut tanımı kaldırmanız gerekir:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <staticContent>
      <!-- Önce mevcut tanımı kaldır, sonra yenisini ekle -->
      <remove fileExtension=".json" />
      <mimeMap fileExtension=".json" mimeType="application/json" />
    </staticContent>
  </system.webServer>
</configuration>

Bu pattern özellikle IIS’in eski sürümlerinde .json için text/json gibi eski tanımların üzerine yazmanız gerektiğinde işe yarar.

Appcmd ile MIME Type Yönetimi

Bazı ortamlarda PowerShell kullanımı kısıtlı olabilir veya eski script’lerle uyumluluk gerekebilir. Bu durumda appcmd.exe kullanabilirsiniz:

cd %SystemRoot%System32inetsrv

# MIME type eklemek
appcmd set config /section:staticContent /+[fileExtension='.woff2',mimeType='font/woff2']

# Belirli bir site için
appcmd set config "SiteAdiniz" /section:staticContent /+[fileExtension='.avif',mimeType='image/avif']

# Var olan MIME type'ı listelemek
appcmd list config /section:staticContent

# MIME type kaldırmak
appcmd set config /section:staticContent /-[fileExtension='.woff2']

Gerçek Dünya Senaryoları

Senaryo 1: SPA (Single Page Application) Deploy Sonrası 404 Hataları

React, Angular veya Vue ile geliştirilmiş bir uygulama deploy ettiniz. Uygulama açılıyor ama bazı asset’ler yüklenmiyor. Browser konsolunda net::ERR_ABORTED 404 hataları görüyorsunuz.

Bu durumun sık rastlanan nedeni, build araçlarının ürettiği .webmanifest dosyası veya source map dosyalarıdır. IIS bu uzantıları tanımadığı için 404 döndürür.

Çözüm olarak site klasörünüzdeki web.config dosyasına şunları ekleyin:

<staticContent>
  <mimeMap fileExtension=".webmanifest" mimeType="application/manifest+json" />
  <mimeMap fileExtension=".map" mimeType="application/json" />
  <remove fileExtension=".json" />
  <mimeMap fileExtension=".json" mimeType="application/json" />
</staticContent>

Senaryo 2: Web Font Yükleme Sorunları

Site tasarımı doğru görünmüyor, fontlar yüklenmiyor. Browser developer tools’da network sekmesine baktığınızda font dosyaları için 404 hatası görüyorsunuz.

Modern web fontları üç format kullanır: .woff, .woff2 ve bazen .eot. IIS’in yeni kurulumlarında .woff2 çoğu zaman eksik olur:

# PowerShell ile kontrol ve ekleme
$fontsToAdd = @(
    @{Extension='.eot'; MimeType='application/vnd.ms-fontobject'},
    @{Extension='.ttf'; MimeType='font/ttf'},
    @{Extension='.woff'; MimeType='font/woff'},
    @{Extension='.woff2'; MimeType='font/woff2'},
    @{Extension='.otf'; MimeType='font/otf'}
)

foreach ($font in $fontsToAdd) {
    $check = Get-WebConfigurationProperty `
        -PSPath "MACHINE/WEBROOT/APPHOST" `
        -Filter "system.webServer/staticContent/mimeMap[@fileExtension='$($font.Extension)']" `
        -Name "mimeType" -ErrorAction SilentlyContinue
    
    if (-not $check) {
        Add-WebConfigurationProperty -PSPath "MACHINE/WEBROOT/APPHOST" `
            -Filter "system.webServer/staticContent" `
            -Name "." `
            -Value @{fileExtension=$font.Extension; mimeType=$font.MimeType}
        Write-Host "Eklendi: $($font.Extension)" -ForegroundColor Green
    }
}

Senaryo 3: API Endpoint’inden JSON Döndürme Sorunu

IIS üzerinde barındırdığınız bir API, JSON içerik döndürmesi gerekirken hata veriyor. Bu genellikle statik JSON dosyaları için geçerlidir. Dinamik API’lar için bu sorun farklı bir katmanda çözülür ama statik JSON dosyaları sunuyorsanız:

<staticContent>
  <remove fileExtension=".json" />
  <mimeMap fileExtension=".json" mimeType="application/json" />
</staticContent>

remove satırı kritik öneme sahiptir. Eğer sunucu genelinde .json tanımlıysa ve siz sadece mimeMap eklerseniz “duplicate entry” hatası alırsınız.

MIME Type Tanımlarında Sık Yapılan Hatalar

Hata 1: Uzantıya nokta koymayı unutmak

MIME type eklerken uzantıyı .woff2 şeklinde, başında nokta ile yazmalısınız. woff2 şeklinde yazarsanız IIS onu tanımaz.

Hata 2: Büyük-küçük harf duyarlılığını göz ardı etmek

Windows dosya sistemi büyük-küçük harf duyarsız olsa da MIME type tanımlarında bu bazen sorun yaratabilir. .SVG ve .svg farklı uzantılar olarak tanımlanabilir. Dosya uzantılarınızı küçük harfle standartlaştırmak iyi bir pratiktir.

Hata 3: Sunucu geneli ile site genelini karıştırmak

Bir MIME type’ı site seviyesinde eklediğinizde sadece o site için geçerlidir. Aynı sunucudaki diğer siteler etkilenmez. Bunu bilerek kullanmak güçlü bir özelliktir ama farkında olmadan yapılırsa kafa karışıklığı yaratır.

Hata 4: Değişiklikleri test etmemek

MIME type ekledikten sonra değişikliği doğrulamak için tarayıcı önbelleğini temizlemeyi unutmayın. Tarayıcı eski yanıtı önbellekten sunuyor olabilir ve değişikliğinizin etkisini göremeyebilirsiniz.

Toplu MIME Type Raporu Oluşturma

Birden fazla sunucu yönetiyorsanız, her sunucunun MIME type konfigürasyonunu karşılaştırmak isteyebilirsiniz. Bunun için basit bir rapor script’i:

$servers = @("WebSunucu01", "WebSunucu02", "WebSunucu03")
$reportPath = "C:RaporlarMimeTypeRaporu_$(Get-Date -Format 'yyyyMMdd').csv"

$results = @()

foreach ($server in $servers) {
    $session = New-PSSession -ComputerName $server
    
    $mimeTypes = Invoke-Command -Session $session -ScriptBlock {
        Import-Module WebAdministration
        Get-WebConfiguration system.webServer/staticContent/* | 
            Select-Object fileExtension, mimeType
    }
    
    foreach ($mime in $mimeTypes) {
        $results += [PSCustomObject]@{
            Sunucu = $server
            Uzanti = $mime.fileExtension
            MimeType = $mime.mimeType
        }
    }
    
    Remove-PSSession $session
}

$results | Export-Csv -Path $reportPath -NoTypeInformation -Encoding UTF8
Write-Host "Rapor oluşturuldu: $reportPath"

Bu script’i çalıştırdığınızda sunucular arasındaki farklılıkları kolayca görebilirsiniz.

Sık İhtiyaç Duyulan MIME Type Listesi

Modern web projelerinde sıklıkla karşılaşılan ve varsayılan IIS kurulumunda eksik olabilen MIME type’lar:

  • .woff: font/woff – Web Open Font Format
  • .woff2: font/woff2 – Web Open Font Format 2
  • .webmanifest: application/manifest+json – PWA manifest dosyası
  • .avif: image/avif – AV1 Image File Format
  • .webp: image/webp – WebP resim formatı
  • .br: application/x-brotli – Brotli sıkıştırılmış dosyalar
  • .gz: application/x-gzip – Gzip sıkıştırılmış dosyalar
  • .svg: image/svg+xml – Scalable Vector Graphics
  • .ico: image/x-icon – Icon dosyası
  • .map: application/json – Source map dosyaları
  • .geojson: application/geo+json – GeoJSON dosyaları
  • .otf: font/otf – OpenType Font
  • .ttf: font/ttf – TrueType Font

Sonuç

IIS’te MIME type yönetimi ilk bakışta sıradan bir konfigürasyon görevi gibi görünür ama yanlış yapıldığında ya da göz ardı edildiğinde ciddi sorunlara yol açabilir. “Dosya var ama 404 alıyorum” durumunun temel nedenlerinden biri budur.

Bu yazıda anlattığımız yöntemleri özetlemek gerekirse: Hızlı ve tek seferlik değişiklikler için IIS Manager arayüzü yeterlidir. Otomasyona ihtiyaç duyuyorsanız PowerShell tercih edin. Uygulamanız bir deployment sürecinden geçiyorsa MIME type konfigürasyonunu web.config dosyasına ekleyin, böylece her deploy’da tutarlı bir konfigürasyon garantilenmiş olur.

En önemli tavsiyem şu: Yeni bir IIS kurulumu yaptığınızda veya yeni bir web uygulaması yayına aldığınızda, modern web ihtiyaçlarına uygun temel MIME type’larını baştan tanımlayın. Sorun çıktıktan sonra debug etmek yerine proaktif olmak, hem sizin hem de kullanıcıların zamanını korur.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir